Skip to content
archcore logo archcore logo archcore

Hooks

CLI

Hooks are how Archcore injects project context into an agent session before you type anything. One hook, one event: session start.

What the hook does

Section titled “What the hook does”

At session start, the agent invokes:

Terminal window
archcore hooks <agent-id> session-start

Archcore responds with:

  • An index of every document in .archcore/ — path, type, title, status.
  • A summary of relations (which documents reference which).
  • Any drift signals detected since the last run.

This output goes straight into the agent’s working context, so the agent already “knows” about your ADRs, rules, guides, and plans on turn one.

Installing

Section titled “Installing”

Hooks are installed automatically during archcore init. To install them manually for all detected agents:

Terminal window
archcore hooks install

Or for a single agent:

Terminal window
archcore hooks install --agent claude-code

Supported agents

Section titled “Supported agents”

Four agents support hooks today:

AgentHook file
Claude Code.claude/settings.json
Cursor.cursor/settings.json
GitHub Copilot.vscode/settings.json
Gemini CLI.gemini/settings.json

OpenCode, Codex CLI, Roo Code, and Cline do not support session hooks yet. You can still use MCP with them — just ask the agent to list documents when you want context.

Example config — Claude Code

Section titled “Example config — Claude Code”
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "archcore hooks claude-code session-start"
          }
        ]
      }
    ]
  }
}

Installed automatically by archcore init and archcore hooks install.

Running the hook manually

Section titled “Running the hook manually”

Useful for debugging:

Terminal window
archcore hooks claude-code session-start

The output is the same as what the agent sees at session start.

When you don’t need hooks

Section titled “When you don’t need hooks”
  • You always start conversations by asking the agent to list documents.
  • Your agent doesn’t support hooks (MCP alone still works).
  • You want explicit control over when context gets loaded.

Next steps

Section titled “Next steps”