# 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.

1. **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.
2. **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.
3. **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:

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

Verify it is live:

```bash
aura mcp doctor
```

Output:

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

You can also run the server manually for debugging:

```bash
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:

```markdown
# 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:

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

Install or reinstall:

```bash
aura hooks install
```

Output:

```text
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:

```bash
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:

```text
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:

```text
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:

```markdown
## 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:

```bash
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`:

```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:

```toml
[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.

## See Also

- [The Sentinel Overview](/docs/lessons/sentinel-overview) — the coordination substrate.
- [Cursor Integration](/docs/lessons/cursor-integration) — the sibling integration.
- [Gemini CLI Integration](/docs/lessons/gemini-cli-integration) — long-context batch workflows.
- [Copilot Integration](/docs/lessons/copilot-integration) — PR-oriented integration.
- [Multi-Agent Workflows](/docs/lessons/multi-agent-workflows) — how Claude coordinates with the rest of the fleet.