hermes-hub-project

hermes-hub-project is a BMAD-style initializer and tenant-safe command-line client for repositories that work with Hermes Hub.

npx hermes-hub-project init

The initializer adds:

• .hermes-hub/PROJECT.md — the concise starting point for humans and agents;
• .hermes-hub/reference/ — a versioned local snapshot of the public Hermes Hub REST contract and LLM-oriented documentation;
• .hermes-hub/project.json — committable, non-secret Hub/tenant binding;
• .agents/skills/hermes-hub/SKILL.md for Codex-compatible tools;
• .claude/skills/hermes-hub/SKILL.md and a Cursor rule when selected;
• a small managed block in the repository AGENTS.md; and
• .hermes-hub/manifest.json, which records owned files and template version.

The bundled OpenAPI file is the complete public Hermes Hub contract, so it also documents control-plane endpoints. The generated project CLI intentionally exposes only tenant-scoped chat and run operations; the presence of an endpoint in the reference does not grant access or make it part of this CLI's safe command set.

Re-run init, or use update, to refresh managed context. Existing project configuration and text outside the marked AGENTS.md block are preserved.

Non-interactive setup

npx hermes-hub-project init . --yes \
  --base-url https://hub.example.com \
  --tenant tenant_123 \
  --tools codex,claude,cursor

Set the tenant API key only in the environment:

export HERMES_HUB_TOKEN='...'
export HERMES_HUB_URL='https://hub.example.com'
npx hermes-hub-project doctor

Tokens are not accepted as command-line flags and are never written to project files or output.

Tenant tools

npx hermes-hub-project chat new "Summarize the current company context"
npx hermes-hub-project chat send "Now turn that into an action plan"
npx hermes-hub-project chat list
npx hermes-hub-project chat history
npx hermes-hub-project chat message wait MESSAGE_ID
npx hermes-hub-project chat message watch MESSAGE_ID --jsonl

npx hermes-hub-project flavor eval suites --json
npx hermes-hub-project flavor eval submit SUITE_ID --json
npx hermes-hub-project flavor eval list --status running --jsonl
npx hermes-hub-project flavor eval get EVAL_RUN_ID --json
npx hermes-hub-project flavor eval wait EVAL_RUN_ID --timeout 30m --jsonl
npx hermes-hub-project flavor eval cancel EVAL_RUN_ID --json

npx hermes-hub-project run start "Summarize the current company context" --follow
npx hermes-hub-project run get RUN_ID
npx hermes-hub-project run watch RUN_ID
npx hermes-hub-project run stop RUN_ID
npx hermes-hub-project docs workspace

chat new creates and selects a persistent tenant chat. chat use CHAT_ID selects an existing chat, and later chat send/chat history commands use that selection. The selection is stored in the gitignored local file .hermes-hub/current-chat.json; it contains no credential. Sending waits for a terminal result by default. --async returns the durable message immediately, and --timeout limits only the local wait—it does not cancel remote work.

Use --stdin for multiline content, --idempotency-key when retrying a send, and --jsonl for streaming or agent-oriented processing. Chat messages use a simple parts payload while Hub handles the underlying A2A session and task details.

Chat event watch is resumable: the CLI preserves SSE revision IDs, reconnects after a nonterminal disconnect, and accepts --after-revision N for a new process. Hub emits chat.message events with the durable state in data.toState. Chat stop and approval routes currently return 409 until Hub persists runtime-run correlation, so they are not working automation controls.

flavor eval can run only the suites installed with the tenant's currently pinned flavor. The CLI never accepts a flavor ID or version override. Hub owns runner availability and tenant isolation; unavailable runners or unpinned tenants fail instead of producing a local simulation. eval get and eval wait return sanitized task reports that can be redirected to local JSON or JSONL. Server-local artifact paths and credentials are not downloadable through this tenant facade.

run start --body @request.json preserves access to runtime-specific request fields without pretending that the pass-through Hermes Agent payload has a fixed schema.

Security boundary

This package is intentionally not a Hub admin CLI. It uses tenant-scoped API credentials for chat and native runs. It does not offer tenant file or company-context writes because those Hub endpoints currently require a control-plane bearer. A future context-sync command needs a dedicated, tenant-scoped, versioned context API first.

The committed project descriptor may suggest a Hub URL, but credentials are sent only when the operator explicitly sets HERMES_HUB_URL. This prevents a cloned repository from redirecting an ambient token to an attacker-controlled host.

Development

cd clients/npm
npm run sync-reference
npm test
npm pack

Publishing to npm is a separate release action and is not performed by the repository build.