Claude Code Integration

MCP, CLAUDE.md, and hooks — the canonical wiring for Aura's first-class Claude citizen.

Why This Exists

Claude Code is, for many teams, the primary AI coding agent. Anthropic's CLI ships with an MCP (Model Context Protocol) client, a project-level CLAUDE.md convention for instructions, and a pre-commit hook architecture that Aura can slot into cleanly. All three mechanisms are public, stable, and documented by Anthropic — which is why Aura's most mature integration is the Claude Code one.

But "most mature" does not mean "Claude-only." Every capability described on this page has equivalents in the Cursor, Gemini, and Copilot integrations. The wiring is what differs; the Sentinel it talks to is the same.

The Aura MCP server exposes twenty-nine tools. A well-configured Claude Code session uses them the way a well-configured human uses Git: continuously, reflexively, without thinking.

How It Works

There are three layers.

The MCP server. aura-cli ships an embedded MCP server called aura-vcs. It speaks JSON-RPC over stdio or a socket, and it exposes the full aura_* tool surface.
The CLAUDE.md protocol. A repo-level file that teaches the model when to call which tool. It lives at the root of your project and is read by Claude Code on every session.
The pre-commit hook. A small shell script in .git/hooks/pre-commit that calls aura intent-check before allowing a commit. This is the enforcement mechanism — without it, Claude can still call tools, but nothing prevents a rogue commit.

All three are installed by aura init. You can inspect or reinstall any of them individually.

MCP server setup

After aura init, Claude Code needs to know about the server. The canonical location is the user's Claude settings:

{
  "mcpServers": {
    "aura-vcs": {
      "command": "aura",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

Verify it is live:

aura mcp doctor

Output:

aura-vcs MCP server: ok
tools exposed: 29
claude code sees server: yes (PID 83421)

You can also run the server manually for debugging:

aura mcp serve --log-level debug

The canonical CLAUDE.md

The Aura repo ships a reference CLAUDE.md that encodes the full protocol. This is the version that lives at the root of aura-cli and is updated with every release. A condensed form:

# AURA SEMANTIC ENGINE — MANDATORY PROTOCOL FOR CLAUDE CODE

You are Claude running inside Claude Code CLI. Aura is installed in this repo.

## BEFORE WRITING CODE
1. Call `aura_status` — see team sync, pending pulls, active zones.
2. Call `aura_live_impacts` — unresolved cross-branch impact alerts.
3. If `💬 TEAM` banner appears, call `aura_msg_list` immediately.
4. For features touching 3+ files, call `aura_plan_discover` and lock
   the wave plan before writing code.

## WHILE WRITING
5. Call `aura_snapshot` before every file edit. Respect zone banners:
   - WARNING → proceed cautiously, notify zone owner.
   - BLOCKED → do NOT edit. Ask via `aura_sentinel_send` or escalate.
6. Call `aura_log_intent` before every commit. The pre-commit hook
   compares your intent to the actual AST diff.
7. Run `aura_pr_review` after each logical unit of work.

## TEAM SIGNALS
- `🔄 SYNC`      → `aura_live_sync_pull`
- `💬 TEAM`      → `aura_msg_list` then `aura_msg_send`
- `📨 SENTINEL`  → `aura_sentinel_inbox` then `aura_sentinel_send`
- `🚨 ZONE`      → coordinate, do not override silently
- `⚠️ COLLISION` → `aura_sentinel_send` to the peer agent

## NEVER
- Commit without `aura_log_intent`.
- Edit without `aura_snapshot`.
- Ignore `SENTINEL` or `TEAM` banners.
- Edit a BLOCKED zone without human override.

The full version, which is what ships by default, is several times longer and covers handover, knowledge queries, and orchestration tools. The condensed form above is what most teams modify.

The pre-commit hook

Aura's hook is the enforcement layer. It runs on every git commit and performs three checks:

Intent logged? If aura_log_intent was not called in this session, the commit is refused (unless strict mode is off).
Intent matches diff? The hook computes the AST diff and compares it against the intent text. Large drift triggers an "Intent Poisoning" flag.
Zones respected? If any file in the commit belongs to a zone not owned by this session, the hook blocks.

Install or reinstall:

aura hooks install

Output:

installed: .git/hooks/pre-commit
installed: .git/hooks/commit-msg
installed: .git/hooks/post-commit (live-sync)

Strict mode is on by default. To audit it:

aura config strict

Examples

A well-behaved session

What the first ninety seconds of a Claude Code session look like when CLAUDE.md is doing its job:

User: add OAuth support to authenticate()

[Claude] → aura_status
         ← 1 pending pull, 0 active collisions, 0 zones
[Claude] → aura_live_sync_pull
         ← applied 3 function updates from cursor-def456
[Claude] → aura_live_impacts
         ← no unresolved alerts
[Claude] → aura_memory_read query="oauth"
         ← 2 entries, top: "use PKCE for public clients (confidence: high)"
[Claude] → aura_plan_discover goal="add OAuth to authenticate()"
         ← 4 gray areas, 3-wave plan
[Claude] (presents gray areas to user)
User: use PKCE, no refresh tokens, token lifetime 1h
[Claude] → aura_plan_lock ...
[Claude] → aura_snapshot file=src/auth/user_service.py
         ← ok, no zone conflicts
         (starts editing)

Every step is a tool call, every tool call is auditable, every piece of context the model uses is recorded.

Handover

When the context window approaches saturation, CLAUDE.md instructs Claude to call the handover tool:

aura_handover agent="claude"

It returns a dense XML payload with the semantic state of the session — plan, gray areas, completed waves, knowledge entries consulted, zones held, outstanding messages. The user starts a new Claude Code session and pastes the payload as the first message. The new session picks up at roughly 90% of the prior context density.

Customizing the protocol

Most teams keep the canonical CLAUDE.md and add a small house-rules section at the bottom:

## HOUSE RULES (acme-auth-service)
- Never use `print` for debugging; use the structured logger.
- All new endpoints must have an integration test in tests/api/.
- TypeScript files use 2-space indentation, Python uses 4.

Claude reads the whole file; the house rules sit alongside the Aura protocol without conflicting.

Disabling strict mode (not recommended)

If, for some reason, you want to let commits through without intent logging:

aura config set strict_mode false

Aura will warn you that this weakens the intent-matching guarantee. If the repo is configured with strict_mode_locked = true, you cannot disable it without the team passcode.

Configuration

The relevant knobs, in .aura/config.toml:

[claude]
mcp_server_name = "aura-vcs"
claudemd_path = "CLAUDE.md"
enforce_claudemd_presence = true

[hooks]
pre_commit = true
commit_msg = true
post_commit = true
strict_mode = true
strict_mode_locked = false

[mcp]
transport = "stdio"
log_level = "info"
tool_timeout = "30s"

enforce_claudemd_presence = true causes aura doctor to flag the repo if CLAUDE.md is missing or has drifted substantially from the shipped template. A team can pin a specific version:

[claude]
claudemd_version = "v0.12.6"

Feature Matrix

| Feature | Claude Code | Notes | | --- | --- | --- | | MCP server | Full | Native support, 29 tools exposed | | Instruction file | CLAUDE.md | Canonical protocol ships in-repo | | Pre-commit enforcement | Yes | Hook refuses commits without intent | | Collision notifications | Inline in tool response | Model sees them immediately | | Handover | aura_handover | Designed for 50K+ token sessions | | Sentinel inbox | Full | Read and reply via MCP | | Knowledge base | Full | Read and write | | Zone claims | Full | Honored by pre-edit and pre-commit |

Claude Code is currently the most complete integration because MCP is native. Other integrations (Cursor, Gemini, Copilot) expose subsets of the same surface; see their individual pages for details.

Troubleshooting

"MCP server not visible to Claude" — run aura mcp doctor. If the server is running but Claude does not see it, check your Claude settings file; the server name must match aura-vcs.
"Claude keeps forgetting to call aura_snapshot" — verify CLAUDE.md is present at the repo root and is not empty. Models sometimes skip protocol steps when the file has drifted from the template.
"Pre-commit hook blocks legitimate commits" — the aura_log_intent call must happen in the same session as the commit. If you are scripting commits outside of Claude, call intent explicitly from the script.

The Twenty-Nine Tools, Grouped

The MCP server exposes twenty-nine tools. Grouping them by purpose makes the surface easier to hold in the head.

Session state

aura_status — the one-stop overview.
aura_usage — token and context usage in the current session.
aura_context_budget — set or query context budgets.

Editing

aura_snapshot, aura_snapshot_list — pre-edit backups.
aura_rewind — surgical function-level revert.
aura_suggest_edit — AI-suggested fixes for review findings.
aura_read_history — audit the history of a specific node.

Intent and review

aura_log_intent — the commit-time intent call.
aura_pr_review — AI-powered bug and security scan.
aura_prove — behavioral goal verification.

Planning

aura_plan_discover, aura_plan_lock, aura_plan_next — the three-step planning flow for multi-file features.
aura_orchestrate_status — check multi-agent orchestration progress.

Session continuity

aura_handover — compress context for agent handoff.
aura_session_resume, aura_session_summarize — resume or summarize a prior session.

Sentinel — the subject of this module

aura_sentinel_send, aura_sentinel_inbox, aura_sentinel_agents, aura_sentinel_status, aura_sentinel_release.
aura_zone_claim.
aura_msg_send, aura_msg_list — the human-readable team channel.
aura_live_impacts, aura_live_resolve, aura_live_sync_push, aura_live_sync_pull, aura_live_sync_status.

Knowledge and memory

aura_memory_read, aura_memory_write, aura_memory_compact, aura_memory_forget.

Diagnostics

aura_doctor, aura_ask.

Not every session uses every tool, but the CLAUDE.md protocol ensures a consistent baseline: status, impacts, inbox, knowledge, then work. That is the habit the integration exists to install.