Agent Integrations

Agent Integrations

Every agent talks to the same daemon, so they share one memory: a dead end Claude Code recorded is in the pack Codex gets.

MCP server (any MCP client)

claude mcp add --transport http av http://localhost:7420/mcp
# with a token: add --header "Authorization: Bearer $AV_TOKEN"

The server lives at /mcp (JSON-RPC over streamable HTTP). Each tool is an in-process call to the HTTP API, so tools behave exactly like the API. The tools:

Group	Tools
Task work	start_task, checkpoint, record, get_context, expand, read_symbol, search_history, status, validate, sync, abandon
Handoff and review	handoff, claim_task, submit, review_task, post_review, merge, undo
Repo knowledge	list_conventions, why
Workspace-free reads	read_file, list_files, diff, log (any commit: main, task:<slug> or a commit id)

• start_task with no title and goal asks for the next job that fits the agent (see Multi-Agent Routing).
• validate is an attestation: the agent runs the command and the daemon records its exit code.
• Task tools accept an id, a slug (louder-hello) or repo/slug.
• Each MCP connection is its own ledger session and remembers the tasks it started or claimed. Without task_id, a call uses the session's only open task, or refuses and names the candidates. Claude Code subagents share their parent's session.
• The agent name is the client's name, or an X-Av-Agent header.

Claude Code

av init (or av init --for claude) wires the MCP server. integrations/claude-code/install.sh (needs jq) installs four hooks into ~/.claude/settings.json (the previous file is kept as settings.json.bak):

Hook	What it does
SessionStart	Prints an 800-token pack for the task of the session's directory (also after compaction or /clear).
PreToolUse on Read|Edit|MultiEdit	Adds what other tasks recorded about that file (at most 400 tokens, each record once per session), so the why arrives when the file is opened.
PostToolUse on Edit|Write|MultiEdit	Checkpoints, at most every 2 s.
Stop	Checkpoints. If changed symbols have no record explaining them, blocks the stop once and asks for the decisions and dead ends behind them.

Keep agents busy. After that check, Stop asks the daemon (a dry run of next) whether work is waiting for this agent. If so, it blocks the stop with av: <what is waiting> - call start_task with no title. If nothing fits yet, it keeps looking every 15 s for up to AV_HOOK_WAIT_SECS (default 600; 0 turns it off) at no model cost. It continues one session at most AV_HOOK_MAX_CONTINUES times (default 20). Re-run install.sh after changing the wait, since the hook timeout is set from it.

All hooks are silent outside a task and never fail the agent.

Codex, Grok Build, Gemini CLI, Cursor Agent

av init --for codex --for grok --for gemini --for cursor

This merges the MCP server into $CODEX_HOME/config.toml (default ~/.codex), ~/.grok/config.toml, ~/.gemini/settings.json or ~/.cursor/mcp.json. The rest of each file is kept, and the previous version is saved as *.bak. With AV_TOKEN set, the file names only the variable, never the token. Grok, Gemini and Cursor also get an X-Av-Agent header.

• Codex, Gemini and Cursor get no hooks: they call start_task / claim_task and get_context themselves.
• Grok gets SessionStart and Stop hooks in ~/.grok/hooks/av.json (see integrations/grok/README.md).

Per-agent instructions are in integrations/<agent>/README.md.

Any mcpServers JSON client (Muse, Windsurf, Cline, …)

av --agent NAME init --for mcp-json --path FILE

This merges mcpServers.av (type: http, the /mcp URL, X-Av-Agent: NAME) into the file and keeps the rest.

Any other agent

integrations/generic/av-wrap.sh <command…> writes the pack to $AV_CONTEXT_FILE, runs the command and checkpoints.

Making an agent loop over the backlog

The MCP server sends short working instructions when an agent connects. It deliberately does not tell an agent to keep taking jobs, because an agent you open for your own work should not start pulling the backlog. To make one loop, add this to the instructions file it reads (AGENTS.md for Codex, Grok Build and Cursor Agent, GEMINI.md for Gemini CLI). The full text is in integrations/agents-instructions.md:

## Scholion (`av` MCP server)

- Call start_task with no title or goal and do what it returns (review, merge, handoff or new task).
  When it returns no task, call it again with wait set; stop after three empty waits.
- Work only in the workspace it returns. Read the pack: it holds the decisions and dead ends of
  earlier agents. Call `get_context` for more, `expand` for one item.
- Record why, not what: a `decision` for a choice someone could undo by mistake, an `attempt` for a
  dead end, a `note` for anything else worth knowing. Anchor it to the file or symbol.
- `checkpoint` after a group of edits. Run the tests yourself, then `validate` with the command and
  its exit code.
- To stop before you are done, `handoff`. When done, `submit`; another agent reviews it.

Try it across vendors

scripts/relay-demo.sh shows one memory shared by different agents: Claude Code tries the obvious fix, records why it failed and hands off; Codex claims the task, and its first pack leads with that dead end. --scripted runs it for free with av commands in place of the agents.