Vodou - Claude Code Integration

See AGENTS.md for the full Vodou operating manual: subsystem map (Vodou-Console, Vodou-Board, Vodou-channels, Vodou-Recall, Vodou-Enhanced-Thinking, etc.), Layer 1/2/3 architecture, memory model, scheduler, work logging format, security defaults, and boundaries. It is not inlined into your session context (44 KB against a 24 KB budget — it never was, and the bootstrap now says so); read it with your file tool when you need it. This file covers Claude Code-specific integration and the shared project policy.

Scope of this file

This file applies to Claude Code — the developer CLI running in a user's terminal/IDE alongside their code. It does not apply to the Claude CLI subprocess that the gateway spawns to answer web-chat messages. That subprocess follows AGENTS.md §6.5 (mid-turn shell-outs allowed, 3 per turn cap, supervised path). If you are the gateway-chat LLM, read this file as context but defer to AGENTS.md §6.5 for tool-execution behavior.

Tool Priority — Vodou Always Wins

STRICT ORDER. Never deviate.

1. Vodou Skills (Layer 1) — if a skill is returned, follow it completely
2. Vodou intent_mappings — before touching ANY other tool, check if Vodou has it:

   sqlite3 vodou-core.db "SELECT keyword, server_name, tool_name FROM intent_mappings WHERE keyword LIKE '%X%' LIMIT 5;"

   If a match exists → ./vodou-core call <server> <tool> '<args>'. Done.
3. Vodou MCP servers directly — ./vodou-core call <server> <tool> for known servers (gmail, zapier, slack, etc.)
4. Cloud connector tools (mcp__claude_ai_* and the like) — LAST RESORT ONLY. Only when Vodou has zero coverage. Vodou ALWAYS has priority.

If the prompt hook surfaces a ### Vodou Intent Match block, use that route immediately — no deliberation needed.

Exception: a hint containing — hook: not auto-run was surfaced for you to judge, not executed. .claude/hooks/intent_executor.py emits three of them and the rules used to quote two strings it never wrote (SW-10), so match on that substring, not on a whole parenthetical:

• (matched inside prose — hook: not auto-run; …) — a registered keyword happened to appear in a sentence, e.g. "screenshot" in "tell me what to do for each screenshot". Not a request to call the tool.
• (side-effecting — hook: not auto-run; …) — the same judgement with higher stakes; the hook refuses to auto-fire anything that sends, writes or spends.
• (skill route — hook: not auto-run; …) — the keyword maps to a skill, and Layer 1 decides, not the hook.

All three end ; the daemon router may still fire this independently — the hint says only that this hook did not.

No double-fire rule: when active_context already contains ### Vodou Tool Results (auto-routed) with a completed result, do NOT call the tool again. Present what is there. Re-executing causes duplicate side effects (double emails, duplicate records).

Skills Are Layer 1 — They Always Come First

When Vodou routes a query to a skill, the skill takes absolute priority. You are its executor, not a substitute. Canonical rules and the full stopping-point checklist live in AGENTS.md under "Skills Are Layer 1". Short version:

• If a skill is returned, follow it — don't answer the question yourself.
• If skill output contains STOPPING POINT, Reply with the number, Reply with 1-, or Display to user: display the intro + full numbered menu verbatim, then STOP. Wait for the user's choice. Never assume.
• If a skill calls MCP tools, use those tool calls — don't substitute your own knowledge.
• Execute steps in order, never skip or combine.

Agent Instructions & AGENT_ACTIONS

Skills can embed executable tool sequences as <!-- AGENT_ACTIONS_N: {...} --> HTML comments. Full spec (template variables, loop, capture, stream_progress) lives in AGENTS.md §6. Short form:

1. Vodou-Console web chat: the gateway's workflow driver handles execution automatically — you just format results.
2. Any coding agent (this file): parse the AGENT_ACTIONS JSON and execute each step via ./vodou-core call <server> <tool> '<args>'.

If Vodou output contains ## Agent instructions (human-readable) or AGENT_ACTIONS: (inline JSON), execute those steps before replying. If .vodou/workspace/agent_next_steps.json exists at turn start, run those actions, then respond.

MCP Tool Calls Are Mandatory — Never Fake Data

When AGENT_ACTIONS or a skill says to call MCP tools, you MUST execute ALL of them via ./vodou-core call <server> <tool> BEFORE responding. Never substitute LLM knowledge for live data. Users need real numbers, not approximations.

Running Vodou from a coding agent

The right primitive is ./vodou-core call <server> <tool> '<json-args>' — deterministic, single-spawn, no subprocess tree, returns clean JSON. Use this for every tool execution you would otherwise reach for brain/do.

./do "<text>", ./oi, ./vodou and ./vodou-core brain "..." DO work headlessly (no TTY gate triggers in current code, verified 2026-05-15), but they spawn the full BrainLoader subprocess tree, and in rapid loops have historically built up to 100s of orphan processes requiring a reboot (the 425-process incident). So:

• ✅ One-shot brain/do calls are fine.
• ❌ Don't loop them, don't poll them, don't use them inside retry logic.
• ❌ Don't run --version to check the binary — read Cargo.toml [package].version instead.
• ❌ Don't poke the worker from here — ask the user to run it interactively.
• For a question about a command (not a request to run it): just answer.

If the user types do "<text>" expecting the launcher: for a known tool, ./vodou-core call — same effect, no spawn hazard; for an ambiguous query needing BrainLoader routing, one ./do is fine. Three or more in a turn: stop and use targeted vodou-core call.

(The AGENTS.md §6.5 mid-turn shell-out guidance with its 3-call cap is for the LLM running inside the gateway chat — a different, supervised process. Same shape of rule, applied here in spirit.)

Helper scripts you should know about

• ./do "<query>" — primary entry point for any task.
• ./vodou-core call <server> <tool> '<json-args>' — direct MCP tool call, headless.
• ./vodou-core mem search "<query>" [--top-k N] [--json] — hybrid FTS5+vector search over memory.db via the daemon socket (same pipeline BrainLoader uses). Use this instead of raw sqlite3 memory.db "... MATCH ..." — raw FTS5 skips the reranker and scope boost. Distinct from Vodou-Recall (which searches chat turns).
• ./vodou-core builds — which build is which: engine binary, console dist, every extension folder, plus what the daemon and worker are actually running. Run it when a fix "didn't work" before assuming the code is wrong.
• ./vodou-core flows — is the product still telling itself the truth? Four flows graded from LIVE evidence. --json for CI, exit 2 on a red row. A grader with no evidence answers unknown, never ok.
• ./vodou-core capture — browser capture graded per site (alive / unknown / broken…). Console twin: Connect → Browser.
• ./vodou-core connections — OAuth / connector ledger with reasons (expired-reconnect vs idle). Same mould as flows.
• ./vodou-core hosts — which host adapters have real evidence of working, graded from gateway.db rows (not a rotating log — that was the bug).
• scripts/broken-lab.sh — break Vodou on purpose in an isolated instance and see what every surface says. Use it before claiming what a user "would see" in a failure.
• ./vodou-core intent-signal "<prompt>" — what the keyword router would do with a prompt, and why. --file <path> for a distribution.
• ./vodou-core mem hygiene [--examples] — do stored facts stand alone for a stranger? A ranking number, not a tidiness one.
• ./vodou-core rules render [--check] — regenerate this file and its siblings from templates/rules/. This file is generated; edit the source.
• ./open-gateway.sh — re-open the web UI without restarting services.
• ./start-vodou-services.sh / ./stop-vodou-services.sh — boot / tear down daemon + worker + console. VODOU_NO_OPEN_BROWSER=1 suppresses the browser.

Committing from parallel sessions

Multiple agent sessions work in this ONE worktree concurrently. Two incidents on 2026-07-04: a commit swept another session's edited src/main.rs (with a mod pointing at a not-yet-committed file — HEAD didn't compile from a fresh checkout), and a hot file was rewritten under a session mid-edit. Rules:

1. Stage explicit paths only. Never git add -A, git add -u, or git add . — you WILL sweep another session's in-flight work.
2. Before staging a shared hot file (src/main.rs, src/daemon.rs, MCP-servers/Vodou-Console/src/llm.ts, MCP-servers/Vodou-Console/src/index.ts, vodou-hook/src/main.rs), run git diff <file> and look for hunks you didn't author. If you find any, stage only your hunks, and say so in the commit message.
3. If the prompt context shows ### Live peers on your files, another session is editing the same files right now. That block is computed from real session state, not guessed — treat it as the reason rule 2 exists.
4. A pre-commit guard blocks self-inconsistent commits (staged mod foo; / relative TS import whose target file isn't in the index). Source: scripts/commit-guard.py; bypass only for genuine emergencies with VODOU_SKIP_COMMIT_GUARD=1.
5. A secret-guard blocks staging a credential VALUE (scripts/secret-guard.py). It scans git diff --cached added lines against .build/release-pii-patterns.txt. Bypass VODOU_SKIP_SECRET_GUARD=1, but prefer fixing the string: if it is a test fixture, make it not key-shaped; if it was ever real, revoke it.
6. A date-guard blocks staged lines that violate the time canon (scripts/date-guard.py; canon: PLANS/PLAN-TIME-CANON.md). SQLite instants are naive UTC YYYY-MM-DD HH:MM:SS; day identity is the LOCAL day; display parses naive-as-UTC, renders local. Bypass a true false-positive with VODOU_SKIP_DATE_GUARD=1.
7. A coherence-guard blocks the seam-audit's enforceable rules (scripts/coherence-guard.py): a raw scope/enum reaching textContent/innerHTML (translate via scopeLabel()); a displayed *_count nothing writes; an iframe of our own surface with no declared min-width. When deliberate, say so in the diff — // COHERENCE-INTENTIONAL: <why>.
8. New module + its declaration commit together. If you add mod x; or an import of a new file, that file goes in the SAME commit.
9. A rules-guard blocks a generated rules file that is out of step with its source (scripts/rules-guard.py). CLAUDE.md, .cursorrules and .cursor/rules/vodou-policy.mdc are generated from templates/rules/ by ./vodou-core rules render; edit the source, render, stage both. Bypass VODOU_SKIP_RULES_GUARD=1.
10. An entrypoint-guard blocks an executable script that starts a long-lived process and belongs to no stack (scripts/entrypoint-guard.py; registry: stacks.toml, PLAN-SEAMS P4 / lane canon rule 3). It is deliberately not a grep for nohup — four of the thirteen occurrences in this tree are prose (an echo, a docstring, two comments), and a guard that fires on documentation is one people learn to bypass. Module code inside an already-declared process is governed by processes.toml instead. scripts/entrypoint-guard.py --audit grades the whole tree; scripts/test-entrypoint-guard.sh proves it fires in both directions. Bypass VODOU_SKIP_ENTRYPOINT_GUARD=1, but prefer adding the file to a stack's entrypoints.
11. An env-example-guard blocks a generated .env.example that disagrees with its manifest (scripts/env-example-guard.py). .env.example is generated from scripts/env.example.manifest.json by scripts/sync-env-example.mjs, the same generated-from-source shape rules-guard covers for CLAUDE.md — and it had drifted on every value anyone checked: re-running the generator would have uncommented WEB_PORT (defeating auto-port-assignment), commented out ORT_DYLIB_PATH (turning semantic memory off for everyone AND breaking the packer's three per-platform seds, which anchor on ^ORT_DYLIB_PATH=), and re-enabled the compact schedule PLAN-DYNAMIC-MEMORY-MD deliberately turned off. Compares key STATE (active-vs-commented and value), not rendered prose, so reflowing a description cannot fail a commit. Bypass VODOU_SKIP_ENV_EXAMPLE_GUARD=1; prefer fixing whichever side is wrong — usually the manifest, because .env.example is what ships and gets fixed by hand.
12. An ext-version-guard blocks extension code changing without a version bump (scripts/ext-version-guard.py). EX-5 — the readiness audit's only exploitable finding — shipped nine days late because nothing asked this: 0.5.97.78 was set on 2026-08-27, five commits then changed the Store build, and the Chrome Web Store kept serving the pre-fix code under a number it had already accepted. The store only enforces that a version is unique at upload, so two different builds can share one and nothing complains. Note this is a DIFFERENT question from verify-extension-version-chain.sh, which checks that Rust, the gateway and the UI agree about a version — they agreed perfectly for all nine days. Staging anything under extension/<build>/ that reaches a user requires that build's manifest.json version to be staged AND to differ from HEAD; staging the manifest without moving the value is the exact failure, so it does not satisfy the guard. Excludes mirror the packer's strip list (test/, store-assets/, build-icons.mjs, README.md, *.map) — a change that cannot reach a user must not demand a bump, or people learn the bypass. Bypass VODOU_SKIP_EXT_VERSION_GUARD=1; the fix is to bump all three manifests together and re-run scripts/pack-vodou-bridge-store.sh.
13. A workspace-guard blocks live code that reads or writes a hand-maintained workspace file (scripts/workspace-guard.py; GATE 16 of PLAN-CONTEXT-THAT-MAINTAINS-ITSELF). Everything a session reads from .vodou/workspace/ is generated on a clock now — MEMORY.md, TOOLS.md, HEARTBEAT.md — and reading those is fine: they are receipts of a renderer. The plan's text said "nothing reads" the four retired files; after the build, six live paths did (the console scraped names with a regex, the planner concatenated two of them, the wizard WROTE all four), and the claim had shipped unexamined because nothing checked it. This does: a staged line that builds a path to, reads or writes a workspace .md outside the generated set fails the commit, in the three idioms this tree uses (.vodou/workspace/X.md, path.join(wsDir, 'X.md'), .join("workspace").join("X.md")). A one-time carry of an old file into its new owner says so on the line — // WORKSPACE-MIGRATION-SOURCE — and that is the only escape. --audit grades the whole tree and is what vodou-core workspace retire consults before moving anything, so the commit check and the archiver cannot disagree about what a reader is. Bypass VODOU_SKIP_WORKSPACE_GUARD=1; prefer reading the owner (a setting, a pin, render()).
14. A loop-guard blocks a proactive loop that no registry declares (scripts/loop-guard.py; registry: loops.toml, PLAN-PROACTIVE-LOOPS rev 3 P0b / lane canon rule 3 — a loop is a process). Four curation engines already run continuously and each invented its own output path: the contradiction detector reaches a person through an eprintln!, the janitor through a work_logs row, the hygiene grader through a command nobody types, the entity graph through a click. The registry is the contract that stops the fifth. Enforced: a staged file under src/loops/ with no [loops.<name>] entry; an entry missing a mandatory field; an entry naming a fixture_* that does not exist; an entry that invents its own drain (emits must be loop_findings) or escalates itself to critical. The fixtures are the point — fixture_quiet and fixture_fresh are must-not-fire controls, and the live ledger's finding is that five graders shipped false-positive because none had one. The registry is read from the index, not the working tree: a commit is judged on what it contains. Silent (exit 0, immediately) on any commit staging neither loops.toml nor src/loops/, which today is every commit. scripts/loop-guard.py --audit grades the tree; scripts/test-loop-guard.sh proves it fires in both directions (13 cases). Bypass VODOU_SKIP_LOOP_GUARD=1, but prefer adding the entry.
15. A push-guard refuses a direct push to main or development (scripts/push-guard.sh, installed as .git/hooks/pre-push by scripts/install-push-guard.sh). Changes reach those branches through a pull request. Asked for 2026-09-16, the day a session fast-forwarded main and pushed 55 commits in one go — its own onboarding fix plus four other sessions' in-flight work (memory/inject changes, extension bumps to 0.5.97.86, the credential masking). Every commit was sound; the problem is that main is what releases are cut from and nobody saw them first. In a clone this many sessions share, "push my work" and "publish everyone's work" are the same keystroke. Pushing a FEATURE branch is unguarded — that is the intended path: git push -u origin <branch> then gh pr create --base main --head <branch> --fill (gh is authenticated as VodouAI, repo scope). Merging the PR is the user's call, not a session's. Bypass VODOU_ALLOW_DIRECT_PUSH=1 for a release push or an emergency; using it is a decision to skip review, so say so.

If .git/hooks/pre-push is missing (a fresh clone has no hooks), reinstall it — one install covers every worktree, since .git/hooks is shared:

bash scripts/install-push-guard.sh          # bash scripts/install-push-guard.sh --check  to verify

If .git/hooks/pre-commit is ever missing, reinstall ALL TEN guards — .git/hooks/ is not versioned, so a fresh clone has none, and reinstalling only the first silently drops the others:

printf '#!/bin/sh\nROOT="$(git rev-parse --show-toplevel)"\npython3 "$ROOT/scripts/commit-guard.py" && python3 "$ROOT/scripts/secret-guard.py" && python3 "$ROOT/scripts/date-guard.py" && python3 "$ROOT/scripts/coherence-guard.py" && python3 "$ROOT/scripts/rules-guard.py" && python3 "$ROOT/scripts/entrypoint-guard.py" && python3 "$ROOT/scripts/env-example-guard.py" && python3 "$ROOT/scripts/ext-version-guard.py" && python3 "$ROOT/scripts/workspace-guard.py" && python3 "$ROOT/scripts/loop-guard.py"\n' > .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit

MCP server dependencies — never npm-install by package name

Servers under MCP-servers/ ship prebuilt node_modules/. Some deps are vendored, not on npm: @vodou/* packages (e.g. @vodou/channel-sdk) are file: links into a packages/ dir inside the same server — a registry 404 for them is expected, not evidence they're lost. Never run npm install <package-name> inside an MCP-servers/* dir; naming a package forces a registry lookup and npm can prune the vendored link while failing. To repair ERR_MODULE_NOT_FOUND: a plain npm install (no name) in that server's directory. Full rules: AGENTS.md §Troubleshooting.

Lane canon (parallel processes, ports, injectors)

Two plans found the same disease in different organs — five-then-seven context injectors nobody counted, and a second web process nobody restarted for seven weeks. The rule, once:

1. Two lanes → one identity + one arbiter, never deletion. A second lane that was locally correct stays. What gets added is a shared identity and one place that decides who pays. Deleting the lane amputates the surface that needed it.
2. Precedence is one rule, everywhere: process env > .env > gateway setting. A script that reads .env after the environment (so FLAG=0 ./script cannot override an .env line) is a bug, not a convention.
3. No new port, process, or prompt-injection site without a registry entry. Start, stop and the updater must all know a process; an injection site declares a lane name, a budget and a trust label.
4. Cross-store identity is resolved through the owner, not by opening its DB. memory.db has ids; gateway.db has names and settings; vodou-core.db has turn receipts. Ask the owner; don't open a second handle and cache the answer.
5. Ephemeral output is not a fact. Tool measurements ([RUN] notes, CPU numbers) may be logged and shown, but are not extracted as facts, not fed to the contradiction detector, and not injected as memory on a later turn.

Work Logging

Log at end of every coding session. Full format, categories, and metadata keys: AGENTS.md §"Enhanced Work Logging".

./do "log: category: description | key: value"

Auto-memory

Four memory types: user (preferences, role), feedback (rules with Why + How to apply), project (in-flight work), reference (external system pointers). Daily incremental logs: memory/YYYY-MM-DD.md. Extraction runs every prompt via the prompt hook.

Don't save code patterns, git history, ephemeral task state, or anything already in AGENTS.md. MEMORY.md is rendered from memory.db each session — edits to the rendered file are overwritten; pin a memory instead (vodou-core mem pin).

Claude Code Hooks

Hooks use vodou-hook-bin — a zero-thread, ~400KB binary that talks to the daemon via Unix socket; never opens the DB directly.

• SessionStart: ./vodou-hook-bin startup (TTY) or ./vodou-hook-bin cursor-session (JSON {"additional_context":"…"} for IDE hooks). Returns the workspace bootstrap, ending with a ### context budget line that names anything evicted.
• UserPromptSubmit: ./vodou-hook-bin sock prompt — sends prompt to daemon for memory search, falls back to buffering if daemon is down.
• SessionEnd: ./vodou-hook-bin sock flush — triggers full session memory extraction via daemon.

Claude Code Memory (auto-memory)

Project-local memory path: .claude/projects/<project-hash>/memory/MEMORY.md. MEMORY.md is dual-injected: once via Vodou workspace bootstrap (AGENTS.md context), once via Claude Code's own auto-memory system — that's intentional. See the system prompt's # auto memory block for the full rules.