Agent HQ

Deploy the Agent HQ mission-control stack (Express + React + Telegram notifier / Jarvis summary) so other Clawdbot teams can spin up the same board, high-priority watcher, and alert automation. Includes setup, telemetry, and automation hooks.

Security Scan

The SKILL.md describes a plausible mission-control app, but it instructs you to clone and run external code and to supply sensitive tokens that are not declared in the skill metadata, creating provenance and secret-exposure concerns.

Purpose & Capability

The described functionality (Express + React UI, Telegram notifier, Jarvis summary, SQLite DB, cron jobs) matches the skill name and description. However, the runtime instructions reference repository code and configuration values (bot token, chatId, API token) that the registry metadata does not declare, so the manifest and the runtime requirements are not fully aligned.

Instruction Scope

SKILL.md directs cloning an external GitHub repo and running its Node scripts, editing a local config file with secrets, and configuring cron jobs that will run notifier/summary scripts on a schedule. Those instructions cause the agent or user environment to execute code fetched at runtime and to persist secrets and periodic network activity (Telegram messages). The instructions do not insist you inspect code before running or provide safe defaults for secret handling.

Install Mechanism

There is no formal install spec in the registry, but the instructions require 'git clone' of an external GitHub repository and running 'npm install' and 'npm run build' — i.e., arbitrary third-party code will be written to disk and executed. Cloning from GitHub is common, but the skill metadata lists 'Source: unknown' (no provenance) which increases risk; the registry should either host or document provenance of the repository.

Credentials

The SKILL.md expects sensitive values (AGENT_HQ_TELEGRAM_TOKEN / AGENT_HQ_TELEGRAM_CHAT_ID and AGENT_HQ_API_TOKEN or config/telegram.json) but the skill's declared metadata lists no required environment variables or primary credential. That mismatch hides the need for secrets and makes it easy to accidentally store tokens insecurely. The number and type of secrets requested are proportionate to the described feature (Telegram, protected endpoints), but they should be declared and handled explicitly.

Persistence & Privilege

The skill is not force-enabled (always:false) and does not request platform-level privileges. However, instructions explicitly tell you to configure cron jobs and run background notifier/summary scripts, which create persistent behavior (scheduled outbound network activity). This persistence is expected for a notifier but raises usual operational/privacy considerations and should be opted into only after code inspection.

What to consider before installing

Before installing or running this skill: (1) Treat the GitHub repo as untrusted until you inspect it — review scripts (scripts/jarvis-connector.js, notify-jarvis-telegram.js, backend/server.js) for what network endpoints they call and what secrets they log or transmit. (2) Do not paste tokens into a repo or leave config/telegram.json world-readable; prefer environment variables or a secrets manager. (3) Because the registry metadata lists no required env vars, explicitly verify and document which secrets are needed and why. (4) Run the system in an isolated/test environment first (not on production machines) to observe cron/notification behavior. (5) Use minimal-permission Telegram bot tokens and rotate them after testing. (6) If you need higher assurance, ask the publisher for provenance (signed releases, exact commit/tag), or require the skill to include an install spec with vetted release artifacts.

Agent HQ Installation

Summary

• Backend + frontend: Express API with SQLite board + Vite/React UI served from frontend-react/dist.
• Automation pieces: Jarvis summary (scripts/jarvis-connector.js), Telegram notifier (scripts/notify-jarvis-telegram.js + cron), plus a high-priority watcher inside backend/server.js.
• Data: data/board.json seeds missions/agents/cards; the board persists in data/mission.db.
• Notifications: config/telegram.json (or AGENT_HQ_TELEGRAM_* env vars) lets you send alerts to Telegram.

Setup steps

1. Clone the repo and install deps:

   git clone https://github.com/thibautrey/agent-hq.git
   cd agent-hq
   npm install
   npm --prefix frontend-react install
   

2. Edit config/telegram.json with your botToken/chatId (or set AGENT_HQ_TELEGRAM_TOKEN/AGENT_HQ_TELEGRAM_CHAT_ID). Keep this file secret.
3. Build the UI and start the server:

   npm --prefix frontend-react run build
   npm run start:agent-hq
   

   The UI is served on / and the API lives under /api (default port 4000).
4. Configure cron jobs (Heartbeats + Telegram):
   • Jarvis summary: node scripts/jarvis-connector.js or scripts/notify-jarvis-telegram.js --force as needed.
   • Telegram notifier cron (see run-telegram-notifier.sh).
5. Use the UI to create cards or POST /api/cards//api/cards/quick to keep Jarvis busy.

Runtime commands

• View board: curl http://localhost:4000/api/board
• Trigger Telegram alert: curl -X POST http://localhost:4000/api/notify-telegram
• Quick card: curl -X POST http://localhost:4000/api/cards/quick -H "Content-Type: application/json" -d '{"text":"Design review needed"}'
• Jarvis summary: node scripts/jarvis-connector.js

Tips

• Drop cards directly into data/board.json before first run for a seeded mission.
• high_priority_jobs table in SQLite prevents duplicate Telegram alerts.
• AGENT_HQ_API_TOKEN protects mutating endpoints for scripted integrations.

Release notes

• 2026-02-09 – Mission-control stack created, README translated to English, changelog added, and the Clawdhub installer skill agent-hq@1.0.0 published (now mirrored with this manifest).

Enjoy running your own Mission Control.