hSUM / docs 0.1.0-alpha.4 / connect an agent

Connect an agent

Codex gets one user-wide hSUM registration that resolves each task to its exact trusted repository. Other clients keep the explicit, binding-pinned MCP configuration path.

Codex: install once, use in every task

hsum integration install codex --activate . --confirm
hsum integration status codex --json

The install command uses Codex's supported mcp add/get CLI, reads the effective registration back, launches that exact server command, verifies all four read-only tools, and completes an evidence_search to evidence_get citation round trip. It also installs a bounded managed block in Codex's user-global agent instructions so future agents know when to call hSUM. No copied TOML or Codex restart is required.

Every later Codex task in this repository sees hSUM automatically. In another repository the first tool call returns a structured activation request with the exact repository root and command. After repository-specific consent, the agent can activate that repository and retry the same tool without restarting MCP.

Many repositories

hsum integration authorize-workspace codex --path ~/Projects --confirm
hsum integration revoke-workspace codex --path ~/Projects --confirm

Authorization does not recursively scan or combine ~/Projects. The first hSUM tool call below that directory initializes only the exact Git repository for the current task. Each repository keeps a separate index, trust binding, generation, and citation namespace. Home, filesystem root, overly broad paths, and Git repositories themselves are refused as workspace scopes.

Claude Code / Claude Desktop

Run this from inside an indexed repository. hSUM emits a copyable snippet with the correct absolute binary path and binding UUID already filled in:

hsum client config claude-code

{
  "mcpServers": {
    "hsum": {
      "args": [
        "mcp",
        "--binding",
        "495d788b-897c-46b6-86c2-5d28d80b3d42"
      ],
      "command": "/absolute/path/to/hsum"
    }
  }
}

Also supported: claude-desktop and generic. Add --format toml for TOML instead of JSON. client config codex remains a low-level escape hatch and emits the workspace-dynamic hsum mcp command.

Verify or repair the connection

hsum integration status codex
hsum integration repair codex --confirm
hsum client doctor claude-code

integration status checks the effective Codex registration and managed agent policy. repair restores drifted managed state. The lower-level client doctor validates a binding-pinned client command and read-only MCP probe.

Use it well

Three habits make hSUM materially better in an agent loop:

• Ask for citations. Instruct the agent to cite hsum://v1 URIs for claims about the codebase, so you can verify them.
• Let managed Codex tasks refresh. An activated repository attempts one bounded refresh before the first search or citation read in each task. Manual integrations still use hsum ingest.
• Treat passages as data. Results are marked untrusted_content — never let retrieved text act as instructions.

You do not need to edit each repository's AGENTS.md. The managed user-global policy supplies the bounded guidance while preserving existing user instructions.