The model is a stateless function: tokens in, tokens out. It has no memory, no filesystem, no ability to do anything. Every capability you think of as "Claude Code" is the harness — the program that decides what tokens go in, what to do with the tokens that come out, and what runs in between. This chapter walks one turn end to end, using this actual host as the running example, so that Chapters 3–7 (the individual MCP servers and repos) and Chapter 8 (the author's self-description) have a shared vocabulary to point back to.

This chapter in one table

1.1 What this instance looks like right now

It helps to ground the abstract layers in one real, fully-inspected setup, split by where each piece actually lives.

User level (~/.claude/, this reader's account):

~/.claude/CLAUDE.md        (none)      ← no global instructions
~/.claude/settings.json    theme + autoMode.environment only, no "hooks" key, no permissions
~/.claude/skills/          (none)
~/.claude/agents/          (none)
~/.claude.json mcpServers  {}          ← empty map, zero local MCP servers

There is also a flat-file auto-memory: a MEMORY.md index plus one file per memory (typed user/feedback/project/reference). The index is loaded into context at session start alongside the conversation — it is a seventh context layer, of the same "plain text, no enforcement" kind as CLAUDE.md.

Project level (/mnt/BlockVolume/Claude/.claude/, this specific working directory — note the directory itself is not a git repository, so "checked in" doesn't literally apply here the way it would in a repo):

/mnt/BlockVolume/Claude/.claude/settings.json        1 PreToolUse hook, matcher "Bash"
/mnt/BlockVolume/Claude/.claude/settings.local.json   permissions.allow: 26 accumulated rules
/mnt/BlockVolume/Claude/CLAUDE.md                     the "never change anything without asking" rule

So this instance is not uniformly empty — it's empty at the user level, and already has one real hook, a sizeable allow-list, and a project rule at the project level. Step 1.6 covers exactly what that one hook does and doesn't do, because it turns out to matter a lot for how you should read the "hooks are enforcement" claim later in this chapter.

The MCP servers visible at session start in the Claude Code session that produced this guide (Gmail, Docs, Spotify, …) were claude.ai connectors: remote servers attached to the claude.ai account, not processes running on this machine. Nothing MCP-shaped runs locally here.

1.2 Step 1 — You press Enter

The harness now builds a single prompt. It is rebuilt from scratch every turn (with prefix caching under the hood for cost, but conceptually: from scratch). Nothing persists in the model between turns except what the harness re-sends.

1.3 Step 2 — Context assembly

The pieces below are assembled into the context the model sees. Treat this as a set of layers rather than a rigidly specified order — no source available for this chapter pins down the harness's exact byte-for-byte sequencing, and in the session that produced this guide, project instructions and memory content in fact arrived as reminder blocks attached to the conversation, not inside a literal "system prompt" slot. What is solid is which layers exist and what each one costs.

a) System prompt. Harness-owned: identity, tool-use conventions, safety framing, the environment block (cwd, platform, git status, today's date). You mostly don't write this directly.

b) CLAUDE.md files, merged by precedence:

~/.claude/CLAUDE.md              ← user-global, every project     (empty here)
<project>/CLAUDE.md              ← project-level                  (yours lives here)
<project>/sub/dir/CLAUDE.md      ← pulled in only when you touch files there

These land as plain text. They are pure prompt — there is no enforcement behind them. Your "never apply changes without asking" rule works because the model reads it and (usually) complies, not because anything in the harness blocks a violation by itself. Section 1.6 covers the one respect in which that's no longer quite true on this host.

CLAUDE.md also supports @path/to/file.md imports, functionally identical to pasting the file inline — the split is for human maintainability, not for the model. According to the author's own self-description (not verified in any of the eight public repos — see Chapter 8), Raindancer118's personal global CLAUDE.md uses this to pull in several rules/*.md files, including one on security. Treat that specific detail as reported, not sourced.

c) Tool definitions. Every built-in tool (Read, Edit, Bash, Grep, …) plus every tool from every enabled MCP server, normally sent as a JSON schema with name, description, and parameter docs. This is the expensive part, and it's why the token-discipline obsession you'll see in these repos exists.

Counting the actual @mcp.tool()/@admin_mcp.tool() decorators in the repos: diary-mcp's main server registers 73 tools (diary_project_tools.py 37, memory_service.py 19, diary_link.py 8, search_engine.py 4, sync_manager.py 3, graph_core.py 2), plus 7 more on the separate diary-admin-mcp entry point (graph_admin.py), for 80 in total — see Chapter 3. cachyos-mcp registers 111: 21 of its own (arch.py) plus 31 from the network-mcp package it bundles (tools.py 20 + advanced.py 11) plus 59 from the sysprobe-mcp package it bundles (diag.py 17 + services.py 12 + desktop.py 30). That bundling is a plain Python import wrapped in try/except Exception: pass in cachyosmcp/__init__.py, so if the netmcp/sysprobe packages aren't importable, cachyos-mcp silently falls back to just its own 21 — see Chapter 5.

How much does that cost in tokens? This is a rough estimate, not a measurement of what the harness actually sends: an AST pass over the real tool definitions (docstring length plus parameter count, since FastMCP derives the schema from the function signature and docstring — see Chapter 2) puts diary-mcp's 73 tools at roughly 7–8k tokens (~100 tokens/tool on average) and cachyos-mcp's 111 at roughly 6k tokens (~50–90 tokens/tool, shorter docstrings). Enable both and you're in the neighborhood of 15–20k tokens of schema, before you've typed a word — if the harness sends full schemas for every enabled tool on every turn.

It often doesn't. Two mitigations show up both in these repos and in the session that produced this guide: - Splitting servers. The author moved the 7 audit-only tools onto a separate diary-admin-mcp specifically so normal sessions don't pay for them (diary_admin_server.py's module docstring states this rationale directly). According to the author's self-description, a similar logic applies at the server level: roughly 8 of 21 configured MCP servers are disabled per-project by default (see Chapter 8; this count is not independently verified in the repos). - Deferred tools. In the Claude Code session that produced this guide, most tools were listed by name only, with full schemas loaded on demand via a ToolSearch-style tool. That is the harness doing the same optimization automatically: idle cost drops to roughly a name per tool, and the "every single turn" cost above only applies once a schema is actually pulled in.

d) Skill descriptions. This is one of the cleverest of these layers. A skill is a directory:

~/.claude/skills/minecraft-dev/SKILL.md
---
name: minecraft-dev
description: Use when working on Spigot/Paper plugins — build setup, event API, …
---
<the actual instructions — can be thousands of words, plus reference files>

Only name + description are listed in context; the description can run up to 1536 characters by default (skillListingMaxDescChars), and the whole listing is capped at roughly 1% of the context window by default (skillListingBudgetFraction) — so "one line each" understates how much a description can actually say, though the total listing is still small relative to a full context window. Nothing in the harness "matches" a description against your task automatically: the model reads the listing and decides to invoke a skill (or you invoke one by name), and only then does the body load. That's progressive disclosure — dozens of skills cost a bounded, small slice of context idle, and a matched one delivers a full playbook. In the session that produced this guide, skills such as dataviz, claude-api and code-review were listed as one-line descriptions; their bodies were not loaded unless invoked.

Skills are how instructions scale past what a CLAUDE.md can carry without bloating every single turn.

e) Hook output. Covered in 1.4 and 1.6 — this is the layer with actual enforcement teeth.

f) The auto-memory index, conversation history, then your prompt.

1.4 Step 3 — UserPromptSubmit fires

Before the model sees anything, the harness runs any UserPromptSubmit hooks. A hook receives JSON on stdin:

{ "session_id": "…", "transcript_path": "/home/opc/.claude/projects/…/xyz.jsonl",
  "cwd": "/mnt/BlockVolume/Claude", "hook_event_name": "UserPromptSubmit",
  "prompt": "the text you just typed" }

and prints JSON on stdout:

{ "hookSpecificOutput": { "hookEventName": "UserPromptSubmit",
                          "additionalContext": "…text spliced into the prompt…" } }

That additionalContext is appended to your message. The model never decided to call it and cannot skip it.

According to diary-mcp's own README, a UserPromptSubmit hook (~/.claude/hooks/diary_prompt_retrieval.py) runs your prompt text through Postgres full-text search against curated memories and injects the top hits — you ask "what was the deal with the Ficus?" and the relevant memory is already in the window before the model starts, no tool call, no round trip. This is worth a flag: that script is not actually in the public diary-mcp repo. git log --all on the repo shows the filename only ever entering as a README reference, never as a committed file; the repo's shipped scripts/ directory contains session_start_hook.py and session_end_hook.py, not a prompt-retrieval script. So the mechanism above is documented behavior, per the README, not verified code — treat it accordingly (see Chapter 3).

The README is explicit about one design choice for that hook: it's FTS-only, never semantic, because — per the README — loading the embedding model fresh on every single prompt would reintroduce a cold-start stall previously documented in a "v0.8.1 postmortem" (a document not included in the public repo, so that history isn't independently checkable either). The model in question is paraphrase-multilingual-MiniLM-L12-v2 via fastembed, and the ONNX weights are noted in code comments as "~470MB" (diary_embed.py:28, diary_embed_ipc.py:6) — an approximate figure from the source, not a measured one. The inference worth drawing, and it is an inference: a hook that sits on the critical path of every prompt has to be cheap, and the shipped session_start_hook.py backs this up directly — its own docstring states "fails silent. A hook must never block a session," and its code wraps the stdin read in a bare try/except.

1.4.1 The event catalogue (a selection)

The table below covers the events this guide actually uses — it is not the full list this Claude Code installation's schema defines.

This installation's actual schema has considerably more: PostToolUseFailure, PostToolBatch, UserPromptExpansion, StopFailure, SubagentStart, PostCompact, PermissionRequest, PermissionDenied, ConfigChange, CwdChanged, FileChanged, InstructionsLoaded, WorktreeCreate, WorktreeRemove, and others not enumerated here. It's also not true that "a hook is just a command": besides the command type used throughout this chapter, the schema defines prompt, agent, http, and mcp_tool hook types, and a command hook accepts options beyond the bare shell string — timeout, statusMessage, async, asyncRewake, once, if.

PreToolUse and Stop are the two this chapter leans on most, but they're not the only events with "teeth" — PermissionRequest/PermissionDenied exist specifically to react to permission decisions, and any hook can return a blocking exit code (below), so the "which events can actually stop something" set is broader than this table.

Exit codes matter: 0 = fine, 2 = blocking error and stderr is fed back to the model (so the model sees why it was blocked and can adapt), anything else = non-blocking error — which, notably, means a hook that errors out for an unrelated reason (a missing dependency, say) does not automatically block anything unless it exits with code 2 specifically. Keep that in mind for 1.6.

Hooks are registered in settings.json. Here is the actual registration on this project, in full — not a hypothetical:

{ "hooks": {
    "PreToolUse": [ { "matcher": "Bash", "hooks": [
      { "type": "command",
        "command": "bash /mnt/BlockVolume/Claude/.claude/hooks/guard-destructive-bash.sh",
        "timeout": 10,
        "statusMessage": "Checking for destructive/state-changing command..." } ] } ] } }

This is from /mnt/BlockVolume/Claude/.claude/settings.json. The user-level ~/.claude/settings.json genuinely has no hooks key — but the project level, one directory down, already does. Step 1.6 walks through what that one hook actually does.

1.5 Step 4 — The model produces tokens

Plain prediction. If it emits a tool-call block, the harness intercepts it.

The animation below plays steps 4 to 6 as one loop, as plain text, the way it passes through the model. Text that is typed out is generated by the model. Text that appears at once is put there by the harness: the model writes a tool call and stops, the harness runs the tool, appends the result, and calls the model again. Between the two model calls nothing is remembered except what is in this text.

system: [system prompt, CLAUDE.md files, tool schemas]

user: How much space is left on the root disk?

assistant: I'll check the root filesystem.
{"type": "tool_use", "id": "toolu_01A…", "name": "Bash", "input": {"command": "df -h /", "description": "Show free space on /"}}
 running Bash: df -h /
user: {"type": "tool_result", "tool_use_id": "toolu_01A…", "content": "Filesystem                  Size  Used Avail Use% Mounted on\n/dev/mapper/ocivolume-root   36G   34G  1.5G  96% /"}

assistant: The root filesystem is 96% full: 1.5 GB of 36 GB left. That's tight, so anything large (a Docker image, a model cache) should go to /mnt/BlockVolume instead.

The tool result comes back as a user message. That's how the API carries it: the model's context is a list of messages, and the harness adds the result as the next one. When the model answers without another tool call, the turn ends and the Stop event fires (1.7).

1.6 Step 5 — Permission check

Before executing a tool call, some combination of the following resolves it: the permission mode, the permissions.allow/deny/ask rules in settings, and any PreToolUse hook's own allow/deny/ask decision. This chapter will not assert a strict, linear "mode, then rules, then hook, then ask you" order — no source available here pins that down precisely, and the one hook installed on this project actually depends on being able to override an allow rule (see below), which is hard to square with a model where allow rules are checked and resolved before the hook ever runs. Treat the exact precedence as harness-internal and version-specific; what's certain is that all three inputs feed into the same decision, and if nothing resolves the call, you get a prompt.

Permission mode is one of six values (not four): default, acceptEdits, plan, auto, dontAsk, bypassPermissions. This host's user-level settings.json configures an autoMode.environment block, which is why auto mode matters here specifically — the other three chapters in this book that touch on autonomous operation (Chapter 6, on AIDEN, and Chapter 8) come back to what running unattended actually implies.

CLAUDE.md is persuasion. Hooks and permission rules are enforced by the harness — but only for exactly what they match. A regex-based hook on one tool is a tripwire, not a sandbox.

That distinction is worth making concrete rather than leaving abstract, because this project already has a real example: /mnt/BlockVolume/Claude/.claude/hooks/guard-destructive-bash.sh, wired up as the PreToolUse hook shown in 1.4.1. Reading it directly:

• It only fires on the Bash tool (the hook's matcher). Edit, Write, NotebookEdit, and any MCP tool call are invisible to it entirely.
• It reads .tool_input.command via jq and tests it, case-insensitively, against a fixed alternation of patterns: docker … (prune|rm|stop|kill|restart), docker compose … (down|restart), systemctl (start|stop|restart|enable|disable|mask), rm -rf/rm -fr-style flag combinations, mv into /etc, /usr, /var, /boot, or /srv, kill/pkill/killall, shutdown, reboot, iptables, firewall-cmd, umount, mkfs, dd if=, fdisk, parted.
• On a match it emits hookSpecificOutput.permissionDecision: "ask" with a reason citing CLAUDE.md, and — per the script's own header comment — this is deliberate: it forces a fresh approval prompt even for a command wrapped inside ssh ... "command", and even if an equivalent command, or an allow rule, already exists in settings.local.json (which on this project holds 26 accumulated permissions.allow entries, e.g. Bash(claude update *), several scoped curl/ssh commands, WebSearch). That's the whole reason it has to be a hook and not just a stricter allow-list: an allow rule can't retroactively demand a fresh confirmation for a pattern that would otherwise auto-approve.
• It always exits 0. That includes the case where jq itself fails: the script sets set -euo pipefail, so a jq error would in principle stop the script early — but because it never reaches an explicit non-zero exit, and any such abnormal exit is a non-2 code, that counts as a non-blocking error per the exit-code rule in 1.4.1, and the command would proceed unguarded. In other words, it fails open, not closed.
• It's a plain regex over a command string, so it also has the ordinary blind spots of that approach: unlisted state-changing verbs (systemctl reload, docker compose up -d, docker start, service … restart, sed -i, git push to a repo that autodeploys, rm -r without -f written as separate flags in some orders), and anything indirected through a variable, base64 … | sh, or a script file written first and executed second.

Here is that hook playing out on one call. The left pane is what the model sees. The right pane is what the harness does while the model waits. For an ask, none of it reaches the model: Claude Code shows the hook's reason to you, not to Claude, so the model only gets the final tool_result and cannot tell that a hook caused the prompt.

system: [system prompt, CLAUDE.md files, tool schemas]

user: The new nginx config is in place, please apply it.

assistant: I'll restart nginx so it picks up the new config.
{"type": "tool_use", "id": "toolu_01B…", "name": "Bash", "input": {"command": "systemctl restart nginx", "description": "Restart nginx"}}

 waiting for the tool result

PreToolUse hook (matcher: Bash)
$ .claude/hooks/guard-destructive-bash.sh
stdin:
{"session_id": "…", "transcript_path": "…/<session>.jsonl", "cwd": "/mnt/BlockVolume/Claude", "hook_event_name": "PreToolUse", "tool_name": "Bash", "tool_input": {"command": "systemctl restart nginx", "description": "Restart nginx"}}
 running hook
grep -Eiq matched "systemctl restart" (pattern on line 10)
exit 0, stdout:
{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "ask", "permissionDecisionReason": "Matches a destructive/state-changing command pattern (…). Per CLAUDE.md, …"}}

permission prompt: Bash command: systemctl restart nginx. Do you want to proceed?
 waiting for you> No
command not run

user: {"type": "tool_result", "tool_use_id": "toolu_01B…", "is_error": true, "content": "The user doesn't want to proceed with this tool use. The tool use was rejected …"}

assistant: Okay, I won't restart it. Should I run nginx -t first to check the new config for errors?

Had the command been systemctl reload nginx, no pattern would match: the hook would print nothing, exit 0, and the command would run without any prompt. A regex hook only stops what it lists.

What the model sees of a hook

Whether the model notices a hook depends on the outcome. Claude Code's hooks reference is explicit about the reason text: "For "allow" and "ask", shown to the user but not Claude. For "deny", shown to Claude."

You can always tell that a hook asked: Claude Code labels the prompt with where the hook came from, [settings] for a hook from a settings file like this project's. The model can't. In the session that produced this guide, the model tried it on purpose. It first ran a plain date, then a harmless echo whose text contains systemctl restart, which the guard matches:

Bash: date -u +%T.%3N
→ 05:46:32.388

Bash: date -u +%T.%3N; echo "harmless hook test: systemctl restart nginx"
→ 05:47:52.601
  harmless hook test: systemctl restart nginx

The second result is just the command's output. Nothing in it says a hook ran, a prompt appeared, or you approved. The only trace is the clock: about 80 seconds between two calls that normally follow each other within seconds. The model can infer that something paused the call, but not that it was a hook. In the session that produced this guide, the model did see hook output of the last kind: the /goal command's Stop hook sent its verdicts back as "Stop hook feedback" messages whenever the goal wasn't met yet.

Accept once, or always accept

When a call needs your approval, Claude Code's prompt offers roughly three answers (the exact wording varies by version):

Not every prompt offers the second answer. Claude Code only offers it when the prompt can show everything the saved rule would allow, so some prompts are one-time only (permissions docs).

This project's settings.local.json shows what the second answer leaves behind: 26 entries. 15 are long, exact one-off Bash commands (a single approved ssh … sed -i … line, for instance), 5 are prefix rules such as Bash(claude update *), and 4 are rules for other tools.

For anything the guard hook matches, "don't ask again" does not stick, and that is deliberate. The hook runs on every Bash call and decides afresh each time. Claude Code runs PreToolUse hooks before the permission prompt, and a hook's output "can deny the tool call, force a prompt, or skip the prompt" (permissions docs); a hook's ask even forces a prompt in auto mode. So when it prints "ask", you are asked again, whatever the allow list says. The script's header says it forces the prompt "regardless of prior approvals elsewhere in the session", and the reason it prints spells the rule out: "Per CLAUDE.md, every state-changing command needs its own explicit approval, even if an equivalent command was just approved on a different host or earlier this session." So every guarded command is accept-once. That is this project's own CLAUDE.md rule at work, not part of Raindancer118's setup. Consistent with it, none of the 26 saved rules matches one of the guard's patterns. If the guard seems to "forget" an approval you just gave, that's the design, not a bug.

So: the project's "never apply changes without asking" rule is partly structural now, not purely persuasion-only — but only for the specific list of Bash patterns above, only on the Bash tool, and only as an "ask," never a hard "deny." Everything else the rule covers (Edit/Write calls, MCP tool calls, any state-changing command outside that pattern list) is still enforced by nothing but the model reading CLAUDE.md and complying.

1.7 Step 6 — Execute, append result, loop

The tool result is appended to the context and the model runs again. Repeat until it emits no tool call. Then Stop fires.

Stop can refuse to let the turn end — the reason is fed back to the model, and the turn continues instead of ending. According to the author's own self-description (not sourced in any of the eight public repos — see Chapter 8 for the full account), Raindancer118 describes a Stop hook that "limits autonomous endless loops," which, read literally, is the inverse use of the mechanism: it would count forced continuations and stop blocking after some number of them, rather than being the source of the looping itself. The same self-description separately mentions a rate-limit mechanism where a session "waits in the background and continues on its own" after hitting a rate limit. Neither hook appears anywhere in the eight public repos, and how the rate-limit one is actually built is not stated. Both are flagged here as reported, not verified — Chapter 8 goes through the self-description in full and is the place to see what else falls into that same "described but not shipped" bucket.

1.8 Step 7 — Compaction, eventually

When the window fills, the harness summarizes older history and restarts from the summary. This is where state silently dies — and it's why diary-mcp's SessionStart hook distinguishes source == "compact" from other sources, re-injecting only the memories pinned with a compact trigger while a normal start re-injects the ones pinned with start (diary-mcp/scripts/session_start_hook.py). Read plainly, that's a design choice worth naming precisely: it treats compaction as a distinct event with its own retrieval rule, rather than treating "session just started" and "session just got summarized" as the same case. Whether that's rarer among memory systems generally is not something this chapter can support — no comparison data is available here — but it is a deliberate, verifiable design decision in this specific codebase.

One naming note for anyone trying to install this from the README: the README's registration example uses python3 ~/.claude/hooks/diary_session_start.py, but the file actually shipped in the repo is scripts/session_start_hook.py — the README's path reflects the author's own local copy name, not the repo's filename.

1.9 Subagents — the fifth thing

A subagent is a separate context window with its own system prompt, its own tool set, and its own model, whose final report is the only thing that returns to the parent. Defined in .claude/agents/*.md with frontmatter (name, description, tools, model).

A major benefit — not the only one, since subagents are also used for plain parallel fan-out — is context economy: an agent can read 40 files and hand back three paragraphs, and the parent only pays for the three paragraphs. Per the author's self-description, this is the shape of Raindancer118's own "orchestrator pattern" — a larger model plans, and subagents on a smaller model do the fan-out work (see Chapter 8); that specific pattern and its naming are not verified against any of the eight public repos, so treat it as reported rather than sourced.

1.10 What to take away

• A turn is context assembled fresh (system prompt, CLAUDE.md, tool schemas, skill listings, hook output, history, your prompt), sent to a stateless model, whose tool calls the harness then gates and executes.
• CLAUDE.md and skill descriptions are pure prompt text with no enforcement behind them; hooks and permission rules are the only layers the harness itself enforces, and strictly only for what they're written to match.
• This project already has one real PreToolUse hook and a sizeable permission allow-list — it is not the blank slate a purely "empty instance" framing would suggest, even though the user-level config genuinely is close to empty.
• Several vivid claims about this stack — the prompt-retrieval hook's exact behavior, the Stop-hook loop limiter, the rate-limit resume mechanism, the rules/*.md split, the orchestrator pattern's name — trace back to the author's own self-description rather than to code in the eight public repos; Chapter 8 is where all of those get checked against what's actually shipped.
• Tool and skill counts are exact where they come from counting real decorators (diary-mcp 73 + 7 admin, cachyos-mcp 111 bundled/21 standalone); token costs are rough estimates from docstring and parameter length, not measurements of what the harness actually transmits.

You already know the concept: an MCP server is a small program that hands an LLM harness a menu of things it can do. This chapter is the mechanism — the literal bytes that move between Claude Code and one of Raindancer118's servers, and why several design decisions in these repos only make sense once you've seen it.

This chapter in one table

2.1 The wire format

MCP is JSON-RPC 2.0. Nothing more exotic. For a local server, the transport is stdio: Claude Code spawns your server as a child process and speaks newline-delimited JSON over its stdin/stdout. Every server in this collection uses stdio (mcp.run(transport="stdio") in the FastMCP servers, StdioServerTransport in vault-mcp, server.ServeStdio in cis-api). The one exception is AIDEN/Serena (Ch 6), which also supports the two HTTP-based transports the spec defines — SSE and Streamable HTTP — selectable with --transport stdio|sse|streamable-http (volantic-codescope/src/serena/cli.py:264-265, default port 8000 at cli.py:278). Nothing else here runs over anything but stdio.

That single fact — one child process, one shared pipe — has consequences that show up everywhere in these repos:

stdout belongs to the protocol. One stray line of ordinary text on stdout is a byte sequence the client's JSON-RPC parser cannot make sense of. What the client then does about it — drop the message, log a parse error, tear down the connection — depends on the client; nothing in these repos specifies the failure mode, so treat any claim about that as harness-dependent, not protocol law. What is documented is the fix: never write anything but the protocol itself to that file descriptor. vault-mcp's launcher, vault-launch, states this in its header comment, and only the word "IMPORTANT" is capitalized:

"IMPORTANT: nothing is ever written to stdout — that fd belongs to the child's MCP JSON-RPC stream. All launcher diagnostics go to stderr." (vault-mcp/src/launch.ts:41-42)

The reason is specific to what the launcher does: it hands its own stdio straight through to the server it wraps (stdio: 'inherit'), so its stdout is that server's protocol stream. A single misplaced console.log in the launcher would land inside someone else's JSON-RPC traffic (Ch 4).

2.2 The handshake, step by step

1. Spawn. Claude Code reads your config and runs the command:

{ "mcpServers": { "diary": {
    "command": "diary-mcp",
    "env": { "DIARY_DATABASE_URL": "postgresql://localhost/diary_mcp" } } } }

For a stdio server, the config's env block (and, for some launchers, command-line args) is the only channel Claude Code gives you for configuration and credentials at spawn time — there is no separate secrets API. That convention is the seam vault-launch exploits (Ch 4): the launcher's own header calls environment injection "exactly how the vast majority of MCP servers already accept credentials" (vault-mcp/src/launch.ts:13-14), so it resolves secrets from a vault and injects them as env vars into the wrapped server's process, with no code changes to that server. It isn't the only credential path in this set, though: vault-launch can also substitute a resolved secret into the child's argv (--arg PH=ItemRef, launch.ts:34), and cis-api's cis_login tool takes a password directly as a tool argument (cis-api/cmd/mcp.go:78), reusing a saved session file if you ran cis login first (Ch 7).

2. initialize — the client sends its protocol version and capabilities; the server replies with its name, version, and which of three spec-defined capability families it offers:

Seven of the eight repos here ship an MCP server at all: diary-mcp, vault-mcp, sysprobe-mcp, network-mcp, cachyos-mcp, AIDEN (via Serena), and cis-api. The eighth, claude-accounts (ccacct), is a plain bash CLI with no MCP SDK anywhere in it — it only reads and preserves the mcpServers block inside ~/.claude.json as one of the config keys it manages (claude-accounts/bin/ccacct:39,180, see Ch 7). Every one of the seven real servers registers tools only: grepping all of them for resource or prompt registrations (@mcp.resource, @mcp.prompt, ListResources, ListPrompts, registerResource, registerPrompt) turns up nothing. vault-mcp is explicit about it — its capabilities object is literally { capabilities: { tools: {} } } (vault-mcp/src/index.ts:663) — and cis-api's Go SDK call is server.WithToolCapabilities(true) with no resource/prompt equivalent (cis-api/cmd/mcp.go).

That doesn't mean tools are the only thing Claude Code can reach for in general — it's a fact about this set of servers, not a ceiling on the client. Claude Code does surface the other two families when a server offers them: MCP resources can be @-mentioned, and the model has built-in list/read tools for them; MCP prompts show up as /mcp__<server>__<prompt> slash commands. None of these seven servers registers either, so none of that machinery is in play here. What is in play: four of the seven servers also send a free-text instructions string in the same initialize reply — server-wide usage guidance the client can pass to the model, separate from any individual tool's description. cachyos-mcp's, for instance, opens with the package-search steering you'll see again in 2.3, and closes by pointing at SYSCONTROL_ALLOW_ACTIONS (cachyos-mcp/src/cachyosmcp/server.py:9-27); network-mcp and sysprobe-mcp send their own versions (network-mcp/src/netmcp/server.py:9-19, sysprobe-mcp/src/sysprobe/server.py:9-23); and AIDEN/Serena builds one dynamically (volantic-codescope/src/serena/mcp.py:366-374).

3. notifications/initialized — handshake done.

Here is that whole sequence for a real server in this set — sysprobe-mcp, spawned as a child process over stdio, through one tools/call at the end. Two panes: what Claude Code writes to the child's stdin, and what the child writes back on its stdout — one JSON-RPC message per line, in the order 2.2–2.4 walk through. The protocolVersion string, the capabilities object's exact shape, clientInfo/serverInfo version fields, and the request id numbering are MCP-spec/SDK-internal details none of these repos pin down — illustrative and version-dependent throughout. Everything else is sysprobe-mcp's real source: the server name and its instructions text (sysprobe-mcp/src/sysprobe/server.py:9-24,28, abridged with …; version 0.1.0 from sysprobe-mcp/pyproject.toml:3), and list_directory_tree's actual signature, docstring, and return shape (sysprobe-mcp/src/sysprobe/diag.py:34-42,81-82). The tools/list result below is exactly what the harness later pastes into every model request as that tool's definition (2.3); the tools/call request's arguments are exactly what the model's own tool_use JSON carried (2.4) — nothing is added or removed in between.

{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "claude-code", "version": "…"}}}
 spawning sysprobe-mcp

{"jsonrpc": "2.0", "id": 1, "result": {"protocolVersion": "2025-06-18", "capabilities": {"tools": {}}, "serverInfo": {"name": "sysprobe-mcp", "version": "0.1.0"}, "instructions": "Token-efficient Linux system diagnostics + desktop/hardware control. Tools\nreturn compact JSON with hard size limits. …"}}

{"jsonrpc": "2.0", "method": "notifications/initialized"}
{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}
 collecting 59 tool schemas (diag + services + desktop)

{"jsonrpc": "2.0", "id": 2, "result": {"tools": [{"name": "list_directory_tree", "description": "Compact directory tree (names + sizes), depth/entry-bounded.\n\nUnderstand a config dir's structure without reading any file contents.\nArgs: path, max_depth (1–6), max_entries cap, show_hidden.", "inputSchema": {"type": "object", "properties": {"path": {"type": "string"}, "max_depth": {"type": "integer", "default": 2}, "max_entries": {"type": "integer", "default": 300}, "show_hidden": {"type": "boolean", "default": true}}, "required": ["path"]}}, "… 58 more tool schemas omitted …"]}}

{"jsonrpc": "2.0", "id": 7, "method": "tools/call", "params": {"name": "list_directory_tree", "arguments": {"path": "~/.config", "max_depth": 1, "show_hidden": false}}}
 running list_directory_tree

{"jsonrpc": "2.0", "id": 7, "result": {"content": [{"type": "text", "text": "{\"root\": \"/home/user/.config\", \"entries\": [{\"path\": \"kdeglobals\", \"type\": \"file\", \"bytes\": 812}, {\"path\": \"autostart\", \"type\": \"dir\"}, …], \"count\": 14, \"truncated\": false}"}]}}

2.3 tools/list: the moment the catalogue is built

The server returns its catalogue. Here is what diary-mcp's memory_search actually looks like on the wire (abridged — FastMCP also adds a title per property, omitted here):

{ "tools": [ { "name": "memory_search",
               "description": "Hybride Suche im Memory-Tree: FTS + semantische Suche, fusioniert via RRF. …",
               "inputSchema": { "type": "object",
                 "properties": {
                   "query": {"type": "string"},
                   "include_extracted": {"type": "boolean", "default": false},
                   "include_expired": {"type": "boolean", "default": false}
                 },
                 "required": ["query"] } } ] }

(diary-mcp/search_engine.py:212-218; the real signature is def memory_search(query: str, include_extracted: bool = False, include_expired: bool = False) -> str, not the query/limit pair you might expect from a generic search tool.)

The harness turns that catalogue into tool definitions sent alongside every model request. Whether the entire schema is present from the first turn depends on the harness: in the Claude Code session that produced this guide, most tools were initially listed by name only, with full schemas loaded on demand through a ToolSearch tool ("deferred tools", see Ch 1). Either way — paid up front or paid on first lookup — whatever schema reaches the model is context, and the model never "queries" the server directly; it sees a static list of function signatures (plus, where the server sent one, its instructions string) and predicts a call from that.

A few things follow from that:

• The description field is one of the main levers steering tool choice, not the only one. Alongside it sit the tool's name, its parameter schema, and — for the four servers that send one — the initialize-time instructions string. cachyos-mcp uses that string explicitly: "prefer search_all_repositories (repos + AUR in one call) to avoid hallucinated package names" (cachyos-mcp/src/cachyosmcp/server.py:13-14). That line is not a tool description at all; it is server-wide guidance the model reads once at session start.
• Individual tool docstrings carry the same kind of steering, one level down. sysprobe-mcp's read_config_snippet opens its docstring with "Read a slice of a text/config file — never the whole thing blindly." (sysprobe-mcp/src/sysprobe/diag.py:88) — an instruction to the model, phrased as documentation, because with FastMCP the docstring is what the model sees as the description. (A related-looking line, "the anti-hallucination tool: see every available variant + votes + installed," is not a tool description at all — it's README prose about search_all_repositories, cachyos-mcp/README.md:14-15, and the model never sees it. What the model does see for that tool is the docstring itself: "Search official repos AND the AUR in one call; unified, sorted result. … The single most token-efficient way to answer 'is package X available and which variant should I use?'", cachyos-mcp/src/cachyosmcp/arch.py:231-235.)
• FastMCP — the high-level server API bundled inside the official mcp Python SDK, imported as from mcp.server.fastmcp import FastMCP (not the separate standalone fastmcp package) — derives each tool's inputSchema from the Python function signature and its description from the docstring. Raindancer118 uses it for diary-mcp, sysprobe-mcp, network-mcp and cachyos-mcp (e.g. sysprobe-mcp/src/sysprobe/server.py:5; dependencies mcp>=1.28.0,<2 for diary-mcp, mcp[cli]>=1.2.0 for the other three), and AIDEN/Serena builds on the same class for its own tool layer (volantic-codescope/src/serena/mcp.py:13-15, pinned mcp==1.27.0; see Ch 6). That's why those docstrings read like instructions with the important limits called out ("Hard cap max_lines") — they're going straight into the model's context as the API contract. The hard numeric bounds themselves, though, tend to live in code rather than prose: read_config_snippet's 1–1000 line cap is enforced by clamp(int(max_lines), 1, 1000) in the function body (diag.py:96), not spelled out in the docstring.
• vault-mcp uses the raw TypeScript SDK and hand-writes each inputSchema (ListToolsRequestSchema handler, vault-mcp/src/index.ts). More verbose, more control — and it needs the control, because parameters like confirmed and exposedToAI carry semantics the model must not paper over (2.5c).
• cis-api is Go, built on github.com/mark3labs/mcp-go; its schemas are assembled with builder calls like mcp.WithString("password", mcp.Required(), mcp.Description("Your CIS password")) (cis-api/cmd/mcp.go) and served with server.ServeStdio(s) (Ch 7).

What FastMCP derives, concretely. sysprobe-mcp's read_config_snippet is a plain function with a docstring:

@mcp.tool()
def read_config_snippet(filepath: str, start_line: int = 1,
                        end_line: int = 0, grep_pattern: str = "",
                        context: int = 3, max_lines: int = 200) -> dict[str, Any]:
    """Read a slice of a text/config file — never the whole thing blindly.

    If grep_pattern is set, returns only matching blocks (+context lines);
    otherwise returns lines [start_line, end_line]. Hard cap max_lines.
    """

(sysprobe-mcp/src/sysprobe/diag.py:84-92) Nothing else about this tool reaches the model — no separate spec file, no hand-written schema. What FastMCP builds from just that signature and docstring, and hands the client in tools/list, is (approximate — the real SDK also emits a title per property, as noted above, and exact handling of a bare "" default may vary by version):

{ "name": "read_config_snippet",
  "description": "Read a slice of a text/config file — never the whole thing blindly.\n\nIf grep_pattern is set, returns only matching blocks (+context lines);\notherwise returns lines [start_line, end_line]. Hard cap max_lines.",
  "inputSchema": { "type": "object",
    "properties": {
      "filepath": {"type": "string"},
      "start_line": {"type": "integer", "default": 1},
      "end_line": {"type": "integer", "default": 0},
      "grep_pattern": {"type": "string", "default": ""},
      "context": {"type": "integer", "default": 3},
      "max_lines": {"type": "integer", "default": 200}
    },
    "required": ["filepath"] } }

Notice what's missing: the docstring's "Hard cap max_lines" is prose the model reads, not a schema constraint the protocol enforces. The actual 1–1000 clamp lives in code (clamp(int(max_lines), 1, 1000), diag.py:96) — nothing in this JSON stops the model from requesting max_lines: 999999; the call would just come back silently clamped.

2.4 tools/call: request and response

Request: {"name": "memory_search", "arguments": {"query": "Ficus"}}. The response is a content array — for diary-mcp, which returns plain str, that's a single {"type":"text"} block. Several of Raindancer118's other Python tools return a dict[str, Any] instead (e.g. read_config_snippet, search_all_repositories); FastMCP serializes that into a JSON text block, and depending on the SDK version may also mirror it as a separate structuredContent field alongside the text. AIDEN's own diary client — itself an MCP client, talking to a diary-mcp it spawns (Ch 6) — is written to prefer that structured form and fall back to the text blocks:

if result.isError:
    details = "\n".join(item.text for item in result.content if isinstance(item, TextContent))
    raise DiaryBridgeError(details or f"Diary tool {tool_name!r} failed")
if result.structuredContent is not None:
    structured_result = result.structuredContent.get("result")
    if isinstance(structured_result, str):
        return structured_result

(volantic-codescope/src/aiden/diary.py:144-151). Notice also that a tool failure is not a JSON-RPC error — it's an ordinary result with isError: true plus text content, which is why the code above checks that flag rather than catching an exception from the transport.

A dict-returning tool, on the wire. cachyos-mcp's search_all_repositories is one of the tools this applies to:

@mcp.tool()
def search_all_repositories(query: str, limit: int = 20) -> dict[str, Any]:
    """Search official repos AND the AUR in one call; unified, sorted result.

    Lets the model weigh repo vs AUR (open-source vs -bin, votes, installed)
    without separate round-trips. The single most token-efficient way to
    answer "is package X available and which variant should I use?".
    """

(cachyos-mcp/src/cachyosmcp/arch.py:230-236) — it ends by building a plain dict, {"query": query, "results": combined[:...], "repo_count": len(repo_rows), "total": len(combined)} (arch.py:259-261). A call, and the reply FastMCP actually puts on the wire — the dict serialized into a single JSON text block (query and result values below are illustrative):

Request:  {"name": "search_all_repositories", "arguments": {"query": "ripgrep", "limit": 5}}
Response: { "content": [ { "type": "text",
  "text": "{\"query\": \"ripgrep\", \"results\": [{\"name\": \"ripgrep\", \"source\": \"extra\", \"version\": \"14.1.0-1\", \"installed\": true, \"description\": \"…\"}, {\"name\": \"ripgrep-all\", \"source\": \"aur\", \"version\": \"0.10.6-1\", \"installed\": false, \"description\": \"…\", \"aur_votes\": 42, \"popularity\": 1.2, \"out_of_date\": false}], \"repo_count\": 1, \"total\": 2}" } ] }

No structuredContent field is shown here on purpose — whether it's mirrored alongside the text block for a dict-returning tool like this one is exactly the SDK-version-dependent detail flagged above; the text block is the part every version agrees on.

Whatever comes back — text block or structured content — is fed into the model's context as the tool result.

2.5 Three consequences that shape these repos

(a) Everything the server returns stays in the conversation. It costs context when it arrives, and it is sent again on every later model request in the session until compaction or the session ends (prompt caching makes those re-reads cheaper, not free). That's plausibly the main reason behind common.py's clamp() helpers (network-mcp/src/netmcp/common.py:159-160, sysprobe-mcp/src/sysprobe/common.py:163-164), the ts_headline snippets capped at 25 words (diary-mcp/search_engine.py:136-137), the 160–200-character substr(coalesce(body,''), 1, 200) body previews (diary-mcp/search_engine.py:152, with 160-char variants at lines 91, 99, 413, 423), and AIDEN's middle-folded code previews, which keep a hit's signature and return value and drop the middle rather than "burn its context" with the whole body (volantic-codescope/src/aiden/index/search.py:165-166). A tool that dumps journalctl unbounded can cost more than the task it was called for.

(b) One stdio connection is one process, and nothing is shared between processes unless you build it. MCP does have sessions — over stdio, a session's lifetime is simply the spawned process's lifetime, from initialize to the pipe closing. What that buys you is isolation, not sharing: every running Claude Code session spawns its own fresh diary-mcp (and AIDEN spawns its own copy again for its internal diary client, Ch 6), so two engineering problems fall directly out of "no sharing across processes":

• diary-mcp: "every diary-mcp process (one per running Claude Code session) loads its own copy of the fastembed ONNX model (~470MB)... With several sessions open at once, that's N copies of the same model in RAM for no reason" (diary-mcp/diary_embed_ipc.py:5-8) → the Unix-socket election in Chapter 3.
• vault-mcp: the bw CLI's local vault cache (BITWARDENCLI_APPDATA_DIR/data.json) "is a plain file with no locking of its own," and this machine "routinely runs many independent processes against the same vault instance concurrently — vault-mcp itself plus one vault-launch child per downstream MCP server (cis, obsidian, spoticontrol, github, gemini, ...), all spawned in a burst on every Claude Code restart" (vault-mcp/src/vault/bw-client.ts:96-101). Session setup is a multi-step sequence (status → logout → config server → login → unlock), and two processes interleaving that sequence corrupt each other's state — one sees unauthenticated, another logs in underneath it, and the first then fails with "Logout required before server config update" (bw-client.ts:106-113). A whole restart "can queue a dozen vault-launch children" behind each other on the same instance (bw-client.ts:116-117). → the FIFO-queued cross-process lock in Chapter 4 (bw-client.ts:171-173).

Both are two-line consequences of the same fact: nothing about MCP gives you a shared process, a shared cache, or a shared lock across sessions. If your server needs one, you write it yourself.

(c) Where it matters most, the guardrail lives server-side, out of the model's reach. SYSCONTROL_ALLOW_ACTIONS is read from the server's own environment at call time (sysprobe-mcp/src/sysprobe/common.py:145-149), never from a tool argument — no MCP call can flip it. The model does learn that the gate exists: a refused call returns {"error": "action disabled", "hint": "set SYSCONTROL_ALLOW_ACTIONS=1 in the MCP server env to enable mutating tools (default is read-only)."} (network-mcp/src/netmcp/common.py:152-154), and the instructions strings name it outright ("Updates/installs … need SYSCONTROL_ALLOW_ACTIONS=1," cachyos-mcp/src/cachyosmcp/server.py:17-18). So the model can see the gate and even ask you to open it — it just can't open it itself through the protocol. That's a real, structural difference from a rule the model merely reads and is expected to honor, the way a CLAUDE.md instruction is.

It's worth being precise about where this pattern does and doesn't apply, though: not every safety property in these repos is out of the model's hands. vault-mcp's own gates on destructive operations — confirmed and, for secret disclosure, exposedToAI — are ordinary boolean tool arguments the model fills in itself (vault-mcp/src/index.ts:209-225); the server simply refuses the call if they're missing or false. That makes disclosure a deliberate, visible, named action rather than an accident — but it is a softer gate than SYSCONTROL_ALLOW_ACTIONS, because the model supplies the value that unlocks it. The two patterns sit at different points on the same idea: put the hardest guardrails where the model isn't, and use visible, named arguments for the ones that only need to slow it down.

The two-step gate, on the wire. The handler checks both booleans in order and, if either is missing, returns a plain string — not a JSON-RPC error, not isError: true:

if (!confirmed) return 'Set confirmed=true as first confirmation.';
if (!exposedToAI) {
  return 'Set exposedToAI=true as second confirmation, explicitly acknowledging that the AI will see the secret value in plaintext.';
}

(vault-mcp/src/index.ts:916-919) A call with only confirmed set gets turned back exactly like any other successful tool result:

Request:  {"name": "vault_reveal_password", "arguments": {"itemId": "web1-root-ssh", "confirmed": true}}
Response: { "content": [ { "type": "text", "text": "Set exposedToAI=true as second confirmation, explicitly acknowledging that the AI will see the secret value in plaintext." } ] }

Only once the model supplies both does the call go through, returning the shape getItemSensitive actually produces — id, name, type, password, notes, hiddenFields, totp (vault-mcp/src/vault/bw-client.ts:45-57; the values below are illustrative, not a real vault item):

Request:  {"name": "vault_reveal_password", "arguments": {"itemId": "web1-root-ssh", "confirmed": true, "exposedToAI": true}}
Response: { "content": [ { "type": "text", "text": "{\n  \"id\": \"5f2e…\",\n  \"name\": \"web1 root ssh\",\n  \"type\": 1,\n  \"password\": \"•••\",\n  \"notes\": null,\n  \"hiddenFields\": [],\n  \"totp\": null\n}" } ] }

The text is pretty-printed because vault-mcp serializes every non-string result with JSON.stringify(result, null, 2) before sending it (vault-mcp/src/index.ts:673); a string result, like the refusal above, goes out as-is. Both replies are ordinary, successful tools/call results. The refusal is just text the model has to read and act on itself — the same channel as any other tool output, not a separate enforcement path.

2.6 What to take away

• MCP over stdio is JSON-RPC 2.0 on a pipe you must never write stray text to; the harness treats stdout as the protocol channel, full stop.
• Of these eight repos, seven ship an MCP server and all seven expose tools only — no resources, no prompts — though four also send a server-wide instructions string alongside the tool catalogue.
• A tool's name, schema, docstring, and any instructions string are all prompt engineering aimed at the model; the docstring is not documentation you can write loosely.
• Every server here is a fresh process per client session with nothing shared across processes by default — a fact that directly caused the ONNX-copy problem in diary-mcp (Ch 3) and the vault burst-locking problem in vault-mcp (Ch 4).
• The strongest safety guarantees live server-side, read from the process environment and unreachable through any tool call; softer guardrails (confirmed, exposedToAI) are visible arguments the model itself must supply.

3.0 At a glance

This chapter is about the main server's memory system — storage, retrieval, the knowledge graph, the hooks that make it run without being asked, the embedding-sharing trick, sync, and federation. The admin server's 7 tools (memory_infer_links, memory_explain, memory_path, memory_graph_stats, memory_query_graph, memory_report) are graph-maintenance tools meant for a human to invoke deliberately, not something an agent reaches for mid-task; they are mentioned where relevant but not covered tool-by-tool.

3.1 What problem it solves

Compaction and session end destroy state. A flat-file memory index — a MEMORY.md plus one file per topic, updated by hand or by agent discipline — solves that with files and self-discipline. diary-mcp solves it with a database, a ranking function, and hooks that don't depend on that discipline at all: the memories that matter get back into context whether or not the agent remembers to ask for them.

3.2 The storage layer (diary_db.py)

One Postgres table carries the memory tree. The actual DDL (diary_db.py:226–241, plus columns added by later idempotent ALTER TABLE statements further down the same schema list) is:

memory_nodes(
  id           UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  parent_id    UUID REFERENCES memory_nodes(id) ON DELETE CASCADE,
  path         TEXT NOT NULL UNIQUE,        -- '/projects/web1/nginx-setup'
  slug         TEXT NOT NULL,
  type         TEXT NOT NULL DEFAULT 'note',
  title        TEXT NOT NULL,
  body         TEXT,
  tags         TEXT[] DEFAULT '{}',
  importance   REAL DEFAULT 0.5 CHECK (importance >= 0 AND importance <= 1),
  access_count INTEGER DEFAULT 0,
  accessed_at  TIMESTAMPTZ,
  valid_until  TIMESTAMPTZ,                 -- decay: expired nodes drop out of search
  origin       TEXT NOT NULL DEFAULT 'curated',   -- curated | extracted
  config       JSONB DEFAULT '{}',          -- per-node settings, e.g. auto_extract
  created_at   TIMESTAMPTZ DEFAULT now(),
  updated_at   TIMESTAMPTZ DEFAULT now(),   -- the last-write-wins clock, see 3.8
  embedding    REAL[],                      -- 384-d, numpy fallback path
  embedding_v  vector(384),                 -- pgvector column, added if the extension is available
  pin_triggers TEXT[] DEFAULT '{}',         -- 'start' and/or 'compact', see 3.6
  deleted_at   TIMESTAMPTZ                  -- tombstone, see below
)

embedding_v gets an HNSW index (vector_cosine_ops) once pgvector is confirmed present (diary_db.py:446–449); pin_triggers gets a partial GIN index (WHERE pin_triggers <> '{}', diary_db.py:265).

Plus memory_links(from_id, to_id, rel_type, link_origin) for the graph, and diary_meta as a local-only key/value store deliberately excluded from sync — it holds the per-remote last-sync timestamp, which would be meaningless to sync (diary_db.py:295–301).

Three choices worth pausing on:

• UUID primary keys. The DDL comment credits them with enabling bidirectional sync (diary_db.py:226: "UUID PKs enable bidirectional sync with Dorn"). In the sync code that actually runs today, though, rows are matched by the unique path column, not by id — each database mints its own UUID independently, and parent_id isn't transferred at all; it's re-derived from the path after the fact (sync_manager.py:26–36, 344–355). So the UUID choice removes one obvious collision risk (two machines can each insert new rows without fighting over a shared counter), but the actual cross-machine identity that makes sync work is the path, not the id.
• Tombstones, not permanent deletes on write. Under last-write-wins sync, a hard delete is indistinguishable from "the other side has a row I don't" — so the next sync would resurrect it. Setting deleted_at makes deletion a fact that propagates instead. Every read path filters deleted_at IS NULL. This isn't "never a hard delete" forever, though: memory_purge_tombstones(older_than_days=30) later runs a real DELETE FROM memory_nodes WHERE deleted_at < now() - interval on both sides once a tombstone is old enough that it's had time to propagate (memory_service.py:673–693). The soft-delete is about not corrupting sync in the short term, not about permanent retention.
• valid_until. Memory that expires on its own. "The deploy freeze lasts until March" shouldn't need manual cleanup.

The schema is applied as CREATE TABLE IF NOT EXISTS plus a long, idempotent list of ALTER TABLE ... ADD COLUMN IF NOT EXISTS statements, run in full on every start (init_db(), diary_db.py:453 ff.). Migration-by-convergence: no migration tool, no version table, every start just re-asserts the target schema. For a single-owner tool this means it's never in a half-migrated state — but "idempotent" has to be taken literally, and the repo has a scar showing what happens when it isn't: an earlier version of init_db() re-added two now-retired columns (auto_inject, reinject_on_compact) on every startup and then immediately dropped them again in a one-time backfill block that never should have kept running. Postgres never reclaims a dropped column's slot number, so after enough restarts memory_nodes hit the hard 1600-column-slot limit and every subsequent server start crashed with psycopg.errors.TooManyColumns. The fix (d74f024, 2026-09-14) removed the dead add/drop pair and rebuilt the table to reclaim 1,578 dead slots. It's a good illustration of the tradeoff: convergent, idempotent schema application is simple and safe against half-migrations, right up until one of the statements in the list isn't actually a no-op on a converged table.

Related to that: the retired trigger_keywords column (see 3.6) is kept in the schema rather than dropped. The DDL comment next to it (diary_db.py:359–364) still describes it as a live feature checked by a Stop hook — that comment is now stale relative to the retirement; the accurate statement of intent is in the test suite instead: "the trigger_keywords DB column stays in the schema (no destructive migration on the live synced DB), but the tools are gone" (tests/test_memory.py:1499–1505).

3.3 Retrieval: the actual ranking math

This is the core of the product, so it's worth being precise about what the code does, as opposed to what its comments say it's trying to do — the two aren't quite the same here.

Two candidate lists, 30 each (search_engine.py:120–176):

Lexical — Postgres FTS with the German text config:

ts_rank(to_tsvector('german', coalesce(title,'') || ' ' || coalesce(body,'')),
        plainto_tsquery('german', %s)) AS sim,
ts_headline('german', coalesce(body,''), plainto_tsquery('german', %s),
            'MaxWords=25,MinWords=10,StartSel=«,StopSel=»') AS snippet
ORDER BY sim DESC LIMIT 30

ts_headline is why results come back with «highlighted» fragments rather than whole bodies — a token-budget decision baked into the query.

Semantic — if pgvector is present, ORDER BY embedding_v <=> %s::vector LIMIT 30 (HNSW-accelerated, <=> = cosine distance). If not, it pulls every embedded row and computes cosine in Python (search_engine.py:163–176). That fallback is O(n) per search but keeps the tool working on a box without the extension — a "degrade, don't fail" choice you'll see repeated across the rest of this stack.

Fusion — Reciprocal Rank Fusion, k=60 (Cormack et al. 2009), computed by _rrf_fuse (search_engine.py:59–79):

RRF(d) = 1/(60 + rank_fts(d)) + 1/(60 + rank_vec(d))

with a document missing from a list scored at rank = len(list) + 1 — the worst possible rank in that list, not a neutral value.

The stated reason for RRF over blending raw scores is sound: ts_rank (a per-document lexeme-frequency statistic — it has no corpus-wide IDF term, unlike a real tf-idf score) and cosine similarity are incomparable quantities, and any weighted sum of the two is a fudge factor that drifts as the corpus changes. RRF sidesteps that by keeping only rank positions, which are comparable by construction.

But here's the part worth being exact about: _rrf_fuse computes an RRF-ordered list of paths, and _hybrid_retrieve uses that order to decide which rows make the merged candidate set and to fill in a rank-based sim value only for rows that don't already have one (search_engine.py:177–190). In practice, every row from the FTS query already carries its own ts_rank, and every row from the vector query already carries its own cosine similarity — so the 1/(i+1) RRF-derived fallback score almost never actually gets used. The merged set is then re-ranked one more time by _apply_ranking, which sorts by each row's original, incomparable ts_rank-or-cosine value (see the re-ranking formula below), not by the RRF score. So: RRF genuinely decides which documents survive into the top 30-ish candidates and gives them a fair combined shot at appearing regardless of which single list ranked them, but the final displayed order is driven by the raw, scale-incompatible similarity numbers RRF was introduced specifically to avoid comparing. The RRF ordering only survives as a stable-sort tiebreak. Treat this as an observation about what the shipped code does, not a claim about what the docstrings say it's for — the two disagree here, and the code is what actually runs. AIDEN reuses the same rank-fusion idea in a different form (a weighted variant, without the missing-rank penalty, over up to four lists) — see Chapter 6 for the details; the two implementations are related in spirit, not identical.

Re-ranking (_apply_ranking, search_engine.py:23–56):

final = sim * (0.5 + 0.5 * importance) + 1e-6 * (1 / (1 + days_since_update))

Importance scales the similarity by a factor between 0.5 and 1.0 — it can reduce a score by at most half, never boost it above the raw similarity. That is enough to reorder two hits whose similarities are within roughly a factor of two of each other (a similarity of 0.6 at importance=1.0 scores 0.60, while a similarity of 0.9 at importance=0.1 scores 0.495 — the less-similar-but-more-important hit wins), so "importance can reorder results" is a real, not merely theoretical, effect; it just can't invert an overwhelming similarity gap. There's also a small implementation quirk: the code reads importance as r.get("importance", 0.5) or 0.5, so an importance of exactly 0.0 is falsy in Python and gets silently treated as 0.5 rather than as "minimum importance." The recency term, at 1e-6, is far too small to change the ordering except between near-identical scores — a tiebreaker, not a ranking signal.

A worked example, with invented numbers (illustrative — a real search hits real database rows). Say the FTS list ranks /projects/web1/nginx-ssl 1st and doesn't return /user/ssh-keys at all — a miss scores as len(list)+1, so rank 31 out of a 30-row list. The vector list ranks the same two paths 3rd and 1st:

path                        rank_fts   rank_vec
/projects/web1/nginx-ssl    1          3
/user/ssh-keys              31 (miss)  1

RRF(d) = 1/(60+rank_fts) + 1/(60+rank_vec):

RRF(nginx-ssl) = 1/(60+1)  + 1/(60+3)  = 0.016393 + 0.015873 = 0.032266
RRF(ssh-keys)  = 1/(60+31) + 1/(60+1)  = 0.010989 + 0.016393 = 0.027382

So nginx-ssl edges out ssh-keys in the RRF-fused order — that number is what decides which rows survive into the merged candidate set. But the final displayed order comes from _apply_ranking on each row's own raw similarity, not from these two numbers. Say nginx-ssl's own ts_rank is 0.51 with importance=0.6, and ssh-keys's own cosine similarity is 0.83 with importance=0.4, both updated within the last day (recency ≈ 1.0):

final(nginx-ssl) = 0.51 * (0.5 + 0.5*0.6) + 1e-6*1.0 = 0.51 * 0.8 = 0.4080
final(ssh-keys)  = 0.83 * (0.5 + 0.5*0.4) + 1e-6*1.0 = 0.83 * 0.7 = 0.5810

ssh-keys wins the final order despite losing the RRF race: the raw similarity gap (0.83 vs. 0.51) is what actually decides the displayed order — the exact point made above. (_rrf_fuse, search_engine.py:59–79; _apply_ranking, search_engine.py:23–56.)

Mode labelling. The result is tagged Hybrid/RRF, FTS, or Semantisch depending on which of the two lists came back non-empty — and, if both are empty, the query falls back further still to a plain ILIKE '%query%' substring scan over title/body with a fixed similarity of 0.1, labelled LIKE (search_engine.py:197–206). That label is returned to the caller, so it's possible to tell from a single search call whether it ran as intended, degraded to lexical-only or semantic-only, or bottomed out at a substring scan.

Here is what that looks like from the caller's side (invented query and body content — a real call returns real database rows):

memory_search(query="nginx ssl setup")

Memory-Suchergebnisse [Hybrid/RRF, kuratiert, ohne abgelaufene] für 'nginx ssl setup':

[project] /projects/web1/nginx-ssl — Let's Encrypt renewal via certbot  Score 0.4080
  «SSL»-Zertifikat wird per certbot-Timer erneuert, «nginx» lädt danach automatisch neu…

— Hinweis: 2 weitere Treffer in auto-extrahierten Memories (kostspieliger). Mit memory_search(query, include_extracted=True) durchsuchbar.

The [Hybrid/RRF, kuratiert, ohne abgelaufene] line is the mode label from _hybrid_retrieve plus the tier scope and the (default-on) expired-memory exclusion note; the «guillemets» around matched terms come straight from ts_headline's StartSel/StopSel options (3.3 above); and the trailing Hinweis line is the extracted-tier count check — a nudge toward include_extracted=True, not the results themselves. (memory_search, search_engine.py:212–310, output assembly at 288–309.)

3.4 Two tiers and the tripwire

curated = saved on purpose. extracted = harvested from transcripts by the SessionEnd hook (see 3.6).

Extracted memories are excluded from default search — otherwise auto-harvested noise would swamp deliberate knowledge. But a tier that's never read is just a write-only log, so: after a normal search, a second pass checks the extracted tier for anything with cosine ≥ 0.85 (TRIPWIRE_SIMILARITY_THRESHOLD, search_engine.py:16) to the query and appends up to 3 hits (TRIPWIRE_MAX_HITS) as a "see also" hint.

The design principle generalizes: when you suppress a data source for signal-to-noise reasons, keep one high-precision channel open so it can still surface when it's unambiguously relevant.

3.5 The knowledge graph, and the contradiction mechanism

Typed edges: related, supports, contradicts, requires, derived_from. Each is tagged link_origin = explicit | inferred so a human-asserted edge is distinguishable from a cosine-similarity guess. (Named link_origin in SQL specifically so it isn't confused with memory_nodes.origin — curated/extracted, an unrelated axis — and aliased back to origin on read so calling code always just sees row["origin"]; that naming decision is documented right in the DDL comment, diary_db.py:243–248.)

The feature that earns the graph its keep: _contradiction_warnings surfaces any contradicts edge touching a node inline, on both memory_search results and memory_get (memory_service.py:63–89, 240–241). Not in a report that has to be run deliberately — at the point of reading. One important precision here, though: nothing in the codebase creates contradicts edges automatically. Both the write-time auto-linker and the nightly batch inference job only ever insert related/inferred edges (memory_service.py:296–333; graph_admin.py:142). A contradicts edge exists only once someone calls memory_link(from, to, rel_type="contradicts") explicitly (graph_core.py:15–21). What _contradiction_warnings does is surface an existing edge at read time — it doesn't detect contradictions on its own.

That distinction matters for a concrete case: a memory recording that a host's IPv6 egress was broken, later updated to say it works again as of a specific date, is — if stored the way a flat-file memory index would store it — a single entry edited in place, not two nodes. Updating one node in place needs no edge at all; there's nothing to contradict, because there's only ever one current fact. The contradicts mechanism only pays off for the case where the old and new claims are kept as two separate nodes (say, a historical log entry plus a current-status entry) and someone has explicitly linked them — then reading either one would surface the warning. It's a real feature, just one that requires a human (or agent) to have made the link, not one that watches the tree for disagreements on its own.

Links get created two ways, and the same write-time/batch pattern shows up twice more in this repo — for links themselves and for federation push; the backup export (see the table below) is batch-only, so it's not a third instance of the same two-speed pattern:

Per the README, the author runs these three jobs as systemd user timers on their own machine, daily at 04:00 (backup), 04:15 (link sync), and 04:30 (link inference) — in that order, deliberately, so backup runs before the other two touch anything. The unit files themselves are not part of the public repo; only the scripts and the suggested schedule are.

A concrete call shows both write-time paths from the table above firing on one save (illustrative path/body/link-alias content — the mechanism and message format are real):

memory_upsert(
  path="/projects/web1/nginx-ssl",
  title="Let's Encrypt renewal via certbot",
  body="Cert renews via a certbot systemd timer; nginx reloads automatically once the renewal hook runs.",
  tags="web1,nginx,ssl"
)

Memory '/projects/web1/nginx-ssl' erstellt. (+2 auto-verlinkt: /projects/web1/nginx-setup, /user/cert-renewal-policy) (an 1 Diary-Link(s) auto-gesynct: laptop)

Three things happened inside one call, and the return message reports all three: the node was inserted; its freshly-computed embedding was compared against every other curated node, two scored above AUTO_LINK_THRESHOLD (0.82), and _auto_link_new_node inserted related/inferred links to both, capped at AUTO_LINK_MAX_NEW=3; and because tags was non-empty, push_node_on_upsert checked it against the laptop link's sync_tags and pushed this one node over federation. Call it again with tags="" and the last clause — if origin == "curated" and tag_list: — never runs, so the message would stop after the auto-link parenthetical. (memory_upsert, memory_service.py:341–419; auto-link at 296–338; message assembly at 385–417.)

The write-time pass is nearly free (the embedding was already computed for the save) and immediate; the small cap stops one save from spamming dozens of edges. The batch pass, with its much higher cap, catches what the per-save cap dropped and what a transient outage lost. Cheap-and-immediate plus thorough-and-slow — that's the shape, and it repeats.

One more federation-specific detail: diary_link_sync's push is a delta by updated_at against the last successful sync for that link, not a full resend of every tagged node — the design rationale, stated directly in the README, is that resending everything every night would generate one fresh relay message per unchanged node forever. The delta logic shipped in the same commit as the cron itself (98fceef, 2026-09-13); it isn't a fix discovered after the fact.

3.6 The hooks — why this works when a pure-MCP memory wouldn't

If memory were only a set of tools, it would depend on the agent choosing to call them. Under load, mid-task, that choice might not get made. The hooks remove the choice:

SessionStart     → psycopg query for pin_triggers, scoped to the current project + globals
                    → additionalContext
UserPromptSubmit → (per the README) FTS the prompt against curated memories
                    → additionalContext — script not present in this public repo
SessionEnd       → if the project opted in, detached subprocess extracts memories from the transcript

Three implementation details that are the difference between working and not:

1. No MCP, no model, no embeddings in the SessionStart/SessionEnd hooks. session_start_hook.py opens psycopg directly with connect_timeout=3; it doesn't import the server. A hook is on the critical path of session start, so it has to run in milliseconds. The actual query is WHERE %s = ANY(pin_triggers) AND origin = 'curated' AND deleted_at IS NULL AND (path = <project> OR path LIKE '<project>/%' OR path LIKE '/user/%' OR path LIKE '/feedback/%') — curated-only, scoped to the project derived from the working directory plus the always-global /user and /feedback subtrees (session_start_hook.py:66–75). If no project slug can be derived from the working directory at all, the hook returns with no output — not even the global pins get injected in that case.
2. Fail silent, always. Every failure path in these scripts is a bare early return. No DB reachable? No memories, session proceeds. The module docstring states the rule outright: a hook must never block a session.
3. SessionEnd detaches, and is opt-in per project. Extraction only runs if the current project's node has config.auto_extract = true (set via a config tool) or the environment variable DIARY_AUTO_EXTRACT=1 is set — default is off. If enabled, the hook spawns extract_memories.py with subprocess.Popen(..., start_new_session=True), stdio to DEVNULL, and returns immediately; extraction is described in the script's own docstring as "purely deterministic (no AI/API)". Running after teardown means closing a session is never slow, and the fact that it's opt-in means transcripts aren't harvested by default.

Here is one SessionStart firing at a normal session start (not a compaction), start to finish — the stdin payload, the query, and the additionalContext this hook prints back. The session id, pin content, and row count are illustrative; the payload shape, the query, and the JSON format are real.

harness runs: python3 scripts/session_start_hook.py
stdin:
{"session_id": "a1b2c3", "cwd": "/home/user/projects/webshop", "hook_event_name": "SessionStart", "source": "startup"}

 slug_from_cwd(cwd) -> "webshop"; psycopg.connect(..., connect_timeout=3); SELECT ... WHERE 'start' = ANY(pin_triggers) ...2 rows back. stdout:
{"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": "# Gepinnte Memories (Session-Start) — Projekt 'webshop'\n(Automatisch aus dem diary-mcp Memory-Tree geladen.)\n\n## [project] Deploys only through CI  ⟨/projects/webshop/deploy-rule⟩\nNever push straight to production; every deploy goes through the CI pipeline…\n\n# Globale Memories (User & Feedback)\n\n## [feedback] Keep answers short  ⟨/feedback/short-answers⟩\nPrefer short, direct answers; details only on request…"}}

This only needs one pane, unlike Chapter 1's animations, because nothing here is model text: the harness spawns the process, the hook queries Postgres directly (no MCP, no model — point 1 above), and what comes back is exactly what later gets spliced into context as additionalContext. Notice the query only ever looks at pin_triggers, origin='curated', and the project scope derived from cwd — an unpinned memory, however relevant, never appears here no matter how it ranks in memory_search.

The README.md describes a fourth hook, UserPromptSubmit (diary_prompt_retrieval.py), which is meant to run the current prompt through the same Postgres FTS index memory_search uses, against curated memories only, and inject the top matches — deliberately FTS-only rather than semantic, to avoid a cold-start embedding-model load on every single prompt. That script is referenced by path in the README but is not present in this public repository, so its exact behavior can't be verified from source the way the other two hooks can.

And the compaction branch is the sharp one: when the hook payload's source field is "compact" rather than a fresh start, SessionStart fires again — Claude Code re-runs it after compaction — and the hook selects nodes pinned with the compact trigger instead of start. The design intent (per the module docstring) is that compaction has just lossily summarized the conversation, so these are the facts to re-inject immediately afterward.

Where the pins come from. Nothing in diary-mcp works out on its own which memories are start and which are compact. The column is written by exactly two tools, memory_pin and memory_unpin (memory_service.py:732–780). memory_upsert never touches it, and the only other writer is sync, which copies it between machines. So whether a node comes back after a compaction is a deliberate, per-node decision by whoever pins it. In practice that's the model, asked by you or told to by its instructions. The tool's docstring presents the two flags as cost tiers, not as two kinds of fact:

@mcp.tool()
def memory_pin(path: str, on_start: bool = True, on_compact: bool = False) -> str:
    """Pinnt ein Memory für automatisches Injizieren — sparsam einsetzen, da jeder Pin Kontext kostet!

    on_start:    Wenn True, wird das Memory beim Session-Start automatisch in Claudes
                 Kontext geladen (setzt 'start' in pin_triggers). Gut für dauerhaft
                 wichtige Projekt-Fakten, die Claude immer kennen muss.
    on_compact:  Wenn True, wird das Memory nach einer Kontext-Kompaktierung erneut
                 injiziert (setzt 'compact' in pin_triggers). Gut für Infos, die eine
                 Kompaktierung „überleben" müssen. Noch kostspieliger als on_start —
                 nur für absolut kritische Nodes.

    Gibt die resultierende pin_triggers-Liste zurück.
    """

_{diary-mcp/memory_service.py:732–745}

In English: pin sparingly, because every pin costs context; on_start is for project facts Claude must always know; on_compact is for facts that must survive a compaction, and is "even more expensive than on_start — only for absolutely critical nodes". The docstring doesn't say why it costs more. Presumably because a compact pin is paid again after every compaction, and long sessions compact several times.

A call and its answer (the path is illustrative; the return format is memory_service.py:760–761):

memory_pin(path="/projects/webshop/deploy-rule", on_start=True, on_compact=True)
→ Pin für '/projects/webshop/deploy-rule' gesetzt: [start, compact].

Three details matter when you use it:

• It replaces, it doesn't add. The update is SET pin_triggers = %s (:754). Re-pinning with the defaults, memory_pin(path), turns [start, compact] back into [start] and silently drops the compact pin. on_start=False, on_compact=True gives a compact-only pin, which is not loaded at session start at all.
• memory_unpin(path) empties the list (:764–780). The memory stays and is still found by search; it's just no longer injected automatically.
• Pinned nodes are never proposed for pruning. The admin memory_consolidate_report leaves them out of its stale list: "gepinnte Nodes sind bewusst dauerhaft wichtig" (pinned nodes are deliberately permanently important; graph_admin.py:479–481).

The split is also not an afterthought. Until commit 7437f7e (2026-06-21, "Refinements: unify pins, …") these were two separate booleans, auto_inject and reinject_on_compact, and sync_manager.py:196ff still converts the old columns into the array. A node could always be start-only, compact-only or both. So the start/compact distinction is an explicit design choice, exposed in the API as two independent flags with a stated cost ranking. Whether a particular pin is justified is a judgement about that memory, not something the system infers.

3.7 The embedding-model election (diary_embed_ipc.py)

The problem, restated from Chapter 2: N sessions → N processes → N × ~470MB of identical ONNX weights (the ~470MB figure is stated directly in the module's own docstring, diary_embed_ipc.py:6–8).

The solution has no daemon and no supervisor:

1. Every process that needs an embedding tries to bind() a well-known Unix socket.
2. Whoever wins loads the model and becomes the machine's embedding server for that socket.
3. Everyone else connects as a client and sends text, gets vectors back.
4. If the server process later exits, its socket file is not automatically removed — Unix domain socket files don't get cleaned up just because the owning process died. What actually happens is more specific: the next process that attempts its own election calls try_start(), which tries to bind(), gets OSError because the path already exists, then actively probes it with a real connect() (_is_alive) to tell a live server from a stale file. Only if that probe fails does it unlink the stale file and rebind. Processes that were already running as clients when the server died do not re-run this election on their own; on their next failed request each one calls _downgrade_to_standalone() and loads its own model copy instead (diary_embed.py:92–98, 155–161). So "self-healing" here specifically means new processes reclaim the role — existing clients degrade to standalone rather than seeking out a new server.

Protocol: one request per connection, an 8-byte big-endian length prefix, then a JSON payload, in both directions.

The socket path can be overridden via DIARY_EMBED_SOCK; otherwise it's $XDG_RUNTIME_DIR/diary-mcp-embed.sock (already 0700 by systemd convention) or, if XDG_RUNTIME_DIR isn't set, a per-uid /tmp/diary-mcp-<uid>/diary-mcp-embed.sock, where the directory is created 0700 and an ownership check refuses to proceed if it's owned by a different uid. The socket file itself is bound under a restrictive umask and then explicitly chmoded 0600. A client that finds a socket owned by another uid also refuses to use it. This is commit 3a35567, dated 2026-09-21 — "Harden embed IPC socket against local multi-user hijacking" — because a socket in world-writable /tmp without these checks would let another local user pre-create or squat the path and potentially read memory content as it's sent for embedding.

Leader election by bind() race is a nice pattern: bind() on an address already in use fails atomically at the kernel level, so it works as a mutex — it just isn't automatically released the way an in-memory lock would be, which is exactly why the liveness probe in point 4 above exists.

3.8 Sync, and one instructive bug

memory_sync() reaches the remote database directly at DIARY_REMOTE_URL, or — if DIARY_REMOTE_SSH_HOST is set — through an ephemeral ssh -N -L tunnel on a locally-reserved port, torn down on exit (with a 15-second come-up deadline); the tunnel is opt-in, not the default path. It ensures the remote schema exists, then reconciles both directions by last-write-wins on updated_at, including tombstones and embeddings.

Details that matter:

• Nodes are applied in path-depth order — parents before children (sync_manager.py:265, 296, 309). This is belt-and-braces rather than a hard requirement: the upsert that writes synced rows is keyed on path and doesn't transfer parent_id at all, so there's no foreign-key violation waiting to happen from out-of-order arrival. parent_id is re-derived from each path and backfilled afterward, on both sides (sync_manager.py:344–355). The depth ordering is still a sensible precaution — the backfill logic is simpler to reason about walking outside-in — just not a fix for a possible constraint failure.
• Conflicts are detected before resolution. If both sides changed the same path since the last sync and the content genuinely differs, it's logged and reported. Resolution is still last-write-wins — but silently losing an edit and knowing an edit was lost are different products.
• Timestamps come from the database clock, not the client's, so comparisons stay consistent with updated_at.
• And this comment, verbatim (diary_db.py:302–304): "no updated_at trigger — it would fire on the parent_id backfill below and bump timestamps, corrupting the last-write-wins sync (endless ping-pong / stale overwrites). All app-level UPDATEs set updated_at=now() explicitly instead." The mechanism: an automatic trigger that bumps updated_at on any write would also fire on the parent-id backfill step that runs after every sync — turning "we just re-linked this row's parent" into "this row was just edited," which makes it look newer than the copy it actually came from. On the next sync, that untouched row would then look like the winning side and get pushed back, and the two databases would ping-pong indefinitely, with "last write" no longer meaning "last human edit." A genuinely subtle distributed-systems trap, and one the code sidesteps by never installing the trigger in the first place, favoring explicit updated_at=now() in every application-level UPDATE instead.

3.9 Federation

Pairing with another person's diary through a relay service, diary-relay (a separate repository by the same author):

• PyNaCl Box = X25519 key agreement + XSalsa20-Poly1305 authenticated encryption. One long-lived keypair per diary, generated by diary_link_init.
• Encryption happens before the payload leaves the process; the relay only ever sees ciphertext, so a passive or storage-compromised relay can't read content.
• Only a tag-scoped subset of curated memories is ever shared. Two related but distinct things use tags here: the manual tool diary_link_sync(alias, tag) pushes/pulls whatever tag it's given, for any tag, on demand; sync_tags (empty by default, set via diary_link_set_sync_tags) is a separate, narrower opt-in layer that controls only the automatic paths — the write-time push on every matching upsert, and which (link, tag) pairs the nightly cron iterates over. A tag not listed in sync_tags can still be synced manually; it just won't sync itself.
• Incoming content lands under /links/<alias>/…, tagged from:<alias>, never overwriting the receiver's own tree.
• The trust boundary is narrower than "the relay can't read content" makes it sound: peer public keys are themselves delivered by the relay during pairing (diary_link_redeem_pairing_code/diary_link_check_pairing_code both read peer_public_key straight out of the relay's response, diary_link.py:159–166, 186–193) and are never checked against any out-of-band fingerprint. So a successful Box decryption proves the message came from whoever holds the private key matching the public key the relay handed over at pairing time — which is airtight against a passive relay, but requires trusting the relay to be honest specifically at the pairing step. The relay also necessarily sees connection metadata: display names, which diaries are linked, and message timing/counts, even though it never sees plaintext content.
• _sanitize_incoming_path() is the detail worth calling out on its own: successful decryption authenticates that a message came from the paired peer, but says nothing about whether the content of that message is well-formed. So the decrypted path is validated segment-by-segment (must start with /, no empty/./.. segments) before it's used to build a local path — otherwise a peer could smuggle a path-traversal write into the receiver's tree. Authentication is not input validation; that's exactly the distinction this function exists to enforce.
• Honest tradeoff, documented rather than hidden: the private key sits unencrypted in local Postgres, consistent with the rest of the database already holding sensitive plaintext content on a trust-authenticated localhost connection. The stated threat model is the relay and the network in transit, not a compromised local machine (diary_link.py:6–10).

3.10 What to take away

• diary-mcp's core retrieval idea — two incomparable-scale candidate lists fused by rank position (RRF) rather than by score — is reused elsewhere in this stack (see Ch 6), but in this repo the final ordering is actually driven by a second re-ranking pass over raw similarity, not by the RRF score itself; read the code, not just the docstring, when a mechanism matters to you.
• Persistence here means more than "a database instead of files": UUID keys, tombstones instead of deletes, and idempotent schema convergence are all deliberate answers to specific multi-machine and multi-restart failure modes — and the 1600-column crash shows what happens when an "idempotent" migration step quietly isn't.
• The knowledge graph's most useful feature, inline contradiction warnings, is not automatic detection — it only fires on edges a human (or agent) explicitly created with memory_link.
• Hooks, not tool calls, are what make this memory system reliable: SessionStart and SessionEnd run outside any model's control, fail silent by design, and treat post-compaction re-injection as a distinct, deliberately modeled event.
• The federation and embedding-sharing designs both reason carefully about a specific threat model (a dishonest relay at pairing time; a hostile local user squatting a socket) rather than aiming for unqualified "it's encrypted" or "it's a mutex" security claims — worth noticing as a pattern, since Ch 4–7 raise similar tradeoffs in different subsystems.

4.1 The threat model: everything the agent touches is written down

As Ch 1 showed, a tool result does not go to the model and then vanish. It is appended to the conversation history. It is sent to the model API on every later turn until compaction. It is saved in the session transcript (~/.claude/projects/<project>/<session>.jsonl). It is also visible to every hook that gets PostToolUse input. Tool arguments follow the same path, because the model writes them as tokens. So a password the agent "just uses" in a curl command it typed ends up in at least four places the user does not control well.

vault-mcp's answer is to make the model work with references ("the item named GitHub Token") while the MCP server process fills in the values at the last moment: in a child's environment, a file on disk, an HTTP header, or a browser form field. This is Ch 2's "put the guardrail where the model isn't", applied to data instead of permissions.

What this design covers, and what it does not:

4.2 Process model and tool surface

src/index.ts uses the SDK's low-level Server, not FastMCP-style decorators. Every tool's inputSchema is JSON Schema written by hand, and one big switch handles all the calls:

server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
  try {
    const result = await handleTool(name, args ?? {});
    return { content: [{ type: 'text', text: typeof result === 'string' ? result : JSON.stringify(result, null, 2) }] };
  } catch (err) {
    ...
    return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };

(vault-mcp/src/index.ts:666-678)

Every result is JSON-stringified into a text block. That includes a base64 screenshot (4.12). Nothing checks the arguments against the schema at runtime: args as {...} is only a TypeScript cast. Because zod is never imported, the schema is enforced only by how well the model follows it.

getClient() keeps one BitwardenClient per vault instance in a module-level Map (index.ts:21-31). Claude Code starts one server process per session (Ch 2), so this cache exists once per process. Anything shared between processes has to go through the filesystem, and that is the origin of 4.3 and 4.4. On startup, each process also runs a background sync + listItems + listFolders for every configured vault and fills the search cache (index.ts:1322-1347).

The 37 tools, by group:

A detail that is easy to miss: toItemMeta drops only hidden custom fields (type 1). Text fields (type 0) and boolean fields (type 2) come back with their values (bw-client.ts:662-667). A token stored in a plain text field is therefore sent to the model by vault_list_items or vault_get_item, with no confirmation step.

For example, an item named "GitHub Token", stored as a login with one plain custom field:

vault_get_item request:

{ "itemId": "GitHub Token" }

Response (toItemMeta, bw-client.ts:648-669; the token value is illustrative):

{
  "id": "3f2a1c9e-…",
  "name": "GitHub Token",
  "type": 1,
  "folderId": null,
  "revisionDate": "2026-08-30T14:02:11.000Z",
  "favorite": false,
  "reprompt": 0,
  "login": { "username": null, "uris": [], "hasTotp": false },
  "fields": [{ "name": "token", "type": 0, "value": "ghp_…illustrative…" }]
}

No confirmed argument is required, or even defined, for this tool (index.ts:191-202). What makes the value come back is only the field's type: 0 — the same field stored as type: 1 (hidden) would have been dropped by the same filter.

4.3 Wrapping the bw CLI

Invocation. Every Bitwarden operation goes through bwRaw, which calls execFile('bw', ['--nointeraction', ...args]). Arguments are passed as an array, so no shell is involved (bw-client.ts:294). --nointeraction exists because, with no TTY, bw would otherwise wait forever at a password prompt. Credentials go in through environment variables, not argv: BW_CLIENTID/BW_CLIENTSECRET for login --apikey, BW_PASSWORD with unlock --passwordenv BW_PASSWORD --raw, and BW_SESSION for everything else (bw-client.ts:432-441).

The file does also import exec (bw-client.ts:1, 11). It is used exactly once: execAsync(this.cfg.masterPasswordCmd) (bw-client.ts:319), which runs through a shell on purpose so that pipelines like secret-tool lookup ... work. There is one argv leak left: createItem, updateItemValue and createFolder pass the whole item as base64 JSON in argv (bws(['create', 'item', encoded]), bw-client.ts:603-604, 620-621). Base64 is an encoding, not encryption. The new password is readable in /proc/<pid>/cmdline for as long as that bw call runs.

Isolated appdata dir. Each instance gets BITWARDENCLI_APPDATA_DIR=~/.cache/vault-mcp/bw-data/<instance> (bw-client.ts:148, 153). One bw appdata dir can hold only one server and account, and switching servers needs logout, then config server, then login. Separate directories let instances such as "volantic" and "nak" live side by side without that churn.

Session setup. ensureSessionLocked (bw-client.ts:388-448) works through these steps:

1. If the in-RAM token is younger than SESSION_TTL_MS (18 min, bw-client.ts:94), return.
2. Read mcp-session.json (mode 600, in the same directory, bw-client.ts:149, 358-365). Run bw status with that token. If it says unlocked and the server URL matches, adopt it. This is how the session is reused across processes. A token unlocked by the server or by any vault-launch child is picked up by the others.
3. Otherwise: run bw status. If the server URL differs, run logout (if needed) and then config server <url>. If unauthenticated, run login --apikey. Then unlock, then persist the new token.

The 18-minute TTL only controls how often the in-RAM token is re-checked. It is not a real expiry. When it runs out, the persisted token is re-validated with a cheap bw status. Presumably the token stays valid until something re-unlocks or logs out. The design choice: mcp-session.json next to bw's data.json is, in practice, an unlocked vault at rest for anyone who can read that directory as the user. Bitwarden's own model keeps BW_SESSION only in the environment.

Master password sources, in this priority order (bw-client.ts:316-337): masterPasswordCmd (shell), then plaintext masterPassword from config.json, then masterPasswordPrompt (cached in RAM after the first prompt). src/util/password-prompt.ts tries kdialog first, then zenity when DISPLAY/WAYLAND_DISPLAY is set (password-prompt.ts:226-229). Its header comment says zenity comes first, which is wrong. The fallback is a one-shot HTTP server on 127.0.0.1:<random port>/<40-hex token>, opened via xdg-open and also printed to stderr. Each method has a 5-minute timeout. The dialogs are started with exec and the vault name is interpolated inside double quotes (password-prompt.ts:25-26, 37-38). A model-chosen instance name containing $(...) would therefore run in a shell when the prompt fires. The name comes from a model-supplied vault_add_instance argument.

4.4 The cross-process lock

Why it exists. The comment block at bw-client.ts:96-113 and the two 2026-09-12 commits describe the failure. Every Claude Code restart starts vault-mcp plus one vault-launch child per wrapped MCP server (cis, obsidian, spoticontrol, github, gemini, ...), all at once, all against the same instance. bw's data.json has no locking. Two processes syncing or unlocking at the same time corrupted it, and existing items then came back as bw get item → "Not found".

The first fix (0a3f3d6) locked each individual bw call, and that was not enough. Session setup is a sequence, and each step invalidates state the other steps rely on. With the lock released between steps, process A sees unauthenticated, process B logs in underneath it, and A then fails with "Logout required before server config update". Or B's re-unlock invalidates A's token or wipes the freshly synced cache. The latest commit (9bba97e) moves the lock one level up: every public operation takes it exactly once and runs session setup and the command inside it.

private async bws(args: string[]): Promise<string> {
  return this.withLock(async () => {
    await this.ensureSessionLocked();
    return this.bwRaw(args, { BW_SESSION: this.sessionToken! });
  });
}

(vault-mcp/src/vault/bw-client.ts:455-460)

The *Locked/bwRaw helpers are the building blocks that do not lock. listItems runs sync + list under one lock (bw-client.ts:475-479). getRawItem retries once after dropping the session, re-unlocking and syncing, all inside the same lock (bw-client.ts:499-514). Matching "not found" is part of that retry (bw-client.ts:644-646), so a lookup for an item that really does not exist costs a full re-unlock + sync before it fails. A "Item:field" ref that misses pays that cost twice, because of the colon fallback in resolveValue.

Mechanics.

• Two layers. Inside a process, calls wait on a promise chain (lockChain, bw-client.ts:273-285), so concurrent MCP requests do not all spin on the file. Across processes there is a directory lock at <dataDir>/.bw-lock.
• Atomicity. mkdirSync(lockPath) either creates the directory or throws EEXIST, and the OS guarantees it is all-or-nothing. That gives a lockfile with no extra dependency.
• FIFO queue. Each waiter first writes a ticket file <dataDir>/.bw-queue/<14-digit zero-padded ms>-<pid>-<8 hex> (bw-client.ts:179). Sorting names alphabetically gives arrival order. Only the holder of the oldest live ticket attempts the mkdir (bw-client.ts:245-266). Without the queue, each of a dozen waiters raced on every 100 ms poll, and one could lose every race until it timed out.
• Staleness. Waiters touch their ticket's mtime on each poll. Tickets older than 30 s are pruned as abandoned. A lock directory older than LOCK_STALE_MS = 30 s is removed and taken over (bw-client.ts:225-227).
• Heartbeat. While the lock is held, a 10 s interval touches its mtime (bw-client.ts:208-214). A slow but live holder, for example one waiting at the GUI prompt, is therefore never mistaken for a crashed one.
• Ticket drop ordering. The ticket is deleted only after the mkdir succeeds, so no later arrival can slip in between.
• Budget. LOCK_MAX_WAIT_MS = 180 s, sized for a dozen launchers queued back to back.

Trap: resolveMasterPassword() runs inside the lock. On a vault configured with masterPasswordPrompt, the prompt chain can take up to 3 × 5 min. The heartbeat keeps the lock alive the whole time, so every other process queued on that instance hits its 180 s timeout. The commit message reports "11 failures across 3 rounds before, 32/32 successful after" with 8 concurrent processes. That is the author's measurement; this guide did not re-run it.

4.5 The injection proxy

src/tools/inject.ts is shared by the remote vault (resolver = client.resolveValue), the project vault (resolver = pv.resolveProjectValue) and vault-launch.

Ref syntax. A ref is "Item" (the primary value: login password, else note body, else the first hidden field or a field named value) or "Item:field", where field ∈ {username, password, notes, totp} or a custom field name (case-insensitive first, then exact). If the lookup fails with "Not found", the whole string is retried as an item name, which handles item names that contain a colon (bw-client.ts:556-575).

Placeholders. Maps go placeholder → ref. applyRef tries three spellings in order and stops at the first that appears:

const candidates = [`{{${placeholder}}}`, '${' + placeholder + '}', placeholder];
for (const token of candidates) {
  if (template.includes(token)) {
    return { out: template.replaceAll(token, value), replaced: true };
  }
}
return { out: template, replaced: false };

(vault-mcp/src/tools/inject.ts:21-27)

The delimited forms come first because, when the key was TOKEN and the template said {{TOKEN}}, a bare replace left the braces around the secret (the "leftover braces" regression test in inject.test.ts). The bare form is kept for keys that already include the braces ({"{{TOKEN}}": ...}). If a placeholder appears nowhere, the call fails with Placeholder for secret ref "X" not found in template. Reference it as {{X}} in your request. (inject.ts:36-38). For HTTP it is enough for the placeholder to appear in one header value or the body (inject.ts:53-74). The initial commit fixed exactly this: a Content-Type header without the placeholder used to reject the request.

Two traps the tests do not cover:

• replaceAll with a string replacement interprets $ patterns. Per ECMAScript semantics, a secret containing $$, $&, $` or $' is changed before it is injected. For example, pa$$word becomes pa$word. Passing a function (() => value) would avoid this. (Not run here; there is no Node on this host.)
• The bare fallback replaces substrings. Key TOKEN also matches inside MY_TOKEN_FILE. It can also match inside a secret that an earlier ref already substituted.

prepareInjection (inject.ts:118-158) merges envMappings, argRefs and stdinSecret into one ref set. It resolves each distinct item once, builds { env, args, stdinValue }, and spawns nothing. That split lets both the capturing runner and the stdio-inheriting launcher use the same code.

What each proxy tool returns to the model:

Plainly: no output is redacted. If the child prints the secret, or the server echoes a header back (as httpbin.org/anything does), the value goes straight into context. ["sh","-c","echo $T"] with envMappings: {T: "GitHub Token"} reveals the token with no confirmation flag at all. There is also no destination allowlist, so http_request will send a secret to any URL the model picks. Derived credentials come back too: a login endpoint's session token in the body, or Set-Cookie in the response headers. Also, the { mode: 0o600 } in write_file applies only when the file is created. Overwriting an existing file keeps its old permissions. Finally, vault_run_command with no refs is simply an unrestricted command runner. If a harness denies Bash but allows mcp__vault-mcp__*, the model still has a shell.

Here is that same mechanism end to end — a placeholder resolved through argRefs this time, not envMappings — with the child's own verbose flag carrying the secret back out through stderr, which nothing on the way inspects.

system: [system prompt, CLAUDE.md files, tool schemas]

user: Check the Coolify API health endpoint, and show me the raw request so I can debug a 401 we saw earlier.

assistant: I'll call the health endpoint with the token injected via argRefs, with curl's verbose flag so the raw request is visible.
{"type": "tool_use", "id": "toolu_02C…", "name": "vault_run_command", "input": {"vault": "homelab", "command": ["curl", "-s", "-v", "-H", "Authorization: Bearer {{TOKEN}}", "https://api.coolify.example/v1/health"], "argRefs": {"{{TOKEN}}": "Coolify API Token"}}}

 waiting for the tool result

vault_run_command received
{"vault": "homelab", "command": ["curl", "-s", "-v", "-H", "Authorization: Bearer {{TOKEN}}", "https://api.coolify.example/v1/health"], "argRefs": {"{{TOKEN}}": "Coolify API Token"}}
 resolving argRef via client.resolveValue() (under the bw lock, 4.4)resolved "Coolify API Token" (value kept only in memory)
substituted into argv: ["curl", "-s", "-v", "-H", "Authorization: Bearer sk_live_51H9…", "https://api.coolify.example/v1/health"]  (inject.ts:20-28, applyRef)
spawn("curl", args, { stdio: ["ignore", "pipe", "pipe"] })  (inject.ts:180-184)
 child process runningchild exited 0  (exitCode: code ?? 0, inject.ts:195)
stdout: "ok"
stderr, returned as-is — nothing here inspects or redacts it (inject.ts:191-194): "> Authorization: Bearer sk_live_51H9…"

user: {"type": "tool_result", "tool_use_id": "toolu_02C…", "content": "{\"stdout\":\"ok\",\"stderr\":\"> Authorization: Bearer sk_live_51H9…\",\"exitCode\":0}"}

assistant: The health check passed. One thing to flag: I asked for -v, and curl prints the request headers it sent — including the Authorization header with the token — to stderr. vault_run_command hands stdout and stderr back to me exactly as the child produced them, with no redaction, so that token is now in this conversation's context and the session transcript.

4.6 The reveal path: two flags the model sets itself

if (!confirmed) return 'Set confirmed=true as first confirmation.';
if (!exposedToAI) {
  return 'Set exposedToAI=true as second confirmation, explicitly acknowledging that the AI will see the secret value in plaintext.';
}
const vaultName = resolveVault(vault);
const sensitive = await getClient(vaultName).getItemSensitive(itemId);

(vault-mcp/src/index.ts:916-922)

The result contains password, notes, all hidden fields and the TOTP seed.

Three calls to the same tool, in the order the checks run (index.ts:912-924):

{ "itemId": "Coolify API Token" }

→

Set confirmed=true as first confirmation.

{ "itemId": "Coolify API Token", "confirmed": true }

→

Set exposedToAI=true as second confirmation, explicitly acknowledging that the AI will see the secret value in plaintext.

{ "itemId": "Coolify API Token", "confirmed": true, "exposedToAI": true }

→ (getItemSensitive, bw-client.ts:521-536; values illustrative)

{
  "id": "9c7e2b41-…",
  "name": "Coolify API Token",
  "type": 2,
  "password": null,
  "notes": "sk_live_51H9…illustrative…",
  "hiddenFields": [],
  "totp": null
}

The first two responses are plain strings the model reads like any other tool result — nothing stops it from just setting both flags on the next call. The third is the whole item's sensitive payload in one shot, once it does.

vault_favorites_get works the same way. Both flags are tool arguments, and the model writes them. The only thing this can do is shape the model's behaviour. The schema marks them required and the tool description says "Use only when the user explicitly requests...", so a well-aligned model has to make an explicit choice, and a first call without the flags returns a string that tells the model what to add. That makes it an intent signal plus a speed bump against accidental reveals. It is no defence against a model that has decided, or been prompt-injected, to reveal: it just sets both flags to true in one call. In Ch 1's terms, this is CLAUDE.md-style persuasion placed inside a schema.

What would make it enforcement is a harness-side check the model cannot write:

• a permissions.ask (or deny) rule for mcp__vault-mcp__vault_reveal_password and mcp__vault-mcp__vault_favorites_get (the server key from .claude.json sets the prefix), or
• a PreToolUse hook matching those names that returns exit code 2 or a permissionDecision: "ask".

The same treatment arguably belongs on vault_run_command and vault_http_request, for the reasons in 4.5.

4.7 Project vaults

A project vault is a small local store for the few secrets one repo needs. It is deliberately not a mirror of Bitwarden: the tool descriptions say "add items ONE AT A TIME". Files:

• <repo>/.vault-project: marker JSON {id (UUID), name, createdAt, storage: 'external'|'committed', totpEnabled}. It is not authenticated.
• The ciphertext: ~/.config/vault-mcp/projects/<id>.vault (external), or <repo>/.vault-project.enc (committed).
• The format: AES-256-GCM, [IV 12B][ciphertext][tag 16B], over the JSON {version:1, items:[{id,name,value,createdAt,updatedAt}]} (project-vault.ts:108-115).

Key derivation always uses hkdfSync('sha256', ikm, salt = projectId as UTF-8, info, 32):

The committed variant (commit: true, or totp_enable followed by enable_commit_storage) mints a 512-bit key with randomBytes(64) that is independent of the machine-wide masterKey. It stores that key in projects/<id>.key and the seed (20 random bytes, base32) in projects/<id>.totp, both mode 600. It also writes a merged backup to ~/.claude/vault-mcp-backups/<id>.json. If a primary file is missing, requireVaultKey/requireTotpSeed fall back to the backup and restore the primary (project-vault.ts:173-225). When moving an external vault into the repo, the data is re-encrypted under the v3 key before anything lands there, and the old external file is then deleted.

"TOTP" here is effectively a second random secret. totp.ts is a correct RFC 4226/6238 implementation, tested against the RFC vectors, but verifyTotpToken is called only from tests. No 6-digit code is ever checked. As totp.ts:4-6 explains, the seed is what goes into the key, since a code that rotates every 30 s cannot protect a ciphertext that has to stay decryptable. The otpauth:// URI is only there so a human can cross-check in an authenticator app.

What each mode protects against:

• External. A repo leak (only a UUID is committed). It does not protect against anyone with config.json.
• External + TOTP. Hardly more: the seed lives in the same directory as the master key.
• Committed. A public ciphertext, together with a leaked masterKey (the tests confirm a different master key still decrypts, and that neither secret alone does).

What none of them protect against: both committed secrets are returned in the vault_init_project / enable_commit_storage tool result ("shown ONCE", index.ts:1180-1188). That is, they go into the model context and the session transcript under ~/.claude/projects/. The backup copy also sits under ~/.claude/. "Never in the repo" is true; "never seen by the model" is not.

The same exposure exists for plain external vaults the moment TOTP is turned on: vault_project_totp_enable's handler calls pv.enableTotp and returns totpSeedBase32 and totpUri directly in the tool result, with the same "Shown here ONCE" language (index.ts:1199-1211). There is no committed storage involved yet — this is the seed for the "external + TOTP" row above — so the 4.7 mode table's "hardly more" caveat undersells it: the seed is not just filed next to the master key on disk, it is also, once, in the model's context and permanently in the session transcript, exactly like the committed-vault case.

4.8 Favorites vault

This is a local snapshot store, including passwords, at ~/.config/vault-mcp/favorites.vault. The path is hard-coded and does not respect VAULT_MCP_CONFIG_DIR. Layout: [salt 32B | IV 12B | ciphertext | tag 16B]. The key is scryptSync(passphrase, salt, 32, { N: 65536, r: 8, p: 1 }) (favorites-vault.ts:19-23, 56-58). The salt is created once and reused on every save; each save gets a fresh IV. If the file does not exist, load() returns an empty vault with a new salt. The first add therefore sets the passphrase silently, with no confirmation, and a typo becomes the passphrase.

The passphrase really is a tool argument, and it is required on all five tools (index.ts:418, 433, 447, 461, 474). The phrase "Never stored on disk" in its description applies to vault-mcp's own files. The passphrase goes into the model context, is sent to the API on every later turn, and is written to the transcript on disk. Anyone with the transcript and the favorites.vault file can decrypt it.

A likely latent failure: according to Node's documentation, scrypt throws when 128·N·r exceeds maxmem, which defaults to 32 MiB. Here that product is 64 MiB and no maxmem is passed, so every favorites operation should fail with a memory-limit error. There are no favorites tests, and this could not be executed here, so it is unverified.

4.9 Search cache

~/.cache/vault-mcp/search.db (SQLite, WAL) contains items(id, vault, name, type, folder_id, folder_name, favorite, uris JSON, username, field_names JSON, revision_date, synced_at, PK(id, vault)) and sync_log(vault PK, synced_at, item_count) (search-cache.ts:56-78). A sync upserts every item and deletes cached ids that are gone, in one transaction.

Stored: names, usernames, URIs, folder names, and field names. Not stored: passwords, notes, and any field values. Note that field_names comes from toItemMeta, which has already dropped hidden fields. The names of hidden fields are therefore not searchable, even though the tool description promises matching on "each custom field name".

vault_search builds a Fuse.js index over the cached items plus the domains extracted from their URIs. Key weights: name 3.0, fieldNames 1.5, domains 1.5, username 1.3, uris 0.8, folderName 0.8. Options: threshold 0.45, ignoreLocation, minMatchCharLength 2 (search-cache.ts:233-248). The README's order ("Name > Username > URI > Folder > Feldnamen") is out of date. The search takes max(3·limit, 30) candidates and keeps max(limit, near-ties within 0.05 of the best score), capped at 30. matchedOn lists the attribute that matched and its value. The default limit is 20 in code; the tool description says 10.

A query against the cache alone, no Vaultwarden round-trip:

{ "query": "coolify" }

Response (index.ts:881-893, shape from cache.fuzzySearch, search-cache.ts:221-269; ids and dates illustrative):

[
  {
    "id": "9c7e2b41-…", "vault": "homelab", "name": "Coolify API Token",
    "type": 1, "folder": "Infra", "username": null, "uris": [],
    "fieldNames": ["scope"], "favorite": false,
    "score": "100%", "matchedOn": ["name: Coolify API Token"]
  },
  {
    "id": "1a44f0a2-…", "vault": "homelab", "name": "homelab Grafana",
    "type": 1, "folder": "Infra", "username": "admin",
    "uris": ["https://grafana.coolify.example"], "fieldNames": [],
    "favorite": false, "score": "81%", "matchedOn": ["domain: grafana.coolify.example"]
  }
]

Neither hit carries a password, a note or a hidden-field value — only what this section says the cache stores. The second result matched through its URI's domain, not its name, which is exactly what matchedOn is for.

4.10 Audit log

auditLog(action, vault, item?, details?) appends one JSON line to ~/.cache/vault-mcp/audit.log (audit.ts:15-30). Logged: timestamp, action, vault, item name or ID, and metadata such as the first element of the command, env var names, argRef placeholders, the stdin item name, item refs, the URL and method for HTTP, search queries, and output paths. Values are never logged. For the proxy tools the entry is written before execution and records no outcome, exit code or HTTP status. list_folders, cache_status, list_instances and project_info are not logged. vault-launch does not log at all, because it never imports auditLog. The log is an access-intent record, not a tamper-proof trail.

4.11 Secret scanner

vault_scan_secrets(path) builds its file list from git ls-files, git diff --cached --name-only --diff-filter=ACM and git ls-files --others --exclude-standard. Only when git returns nothing does it walk the directory, skipping node_modules, .git, dist, build and similar (secret-scan.ts:106-129). It reads working-tree contents, so neither the staged blob nor history is scanned. It skips binary and media extensions, lockfiles, and files over 2 MiB.

Rules:

• high-confidence regexes for AWS key IDs, GitHub ghp_/gho_/…/github_pat_, Slack xox?-, Google AIza…, Stripe sk_/rk_live|test, OpenAI-style sk-, and PEM BEGIN … PRIVATE KEY headers;
• a medium-confidence generic (pass|secret|token|api_key|auth|credential)… [:=] "literal" rule, filtered by isLikelyRealSecret. The filter requires at least 12 chars, not a {{…}}/${…} placeholder, not process.env., no words like changeme/example/dummy, and both a letter and a digit or symbol.

redact() returns first4...last4 (N chars), or all asterisks when the value is 8 chars or shorter. For a 12-character secret that discloses 8 of the 12 characters. A test runs the scanner against the repo's own src/ and expects zero findings outside the fixtures.

4.12 Browser fill

browserFillForm resolves every field ref before starting the browser. It then runs chromium.launch({ headless }) (default headless), creates a new context with optional extraHTTPHeaders, and navigates with page.goto(url, { waitUntil: 'domcontentloaded' }). For each selector → ref, in insertion order: locator(selector).first(), wait until visible, then selectOption for <select>, check/uncheck for checkbox or radio ("true"/"1"), and fill for everything else. After that it can click submitSelector, wait for waitForSelector, and return {success, finalUrl, pageTitle, extractedContent?, screenshot?} (browser.ts:47-110).

Nothing ties url to the item's stored URIs, so credentials can be filled into any page. extractSelector text is returned verbatim. A screenshot is taken whenever screenshot=true and on every error, and it is returned as base64 inside the JSON text, not as an MCP image block. Likely consequence: one screenshot costs tens of thousands of context tokens, and an error screenshot can show a visible username or a password field that is not masked.

4.13 vault-launch: injection at the environment boundary

src/launch.ts borrows the shape of op run -- and aws-vault exec --. The .claude.json entry points at node dist/launch.js --vault nak --env CIS_USER=nordakademie.de:username --env CIS_PASS=nordakademie.de:password -- /abs/path/cis-api/cis mcp (launch.ts:17-29). --vault selects the instance; --env VAR=Ref and --arg PH=Ref can repeat. Only the first = splits the pair, and everything after -- is the child command, taken as-is.

const { env, args } = await prepareInjection(
  (ref) => client.resolveValue(ref),
  parsed.command,
  { envMappings: parsed.envMappings, argRefs: parsed.argRefs },
);
const child = spawn(parsed.command[0], args, {
  stdio: 'inherit',
  env: { ...process.env, ...env },
});

(vault-mcp/src/launch.ts:112-121)

Because stdio is inherited, the child's stdin and stdout are Claude Code's JSON-RPC pipe. The launcher never touches those bytes, and it writes only to stderr (the header comment makes this rule explicit, per Ch 2). This design has an elegant consequence. Claude Code's initialize request may arrive while the launcher is still unlocking the vault. The launcher never reads stdin, so the request waits in the kernel pipe buffer until the child reads it. There is no stdinSecret here, because stdin belongs to the protocol. SIGINT, SIGTERM and SIGHUP are forwarded, and the exit code or signal is mirrored.

For cis-api, cmd/mcp.go:46-47 simply calls os.Getenv("CIS_USER") and os.Getenv("CIS_PASS"). The wrapped server needs no code changes, and the credentials never pass through the model. They do sit in the child's /proc/<pid>/environ, which the same user can read.

The two --env mappings from that entry resolve, at spawn time, into a concrete environment only the child ever sees:

Input (the mappings prepareInjection receives, launch.ts:112-116):

{ "envMappings": { "CIS_USER": "nordakademie.de:username", "CIS_PASS": "nordakademie.de:password" } }

Output (the child's environment after spawn(parsed.command[0], args, { stdio: 'inherit', env: { ...process.env, ...env } }), launch.ts:118-121; values illustrative):

CIS_USER=jdoe
CIS_PASS=Tr0ub4dor&3…illustrative…
PATH=/usr/bin:/bin:/usr/local/bin
HOME=/home/user
…

Nothing here touches stdout or stdin — the resolved values only ever reach cis mcp's own os.Getenv calls, in a different process's environment. Neither the ref nor the resolved value passes through the model's context at any point.

Each launcher is another process competing for the bw lock (4.4).

4.14 Tests

vitest, 6 files:

Untested: favorites vault, search cache, audit log, browser, password prompt, and all of index.ts, including the confirmation checks.

4.15 What to take away

• References in the model, values in the server. Mapping from a name to a value at the last hop (env, file, header, form field) is the single mechanism that keeps secrets out of context. Every tool that returns a value, or takes one as an argument, bypasses it.
• Keeping a value out of the arguments does not keep it out of the output. Unless the proxy redacts output and restricts destinations, a model that wants the secret can still get it through the tool's result. This design protects against accidents, not against an adversarial model.
• A confirmation flag the model sets is persuasion, not enforcement. Real gates belong in the harness (permission rules, PreToolUse hooks), keyed on tool names the model cannot rename.
• Serialize the whole critical section, not the individual calls. If a stateful CLI's setup is a multi-step sequence, locking each step separately still lets processes interleave. mkdir as a lock plus a ticket queue, heartbeat and stale-steal gives a portable, fair cross-process mutex.
• Look where key material ends up in practice. "Shown once" in a tool result means "stored in the transcript permanently".

These three repos are really one design split three ways. network-mcp and sysprobe-mcp are generic Linux servers. cachyos-mcp adds Arch/pacman tools and bundles the other two into a single process. All three are Python on FastMCP (see Ch 2), and every tool shells out to a system CLI or calls psutil.

Each repo has one initial commit, and all three initial commits carry the same timestamp (12:03:21). The only later change is cachyos's askpass commit, 22 minutes afterwards. This suggests the three were developed together and committed as a set. The network-mcp README is an empty file (0 bytes).

5.1 The composition pattern: register(mcp)

Every package exposes one public function. It takes any object that has a .tool() decorator and attaches that package's tools to it:

def register(mcp) -> None:
    """Register all sysprobe tools (diag + services + desktop) on a server."""
    diag.register(mcp)
    services.register(mcp)
    desktop.register(mcp)

(sysprobe-mcp/src/sysprobe/init.py:16)

Inside each module's register, the tools are nested closures decorated with @mcp.tool(). FastMCP's decorator returns the original function unchanged, so tools can call each other as plain Python. For example, get_network_traffic_per_process calls get_interface_throughput(1.0) as a fallback (network-mcp/src/netmcp/tools.py:253), and get_package_dependencies calls get_package_info (cachyos-mcp/src/cachyosmcp/arch.py:306). The interface is duck-typed. The tests exploit this by passing a fake Cap class whose tool() just records functions into a dict (sysprobe-mcp/tests/test_sysprobe.py:71).

Each standalone server.py has three lines of real logic: FastMCP("<name>", instructions=INSTRUCTIONS), register(mcp), and .run() (stdio by default). The aggregator does the same, then embeds the other two packages:

def register(mcp) -> None:
    arch.register(mcp)
    # Embed the generic servers. They are path-dependencies, so normally
    # present; guard the import so cachyos still works if used in isolation.
    try:
        import netmcp
        netmcp.register(mcp)
    except Exception:  # noqa: BLE001
        pass
    try:
        import sysprobe
        sysprobe.register(mcp)

(cachyos-mcp/src/cachyosmcp/init.py:15)

The dependency wiring lives in pyproject.toml through uv sources:

[tool.uv.sources]
network-mcp = { path = "../network-mcp", editable = true }
sysprobe-mcp = { path = "../sysprobe-mcp", editable = true }

(cachyos-mcp/pyproject.toml)

uv.lock records them as source = { editable = "../network-mcp" }. Two consequences follow: - The three repos must be checked out as siblings, or uv run cachyos-mcp cannot resolve its dependencies. - Because the installs are editable, a change to network-mcp's source takes effect the next time cachyos starts, with no reinstall.

Four traps in this pattern:

1. The guard does not guard. cachyosmcp/__init__.py does from . import arch at the top, and arch.py:21 does from netmcp.common import clamp, have, require_actions, run unconditionally. If netmcp were missing, the package would fail to import before the try ever ran. The comment's "still works if used in isolation" is false for netmcp. For sysprobe it is true.
2. The guard swallows real bugs. except Exception: pass also hides a NameError or SyntaxError inside sysprobe, and the server then starts quietly with 59 fewer tools. The only safety net is the test assert len(names) >= 100 (cachyos-mcp/tests/test_cachyos.py:59).
3. Two copies of the plumbing. Inside the aggregator, sysprobe tools use sysprobe.common.run while netmcp and arch tools use netmcp.common.run (see 5.3). Both read the same env var names, so one flag still governs everything.
4. Instructions are lost. Only cachyosmcp.server.INSTRUCTIONS is sent. The aggregator imports the packages, not their server.py. The cachyos text says "See those servers' instructions for the gating of their mutating tools" (cachyos-mcp/src/cachyosmcp/server.py:25), but in aggregated mode the model never receives those instructions. That includes sysprobe's "never read whole files" hint.

No tool name is registered twice across the three packages (checked: 111 names, no duplicates), so the SDK's duplicate-name handling never comes into play.

5.2 From a Python function to what the model sees

Ch 2 covered how FastMCP builds a tool's schema. Concretely, for

@mcp.tool()
def read_config_snippet(filepath: str, start_line: int = 1,
                        end_line: int = 0, grep_pattern: str = "",
                        context: int = 3, max_lines: int = 200) -> dict[str, Any]:
    """Read a slice of a text/config file — never the whole thing blindly.
    ..."""

(sysprobe-mcp/src/sysprobe/diag.py:84)

Based on the mcp SDK's documented behavior (Ch 2 covers the same tool-schema-assembly mechanism at the protocol level, but this paragraph's specifics were not re-verified against the SDK's source for this chapter — the mcp package is not installed anywhere on this host, so this is inference from known FastMCP semantics, not a source read), FastMCP does four things: - The tool name is fn.__name__. - The description is the whole docstring. Presumably the SDK does not parse Args: blocks into per-parameter descriptions, so they would reach the model verbatim as part of the description text — consistent with what the docstrings in this codebase actually contain (e.g. sysprobe-mcp/src/sysprobe/services.py:29, network-mcp/src/netmcp/tools.py:73, both plain Args: blocks with no separate per-parameter schema fields to receive them). - The inputSchema likely comes from a pydantic model built from the signature. Parameters without a default (filepath) would become required; parameters with a default would get "default": ...; annotations would map to JSON types. - The arguments in each tools/call are presumably validated against that model before the function runs.

Some consequences are visible in this code: - [ACTION] markers are prompt text. Mutating tools start their docstring with [ACTION] or [POWER]. That is text engineering: it tells the model that a tool mutates something. It enforces nothing. - The int() casts are redundant. clamp(int(max_lines), 1, 1000) and similar casts appear everywhere. They defend against loose argument types, although pydantic validation already coerces types. - Size is paid up front. All 111 schemas plus descriptions go into context in every turn (Ch 2), whether or not the tool is gated. A gated tool that returns {"error": "action disabled"} still costs its schema tokens. This presumably matters less in harness builds that defer MCP tool schemas behind a search tool, as the session this guide was written in does for large connector sets.

The instructions string. FastMCP(name, instructions=...) puts the text into the instructions field of the initialize result (Ch 2). Claude Code injects server instructions into the system context under a "MCP Server Instructions" heading. That is directly observable in the harness that produced this guide. So the text is persuasion that arrives once per session, not per call. network-mcp uses it to prescribe an escalation order: "get_network_status -> get_network_interfaces -> list_listening_ports / find_port_owner, then escalate …" (network-mcp/src/netmcp/server.py:13). cachyos uses it to push search_all_repositories first "to avoid hallucinated package names".

5.3 The shared core: common.py

diff network-mcp/src/netmcp/common.py sysprobe-mcp/src/sysprobe/common.py shows the two files are identical code up to line 160. The only differences in that range are comments: sysprobe's copy explains why the environment is scrubbed (powerprofilesctl needs the system's gi module) and notes that desktop variables are deliberately kept. sysprobe then appends 41 lines: POWER_ENV, power_allowed(), require_power() and popen_detached(). The docstring calls the module "intentionally dependency-light … a copy-anywhere unit", so the duplication is deliberate: each generic server stays self-contained. arch.py does not have its own copy; it imports netmcp.common.

strip_ansi removes two kinds of escape sequences, using _OSC_RE (\x1b]… ended by BEL or ST) and _ANSI_RE (CSI sequences). It also normalises \r\n to \n and drops stray \r, which kills progress-bar redraws. Every run() result passes through it.

run() never raises. It returns a CmdResult (a dict subclass with an .ok property that means rc == 0), with these conventions:

These mirror shell conventions: 127 "not found", 126 "not executable", 124 as used by coreutils timeout. The docstring gives the reason: "the model receives clean structured feedback rather than a stack trace". Note what a timeout does: stdout is thrown away, so a 30-minute paru -Syu that times out returns no log at all.

Environment scrubbing (network-mcp/src/netmcp/common.py:69):

run_env = {**os.environ, **(env or {})}
venv = run_env.get("VIRTUAL_ENV")
for var in ("PYTHONHOME", "PYTHONPATH", "PYTHONEXECUTABLE",
            "PYTHONSTARTUP", "VIRTUAL_ENV", "UV"):
    run_env.pop(var, None)
if run_env.get("PATH"):
    parts = run_env["PATH"].split(os.pathsep)
    parts = [p for p in parts
             if "/.venv/" not in (p + "/")
             and not (venv and p.startswith(venv))]
    run_env["PATH"] = os.pathsep.join(parts)
run_env.setdefault("LC_ALL", "C")
run_env.setdefault("NO_COLOR", "1")

Why this is needed: the server runs under uv run, which puts .venv/bin first on PATH and sets VIRTUAL_ENV. A system script with #!/usr/bin/env python3 (the comments name powerprofilesctl) would then run under the venv interpreter, which lacks PyGObject, and crash. The test test_run_strips_venv_from_path pins this behaviour. Three subtleties:

• LC_ALL is only a default. setdefault means that if the user's environment already sets LC_ALL (for example de_DE.UTF-8), it is not overridden, despite the comment's "Force". Parsers that match English output would then silently find nothing. Examples: ping_host's packets transmitted regex and get_battery_health's upower keys.
• The PATH filter is broad. It drops every PATH entry containing /.venv/, including a user tool that happens to live in some other project's venv.
• popen_detached does not scrub. It builds {**os.environ, **env} with no scrubbing (sysprobe-mcp/src/sysprobe/common.py:190). So apps started by launch_app inherit VIRTUAL_ENV and the venv PATH, which is exactly the problem run() avoids. What popen_detached does get right is stdin/stdout/stderr=DEVNULL plus start_new_session=True. A GUI app that inherited the server's stdout would write into the JSON-RPC stream (Ch 2). setsid lets the app outlive the server.

Text helpers. tail(text, n) returns the last n lines, or the full text when n is 0. grep(text, pattern, ignore_case=True, max_matches=200, context=0) returns {"line", "text", "context"?} entries plus a {"note": "truncated at N matches"} sentinel. A bad regex comes back as [{"error": "bad regex: …"}] instead of an exception. clamp(v, lo, hi) is used on nearly every numeric argument.

Result conventions. Tools return plain dicts, which the SDK serialises to JSON. Failures are also normal dicts, {"error": …, "hint": …}, so at the protocol level they are successful tool results with an error key. The model reads them the same way, but a client that keys on MCP's isError would see success. Genuine exceptions still escape in a few places, for example an uncaught re.error in get_pacman_log (arch.py:479). Those surface through the SDK's error path.

Clamps count items, not bytes. The "hard size limits" are line and entry counts. read_config_snippet caps a response at 1000 lines but never truncates a single line, so a 5 MB minified JSON file on one line comes back whole. In grep mode, max_matches is capped but each match can carry up to 21 context lines. list_listening_ports, get_routes, get_block_devices and the ufw branch of get_firewall_rules have no cap at all. Presumably the harness's own MCP output limit is the real backstop.

Example: a clamp in action. A grep_file call with a low max_matches shows the clamp and grep()'s truncation sentinel in the same response (the log lines below are invented for illustration, not a real capture):

// request
{"name": "grep_file",
 "arguments": {"path": "/var/log/pacman.log", "pattern": "error", "max_matches": 3, "context": 0}}

// response
{
  "file": "/var/log/pacman.log",
  "matches": [
    {"line": 1822, "text": "[2026-09-20T03:12Z] [ALPM] error: could not commit transaction"},
    {"line": 1904, "text": "[2026-09-21T11:47Z] [ALPM] error: transaction failed"},
    {"line": 2031, "text": "[2026-09-22T02:00Z] [ALPM] error: could not resolve dependencies"},
    {"note": "truncated at 3 matches"}
  ]
}

(the call is sysprobe-mcp/src/sysprobe/diag.py:113–127; the clamp and the {"note": …} sentinel are network-mcp/src/netmcp/common.py:116–136, grep().) The clamp counts matches, not bytes: three one-word lines would have cost the same "3" as these three long ones, and the note entry is the only signal that more matches exist — it does not say how many.

5.4 Walkthrough (sysprobe): read_config_snippet

Take the call {"filepath": "~/.config/kwinrc", "grep_pattern": "Tiling", "context": 2}:

1. The harness checks Claude Code permissions for mcp__<server>__read_config_snippet (Ch 1), then sends tools/call over stdio. FastMCP validates the arguments against the generated model.
2. _expand runs: Path(os.path.expanduser(os.path.expandvars(path))).resolve() (diag.py:25). ~ and $VARS are expanded, symlinks are resolved, and relative paths are anchored at the server's working directory.
3. fp.is_file() is checked, or the tool returns {"error": "not a file: …"}.
4. fp.read_text(errors="replace") reads the whole file into memory. The "never the whole thing" promise in the docstring applies to what is returned, not what is read.
5. Because a pattern was given, grep(text, "Tiling", context=2, max_matches=max_lines) runs and the tool returns {"file", "grep", "matches": [{"line": 41, "text": …, "context": […]}]}. Without a pattern, it returns {"total_lines", "range": [start, end], "lines": [{"line", "text"}…]}, where end is capped at start + max_lines - 1.

query_journalctl has a related trap. It runs journalctl … -n <lines> first, then applies grep_pattern to that already-truncated window (services.py:102–116). "grep 'error' since 1 hour ago, lines=50" therefore searches only the last 50 lines of the hour, not the whole hour, and an empty result does not mean "no errors". journalctl --grep would filter before truncating.

5.5 Walkthrough (network): list_listening_ports / find_port_owner

flags = "-lpnH"
if proto == "tcp":   flags += "t"
elif proto == "udp": flags += "u"
else:                flags += "tu"
res = run(["ss", flags])
...
return {"listening": _parse_ss(res["stdout"])}

(network-mcp/src/netmcp/tools.py:189)

-H suppresses the header, so _parse_ss can split rows positionally. It reads netid, state, recv-q, send-q, local and peer. It then pulls users:(("node",pid=4512 out with a regex (tools.py:465). This design is typical of the repo: - It chooses machine-friendly output (-H, ip -j, nmcli -t, mtr --json, lsblk -J) so parsing is trivial. - The parsers are module-level functions, so the tests can feed them canned text (network-mcp/tests/test_network.py:33).

Two caveats come from ss semantics rather than from the code: - ss -p reveals owner processes only for sockets you own unless you are root. For other users' sockets the process/pid keys are simply absent. - find_port_owner runs ss -tulpnH "( sport = :N or dport = :N )". The -l flag restricts it to listening sockets, so the docstring's "listening or connected" is wrong: established connections to that port are never shown, and "free": true means only "nothing is listening". port is typed int, so the filter string cannot be abused for injection.

5.6 cachyos arch.py: package intelligence

AUR RPC. _aur_get(path, params) sends a GET to https://aur.archlinux.org/rpc/v5/<path> with httpx. httpx is a transitive dependency via network-mcp, as the comment at arch.py:127 admits. The User-Agent is cachyos-mcp/0.1 and the timeout 12 s. All failures turn into {"error": "AUR RPC: …"}. Search uses search/{query}?by=name-desc; info uses info?arg[]=name.

search_all_repositories is the "anti-hallucination" tool. The idea: instead of letting the model guess a package name from its training data, give it everything that actually exists in one call.

combined.sort(key=lambda r: (
    r["name"] != query,        # exact-name matches first
    r["source"] == "aur",      # repo before AUR
    -(r.get("aur_votes") or 0)))

(cachyos-mcp/src/cachyosmcp/arch.py:255)

It merges pacman -Ss query (parsed by _SS_HEADER, including the [installed] marker) with AUR search hits, then sorts as shown. Traps: - AUR entries always carry "installed": False (arch.py:249), even when the package is installed as a foreign package. - AUR errors are dropped without a trace. If the AUR RPC returns an error, for example on a too-short or too-broad query, the if … not aur.get("error") branch simply omits the AUR results. The response contains no flag saying so, and the model may conclude that no AUR variant exists. - pacman -Ss treats its argument as a regex, so query is interpreted as a regex on the repo side but as plain text on the AUR side.

Example: what search_all_repositories actually returns. For a query with one hit in the official repos and one on the AUR (version numbers, vote count and description are invented for illustration):

// request
{"name": "search_all_repositories", "arguments": {"query": "htop", "limit": 20}}

// response
{
  "query": "htop",
  "results": [
    {"name": "htop", "source": "core", "version": "3.3.1-1",
     "installed": true, "description": "Interactive process viewer"},
    {"name": "htop-vim", "source": "aur", "version": "3.3.0-1",
     "installed": false, "description": "htop with vim-style navigation…",
     "aur_votes": 12, "popularity": 0.31, "out_of_date": false}
  ],
  "repo_count": 1,
  "total": 2
}

(cachyos-mcp/src/cachyosmcp/arch.py:230–261.) Two of the traps above are visible directly in this shape: the AUR row carries "installed": false regardless of whether htop-vim is actually installed as a foreign package, and the two rows have different key sets — repo rows have no aur_votes, popularity or out_of_date. Code that assumes one schema across results breaks on the first AUR hit.

check_updates needs no root. checkupdates (from pacman-contrib) syncs into a temporary database, so it works without root. AUR updates come from paru -Qua. The code ignores both rc and stderr (arch.py:399–409). That handles checkupdates' exit code 2 for "no updates", but it also means that a network failure is indistinguishable from {"count": 0}.

The remaining read tools map one-to-one onto pacman queries:

get_pacman_log, get_mirrorlist and get_package_cache_info read files and directories directly. list_kernels matches pacman -Q output against a regex.

5.7 The privilege ladder

pacman needs root, and the MCP server runs as the user. _privileged(cmd, execute=True) (arch.py:62) resolves this in a fixed order:

1. The gate. require_actions() runs first; see 5.8.
2. Removal never runs. If execute=False, the tool returns {"executed": False, "command": "sudo pacman -Rns …"}. remove_packages always passes execute=False (arch.py:457), so removal is never executed. Because the gate comes first, with actions disabled it does not even return the command.
3. Passwordless sudo. It probes sudo -n true (5 s timeout). On rc 0 it runs sudo -n <cmd> and returns method: "passwordless" with the last 4000 characters of output.
4. GUI askpass. This step was added in commit 9c90b3d. It applies only if WAYLAND_DISPLAY or DISPLAY is set in the server's environment. The code then picks the first askpass helper it finds: $SUDO_ASKPASS, then ksshaskpass, lxqt-openssh-askpass, /usr/lib/seahorse/ssh-askpass, x11-ssh-askpass, ssh-askpass. It runs sudo -A <cmd> with SUDO_ASKPASS set. A non-zero rc gets a hint: "password cancelled/wrong or the command itself failed".
5. Hand the command back. Otherwise it returns the command with a hint to run it with Claude Code's ! prefix, or to add a NOPASSWD sudoers rule.

paru is handled by _paru_run, which walks a parallel ladder without sudo in front, because paru builds as the user and calls sudo only for the pacman step. On the askpass step it injects --sudoflags -A. Note that _paru_run does not check the gate itself. Both callers do it (system_update with aur=True at arch.py:420, and install_aur_package at arch.py:438), so the gate check depends on caller discipline.

Example: the same call, three outcomes. install_packages(names="htop") builds sudo pacman -S --needed --noconfirm htop and hands it to _privileged. Three different hosts produce three different results for that identical call (rc and output text are invented for illustration):

Passwordless sudo configured:

{"executed": true, "command": "sudo pacman -S --needed --noconfirm htop",
 "method": "passwordless", "rc": 0,
 "output": "resolving dependencies...\n…\ntotal installed size: 1.42 MiB\n"}

No passwordless sudo, but a Plasma session with ksshaskpass on PATH (the user approved the popup):

{"executed": true, "command": "sudo pacman -S --needed --noconfirm htop",
 "method": "askpass", "rc": 0,
 "output": "resolving dependencies...\n…\ntotal installed size: 1.42 MiB\n"}

Headless, no DISPLAY/WAYLAND_DISPLAY, no passwordless sudo:

{"executed": false, "command": "sudo pacman -S --needed --noconfirm htop",
 "hint": "passwordless sudo not configured and no GUI askpass found. Run this command yourself (in Claude Code: prefix with '!'), or add a NOPASSWD sudoers rule for pacman."}

(cachyos-mcp/src/cachyosmcp/arch.py:62–95, _privileged; call site arch.py:428–433, install_packages.) Only the third case is distinguishable by shape alone if a caller drops the method field — both successes report "executed": true, so a downstream reader that only checks executed cannot tell a silent sudo -n from a password popup the user just clicked through.

Observations on the ladder (interpretation marked): - Whether the ladder works depends on how Claude Code was launched. From a Plasma terminal, DISPLAY is inherited and a popup appears. Over SSH or from a systemd unit there is no display and you get the "return the command" branch. - The askpass popup is weak consent. sudo's askpass prompt shows "[sudo] password for …", not the command line. The user authorises something as root without seeing what. - Package names are split on whitespace, not validated. In install_packages, names.split() goes straight into pacman -S --needed --noconfirm *pkgs. A value such as "foo --config /tmp/x.conf" would presumably pass pacman options to a root process. The same applies to install_aur_package(name) and paru. - Sudo credential caching. Depending on sudoers timestamp_type, one successful askpass may make the next sudo -n true probe succeed. Later calls would then take the silent "passwordless" branch without a popup. This is likely but unverified. - AUR builds run unreviewed. --noconfirm on paru -Syu/-S skips PKGBUILD review, and AUR PKGBUILDs are arbitrary shell code.

5.8 The gating model

Both gates are plain environment variables of the server process. The server tests each value against {"1","true","yes","on"} at the start of every gated call:

def require_power() -> dict[str, str] | None:
    """Return an error dict unless BOTH the actions and power gates are open."""
    gate = require_actions()
    if gate:
        return gate
    if not power_allowed():
        return {"error": "power action disabled", ...}

(sysprobe-mcp/src/sysprobe/common.py:176)

Example: calling a gated tool with the flag unset. With SYSCONTROL_ALLOW_ACTIONS not set in the server's environment, every one of the 29 gated tools returns the same two-key dict, regardless of what it was asked to do:

// request
{"name": "control_service",
 "arguments": {"service": "nginx.service", "action": "restart"}}

// response
{
  "error": "action disabled",
  "hint": "set SYSCONTROL_ALLOW_ACTIONS=1 in the MCP server env to enable mutating tools (default is read-only)."
}

(network-mcp/src/netmcp/common.py:148–156, require_actions; called from sysprobe-mcp/src/sysprobe/services.py:242–244.) The gate runs before anything else in the function body — action is never checked against the allowed set {"start", "stop", "restart", "reload", "enable", "disable"} at all in this call, since the gate returns first. The model sees the identical error whether it tried to restart a service, kill a process, or (with both flags) reboot the machine.

That is 29 gated tools and 82 ungated ones. Some drift between docs and code: - kde_notify is ungated. Its docstring says "Harmless, ungated" (desktop.py:491), but the sysprobe README lists it under the gated control tools. - suspend_system is gated only once. It needs just the actions flag, not the power flag. - Some ungated tools still have side effects: - scan_wifi(rescan=True) triggers a radio scan. - bluetooth_scan switches the adapter into discovery. - http_probe accepts any HTTP method, including DELETE. - get_public_ip calls the third-party service ifconfig.co.

5.9 Inventory: desktop vs headless

The classification below is the author's of this chapter, derived from which CLIs and which D-Bus/session services each tool needs.

_QDBUS is resolved once at import time (desktop.py:21), so installing qdbus6 while the server runs has no effect until it restarts.

5.10 Security: what the gates guarantee, and what they do not

Guaranteed. The flags live in the server's environment, which Claude Code sets when it spawns the process (the READMEs show claude mcp add … -e SYSCONTROL_ALLOW_ACTIONS=1). Nothing in the MCP protocol lets the model change another process's environment, and the check runs inside the server before any command. This is Ch 2's "put the guardrail where the model isn't". The double gate means that turning on "change my brightness" does not also turn on reboot.

Not guaranteed.

1. A shell in an ungated tool. This is the most serious problem in the three repos.

python @mcp.tool() def check_command_exists(command: str) -> dict[str, Any]: """Is a CLI tool installed? Returns presence + absolute path.""" path = run(["sh", "-c", f"command -v {command}"]).get("stdout", "").strip() from shutil import which as _w p = _w(command) or (path or None) return {"command": command, "exists": bool(p), "path": p} (sysprobe-mcp/src/sysprobe/diag.py:129)

command is interpolated into sh -c. For "x; id", shutil.which("x; id") returns None, so path is the shell's stdout, and the injected command's output comes back in the path field. This is arbitrary command execution with output capture, in a tool that is not gated. It bypasses SYSCONTROL_ALLOW_ACTIONS entirely. It could also be used to edit the MCP config that sets the flags.

2. The file readers read anything the user can read. read_config_snippet, grep_file and list_directory_tree have no path allowlist. ~/.ssh/id_ed25519, ~/.claude/.credentials.json, browser profiles and .env files are all reachable. On top of that, _expand applies os.path.expandvars to the model's input and echoes the resolved path in error messages. So read_config_snippet("$SOME_TOKEN") likely leaks that environment variable's value inside "not a file: /…/<value>".

3. Process tools expose other processes' command lines. find_processes and get_process_info return cmdline, and /proc/*/cmdline is world-readable by default. Secrets passed on argv are therefore exposed, including other users'. nm_wifi_connect itself passes the Wi-Fi password on argv (tools.py:439). inspect_process_io lists open files and sockets, but only for your own processes: psutil raises AccessDenied for others unless the server runs as root.

4. Network reach. port_scan is ungated and scans any host. With nmap present it uses -Pn -T4. The socket fallback's port parser has an ordering bug: it expands ranges before the 1024 cap (advanced.py:178 and 328), so "1-2000000000" iterates two billion times. http_probe is effectively SSRF to any URL, including localhost admin APIs, and returns set-cookie headers. tls_cert_info uses a verifying context, so it cannot inspect an already-expired or self-signed certificate: that is a handshake error.

5. Argument injection. Host, name and query strings go into argv without a check for a leading -. This affects ping, mtr, nmap, whois, journalctl -u and pacman. It is not shell injection, but nmap in particular has options that write files. That is presumably reachable via port_scan(host="-oN…"); not tested here.

6. Gated tools are more powerful than their names suggest. capture_packets splits bpf_filter on whitespace into tcpdump argv, so tcpdump options such as -w or -z are accepted. It also needs root or CAP_NET_RAW. launch_app runs any binary on PATH with whitespace-split arguments. kill_process accepts pid=-1, which os.kill interprets as "every process I may signal". Once actions are on, the gate is one switch for 28 tools. Per-tool granularity has to come from Claude Code's permission rules (Ch 1).

7. Untrusted text flows into context. Several tools return strings that someone else controls: AUR descriptions, whois records, SSIDs from scan_wifi, Bluetooth names from bluetooth_scan, journal lines and file contents. Anyone within radio range can name a network. Combined with item 1, the chain is plausible: attacker-controlled text reaches the model, the model calls check_command_exists, and a shell runs. This is interpretation, but every link is in the code. If the user has allowlisted mcp__cachyos__* to avoid permission prompts, nothing stands in the way.

Stdout hygiene, by contrast, is clean. There is no print() anywhere in the three src/ trees, all child output is captured, and detached apps get DEVNULL.

5.11 Tests

There are 23 pytest functions: sysprobe 8, network 10, cachyos 5. - Pure-function tests cover strip_ansi, grep, tail, clamp, _parse_ss, _parse_nethogs, _parse_ports, both speedtest parsers, _parse_pacman_search (including the group and [installed] forms) and _parse_info (wrapped values). - Gate tests cover require_actions and require_power (all three combinations). - Environment tests cover rc 127 for a missing binary and venv stripping from PATH. - Registration tests assert at least 55 tools for sysprobe, at least 30 for network and at least 100 for cachyos. They go through asyncio.run(mcp.list_tools()). - Live calls: get_system_info and which_package_owns are called for real, with Cap stubs.

Not tested: check_command_exists, the privilege ladder and askpass, any gated tool's behaviour with the gate open, and the port-range bug.

5.12 What to take away

• Composition by register(mcp) gives you small deployable servers and a bundle, from the same code. But the bundle sends only its own instructions, and a broad except Exception: pass hides a missing half. Assert tool counts in tests.
• Make the subprocess wrapper total. Never raise, map failures to shell-style return codes, strip ANSI, and scrub the interpreter's environment so system tools do not run inside your venv. Then apply the same rules to every spawn path, including detached ones.
• "Hard limits" should count bytes, not just lines. And "read-only" is not "harmless": a read tool that can reach ~/.ssh or run sh -c is a capability, whatever its docstring says.
• A server-side env gate is real enforcement only if no ungated tool can do what the gated ones do. One interpolated string in a helper tool voids the whole model.
• A privilege ladder that ends in "return the command" is a sound default: the model proposes, the human executes. Each rung above it (NOPASSWD, askpass) trades informed consent for convenience.

6.1 What Serena provides, what AIDEN adds, and how the two are joined

Serena (oraios/serena, MIT) is an MCP server that gives an agent LSP-backed symbol tools. It starts real language servers (pyright, tsserver, gopls, ...) through its solidlsp layer and exposes their answers as tools: find_symbol, find_referencing_symbols, rename_symbol, replace_symbol_body, per-file diagnostics. These answers are type-resolved. They are also only as fast as a language server, and they are live queries, not a persistent index.

AIDEN keeps all of that and adds four layers that Serena does not have. There is a persistent tree-sitter/SQLite index with hybrid search, name-based code graphs, dev-ops tools, and a Diary-backed memory that replaces Serena's .serena/memories Markdown files.

How AIDEN's tools get in. Serena discovers tools by enumerating subclasses. ToolRegistry (a singleton) walks every subclass of Tool that defines apply and whose module starts with a prefix in tool_packages. AIDEN appends its own package and imports it before the singleton is built:

tools_base.tool_names_excluded_from_registry.update(LOCAL_MEMORY_TOOLS)
for legacy_name, diary_names in LEGACY_MEMORY_TOOL_EXCLUSION_ALIASES.items():
    tools_base.tool_exclusion_aliases.setdefault(legacy_name, set()).update(diary_names)
if "aiden.tools" not in tools_base.tool_packages:
    tools_base.tool_packages.append("aiden.tools")
import aiden.tools  # noqa: F401

(volantic-codescope/src/aiden/cli.py:67)

Order matters here. Commit 7fa4c30 records a bug where the registry was built during test collection, before AIDEN had registered its tools, which froze it without them. test/conftest.py now copies the production init order.

As in every FastMCP server (Ch 2), each tool's JSON schema and description come from apply()'s signature and docstring. Tool names come from the class name: SearchCodeTool becomes search_code.

The "two deliberately small Serena hooks". The README names two:

1. Tool exclusion (serena/tools/tools_base.py:530-531, agent.py:172-181). There is a set of names the registry skips entirely (read_memory, write_memory, onboarding, ...), plus an alias map. Excluding a legacy name in config also excludes its Diary replacements. For example, excluding read_memory removes memory_context, memory_get, memory_project_context, memory_search and memory_search_semantic.
2. The Diary activation hint (agent.py:1051-1052). If the active tool set contains memory_project_context, the project activation message ends with "Diary is the only memory backend. Call memory_project_context now...". This is prompt text, not enforcement (Ch 1: persuasion).

Two more patches are applied at runtime from aiden/cli.py without editing Serena's files. ActivateProjectTool.apply is wrapped to start the explorer, and every AIDEN tool's apply is wrapped to append explorer notices. The wrappers use functools.wraps, and the code comment calls that "load-bearing, not cosmetic". Commit 8081f1f explains why. Without wraps, ActivateProjectTool lost its docstring, Serena refused to start ("apply method has no (or empty) docstring"), and "the last release shipped unusable."

The mergeability claim versus the diff. The package docstring says the Serena internals are "kept unmodified". The fork point is upstream as of 2026-06-13. The diff from there to HEAD touches 6 upstream files: +244/−16 lines.

Each change is small and self-contained, so the strategy is plausible. It is also untested: the clone has no upstream merge after the fork (it is shallow, but no merges appear after the first AIDEN commit). As an aside, CLAUDE.md and AGENTS.md still tell agents to read .serena/memories, a directory that 7fa4c30 deleted.

6.2 The index: parsing and schema

Parsing (index/parser.py, languages.py, queries/). There are 33 .scm files, matching the README's "33 languages" claim, but only 30 of them are mapped in languages.py's _LANG_QUERY_STEM dict — chatito, properties and udev have no entry, so the README's language count overstates what the code actually supports. Each mapped language has an Aider "tags" query, vendored under Apache-2.0. The module header records a workaround: tree_sitter_language_pack.get_parser "returns a parser object with a broken ABI in this version", so AIDEN calls get_language and builds its own tree_sitter.Parser. The queries use a capture vocabulary that AIDEN turns into rows:

• @name.definition.<kind> gives the symbol's name and position.
• @definition.<kind> gives the full node (range and body).
• @name.reference.<kind> gives a reference, which later becomes a graph edge.

Within one match, the i-th name node is paired with the i-th full-definition node of the same kind. signature is the first line of the body, capped at 240 characters. The body is capped at _MAX_BODY_CHARS = 20_000. The comment explains why the cap is large: a tight cap "made the tail of every long function invisible to all retrievers". Files are skipped if they exceed 2 MB, have a NUL byte in the first 8 KiB, are symlinks, or sit in a hard-coded ignore list (node_modules, .venv, dist, vendor, .serena, ...). Only the root .gitignore is read (indexer.py:188), so nested .gitignore files have no effect.

Storage (index/store.py). One SQLite file, <project>/.serena/aiden/index.db. On first use, an index left at the pre-rename path .serena/codescope/index.db is renamed into place, including its -wal and -shm files.

Every row belonging to a symbol shares one integer id: symbols.id, the FTS rowids, and chunks_vec.sid. That makes "delete everything for this file" an exact operation. Despite the name chunks_vec, there is one vector per symbol and no separate chunking.

The connection settings come from how the database is used: many short-lived connections (one per tool call), mostly reads. The code sets journal_mode=WAL, synchronous=NORMAL, a 64 MB page cache and a 256 MB mmap. The connection uses isolation_level=None, and transactions are opened explicitly with BEGIN IMMEDIATE. The comment gives the reason: Python's implicit-transaction mode turned every per-file SAVEPOINT release into a full commit. A full reindex commits every 200 files (_COMMIT_EVERY_FILES), so searches are not blocked for long. close() rolls back and never commits, "where committing would publish the partial state of a failed reindex."

refs.owner_id was added in d91f8e8. Before that, every graph query re-derived ownership with one range query per reference: 60 ms for one query, 0.7 ms after. The column is filled once, while the file's symbols are already in memory. Existing indexes migrate in place with ALTER TABLE and a backfill UPDATE ... ORDER BY (end_line-start_line) ASC LIMIT 1, so they need no rebuild.

6.3 Keeping the index fresh

Change detection. index_file always reads the file and compares its blake3 hash with files.hash. The module docstring promises "a cheap mtime+size pre-filter", but no such check exists in the code. A full reindex therefore reads and hashes every file, and parses only the ones that changed.

Git-scoped sync (incremental.py, tool sync_index):

1. pygit2.Repository.status() returns the changed and deleted paths, relative to the project root. Ignored and current files are masked out.
2. Two meta keys hold the state from the previous sync: git_head and git_dirty_paths (a JSON list).
3. If HEAD moved, if there is no recorded dirty set, or if .gitignore is dirty now or was dirty last time, AIDEN runs a full hash-skipping reindex.
4. Otherwise it reindexes only the changed files, the deleted files, and files that were dirty last time but are clean now. That last group covers files restored or stashed without a HEAD change.
5. The new state is recorded only if errors == 0, so a failed sync is retried next time.

Outside git, sync falls back to a full hash-based reindex.

Watcher (watcher.py). watchfiles.watch() runs in a daemon thread and uses DefaultFilter extended with AIDEN's ignore directories. AIDEN passes no debounce argument, so batching follows watchfiles' default. For each batch it calls reindex_paths on the changed source files plus any paths that no longer exist. A change to .gitignore triggers a full reindex. Watchers are stored in a module-level dict keyed by resolved root, so there is one per process, not one per project.

Progress (progress.py). IndexProgress records the phase (scanning → parsing → pruning → embedding), done/total counts, and a finished result that stays readable for 90 s. It lives in a per-process dict. To see writes made by other processes, the explorer uses index_revision() (indexer.py:93): size:mtime_ns of index.db and index.db-wal. The WAL file is included because "a committed write can sit there for a while."

6.4 Embeddings (index/embed.py)

All three L2-normalize their output, so sqlite-vec's L2 distance maps directly to cosine (cos = 1 − d²/2, search.py:192). auto falls back to hashing when fastembed fails to load. _update_embeddings then refuses to let that fallback replace an existing semantic index ("Semantic backend unavailable; keeping existing ... vectors").

What gets embedded. build_embed_text produces f"{kind} {name}\n{signature}\n\n{body[:1800]}". The name and signature are included so that the query "validate an auth token" can land on validate_token. The path is left out on purpose. Path is already a weighted BM25 column, and putting it in the vector "makes two identical functions in different files look different -- which is precisely the case clone detection must catch." DEFAULT_MAX_CHARS = 4000 is a hard backstop for raw snippets.

The batch budget. This part is backed by measurements in commits 4454719 and 7dd782d.

def batch_size_for(self, longest: int) -> int:
    longest = max(1, longest)
    return max(1, min(self.batch_size, self.batch_cost // (longest * longest)))

def embed_batched(self, texts):
    order = sorted(range(len(texts)), key=lambda i: -len(texts[i]))
    size = self.batch_size_for(len(texts[order[0]]))
    for start in range(0, len(order), size):
        yield self._embed_indices(texts, order[start : start + size])

(volantic-codescope/src/aiden/index/embed.py:163)

Three separate effects shape this code:

• Cost is count × longest². ONNX pads every item in a batch to the batch's longest member, and self-attention allocates a length×length matrix per item. AIDEN_EMBED_BATCH_COST defaults to 20,000,000 char². At about 1,900 characters per text that allows about 5 items per pass. AIDEN_EMBED_BATCH (default 128) is only an upper bound.
• Longest first. ONNX Runtime grows its memory arena for each new tensor shape and never returns it. With ascending lengths, every batch is a slightly bigger shape, and memory "passed 3.2 GB and kept climbing". Running the largest batch first allocates the peak once, and every later batch fits inside it.
• One fixed item count per pass. Letting short-text batches grow to fill the budget makes them larger in the count dimension, so the arena grows again ("1.7 GB to 3 GB over one run"). The count is computed once, from the longest text.

The recorded result is a flat 1.59 GB peak for a full index of the repository itself (545 files, 7,080 symbols, 1,200 s), against about 20 GB originally reported.

Resumable writes. embed_batched yields one batch at a time. _embed_pending writes each batch (insert_embeddings) and commits it, so a run killed by a systemd-run -p MemoryMax=2G cap loses only the batch in flight. The next run embeds symbols_without_embeddings(), a SQL NOT IN anti-join.

Model reuse. _CACHE memoizes embedders by configuration and by stored id. The model is built outside the lock, and the first instance to land in the cache wins via setdefault. Before this cache, "every semantic search previously reconstructed the ONNX model (~2.7 s and ~0.9 GB)" (CHANGELOG).

6.5 Hybrid search (index/search.py)

hybrid_search runs up to four rankers over a candidate pool of max(limit×10, 100) each and fuses them with RRF, the same method as Diary (Ch 3):

rankings = {
    "name": self._name_ids(store, query, pool, flt),
    "bm25": self._bm25_ids(store, query, pool, flt),
    "vector": self._vector_ids(store, query, pool, flt),
}
if _IDENTIFIER_RE.match(query.strip()):
    rankings["trigram"] = self._trigram_ids(store, query.strip(), pool, flt)
weights = {"name": 1.5, "bm25": 1.0, "vector": 1.0, "trigram": 0.5}

(volantic-codescope/src/aiden/index/search.py:501)

The fused score is Σ w / (RRF_K + rank + 1) with RRF_K = 60 (search.py:40). Unlike Ch 3's plain RRF, each ranking here has a weight.

Worked example — fusing three rankings. The rankings themselves are illustrative (a real query depends on the live index); the arithmetic, RRF_K, and the weights are exact (_rrf, search.py:478-485; weights, search.py:510). Say bm25 ranks index_file first and _read_source second, and vector ranks adopt_legacy_index first and index_file third; name returns [] for this query (see below), so it contributes nothing:

index_file outranks adopt_legacy_index, even though adopt_legacy_index was actually first in its own ranking, because index_file is the only candidate two rankers agree on. That is the point of RRF: a candidate confirmed by two retrievers beats one retriever's single top pick, without ever comparing a BM25 score to a cosine distance.

Abstain without evidence (bb00c60). The name ranker used to match any symbol whose name contained any one query word, and it had the highest weight. "reuse before writing new code" returned five methods called new. The fix has two parts. A query of three or more words now needs a name that covers at least two of them. If no name clears that bar, the ranker returns [] instead of a weak guess, because "a weak name match would outrank both" BM25 and the vector search. The trigram ranker is excluded from prose queries for a similar reason. Earlier it returned rows in storage order, and fusion treated that order as a ranking, which "injected noise into every hybrid search."

Filters. SearchFilter(path_glob, lang, kind, exclude_tests) is applied inside each ranker, before its top-k cut. The SQL uses GLOB, not LIKE. 682111f found that LIKE is case-insensitive and has no character classes, so *Test.* excluded latest.py. The vector ranker cannot push a filter into MATCH, because +path/+lang are auxiliary columns, not partition keys. It uses one of two strategies. When 2,000 or fewer symbols pass the filter, it scores those vectors exactly with numpy. For wider filters it runs an 8× over-fetched kNN, then a 64× one, and only then falls back to the exact scan. The recorded result is 66 ms against 321 ms for always scanning exactly.

Folded previews. Each hit carries preview, 12 lines by default: the first two thirds of the body, a ... [N lines omitted] ... marker, and the tail (_fold, search.py:165). The docstring's reasoning: a hit with no code forces a second read, and a hit with the whole body wastes context.

Example — a search_code call. A prose query misses the name ranker even when a matching function exists, if the name only covers one of the query's tokens (the abstain rule above). Here index_file (indexer.py:245-276) is found anyway, by BM25 and the vector ranker:

// tool call (SearchCodeTool.apply, search_tools.py:29-61)
{"name": "search_code", "input": {"query": "does a full reindex use an mtime check before hashing a file", "limit": 5}}

// result: JSON list of SearchHit, one per hit (dataclasses.asdict, search.py:200-214)
[
  {
    "symbol_id": 5219,
    "name": "index_file",
    "kind": "function",
    "path": "src/aiden/index/indexer.py",
    "start_line": 245,
    "end_line": 276,
    "signature": "def index_file(self, store: IndexStore, abs_path: Path, rel_path: str, *, force: bool) -> tuple[str, list[tuple[int, str, str, str]]]:",
    "score": 0.032266,
    "lang": "python",
    "preview": "    def index_file(self, store: IndexStore, abs_path: Path, rel_path: str, *, force: bool) -> tuple[str, list[tuple[int, str, str, str]]]:\n        \"\"\"Index a single file.\n\n        :return: ``(outcome, inserted)`` where outcome is 'indexed'/'skipped'/\n            'error' and ``inserted`` is the list of ``(sid, body, path, lang)``\n            for newly stored symbols (empty unless outcome == 'indexed').\n        \"\"\"\n        data = self._read_source(abs_path)\n... [21 lines omitted] ...\n            log.warning(\"Failed to store %s: %s\", rel_path, e)\n            return \"error\", []\n        return \"indexed\", inserted",
    "sources": ["bm25", "vector"]
  }
]

symbol_id and score are illustrative; everything else follows from the code as written: the fold at 8 head / 3 tail lines around a ... [N lines omitted] ... marker (_fold, search.py:165-180), and the missing "name" entry in sources — the query's tokens of 3+ characters cover only file in index_file, short of the 2-token minimum a 9-token query needs, so the name ranker returns [] rather than a weak guess (search.py:336-353).

search_semantic is vector-only and falls back to BM25. search_regex runs rg --json -e PATTERN -- root with a 30 s timeout.

6.6 The graph and the LSP hierarchies

graph.py stores no edges. It derives them on demand, by name:

• Caller: a reference's owner_id, the innermost symbol containing it (_dependents: refs JOIN symbols ON s.id = r.owner_id WHERE r.name = ?).
• Callee: a referenced name that is also defined in the project. It resolves to one definition via ORDER BY CASE WHEN path=? THEN 0 ELSE 1 END, path, start_line LIMIT 1, which prefers the same file and otherwise takes the alphabetically first path.

What this means for accuracy follows directly from the code. The Python query captures attribute: (identifier) @name.reference.call, so self.store.commit() records the reference commit. As a result:

• get_dependents("commit") lists every function that calls any .commit(), whether the target is a Git helper, a SQLite connection, or this project's method.
• A callee with several same-named definitions is resolved to one of them more or less arbitrarily.
• Dynamic dispatch, overloads and scopes are not modelled. Calls to library code disappear, because refname not in defined drops them.
• get_type_hierarchy falls back to parsing base types out of the stored declaration line (base_type_names) and keeps only project-defined names.

call_chain (forward) and change_impact (reverse, "blast radius") expand this relation recursively to depth=3. The visited set is per branch, so cycles terminate, but a diamond is expanded once per path.

This is why hierarchy_tools.py exists. get_call_hierarchy and get_type_hierarchy locate the symbol through Serena's LSP retriever and send callHierarchy/* / typeHierarchy/* requests through the new solidlsp methods. Those answers are type-resolved. Several servers, pyright among them, implement call hierarchy but not type hierarchy. For those, the type tool returns the index's structural answer in the same JSON shape, tagged "resolved_by": "index" with a warning note. The docstrings tell the agent which tool fits which question: the index graph for fast overviews, the LSP tools "when correctness matters."

The explorer's whole-project graph is stricter than graph.py. It counts only names with exactly one defining file (WITH unique_def AS (... HAVING COUNT(DISTINCT path) = 1), explorer.py:755).

6.7 get_code_context (index/context.py)

get_code_context replaces a chain of calls (search, read, callers, callees, find a test) with one:

1. hybrid_search(query, limit=max_symbols, exclude_tests=True, preview_lines=0). If that finds nothing, it retries without the test filter ("Tests may be the only place a name appears").
2. For each hit, the body is folded to body_lines (default 80) and truncated is set.
3. called_by comes from dependents_in. calls comes from dependencies_in, pinned to this exact definition by path and start line. tests are the dependents whose path contains test or spec. Each list is capped at related (default 5).
4. Edges are flagged speculative when the related symbol's name has more than one definition. The result also carries warnings, for example "No embeddings indexed: matching was lexical only."

Example — get_code_context for one query. Asking how sync_index (6.3) picks between an incremental and a full reindex surfaces the function behind it, sync_incremental (incremental.py:121-150):

// tool call (GetCodeContextTool.apply, search_tools.py:224-258)
{"name": "get_code_context", "input": {"query": "how does sync_index decide between an incremental and a full reindex"}}

// result: CodeContext / SymbolContext (context.py:38-71); "code" is shortened here with "…" — the
// real field holds the full body, since the function is under the 80-line default body_lines budget
{
  "query": "how does sync_index decide between an incremental and a full reindex",
  "symbols": [
    {
      "symbol_id": 8841,
      "name": "sync_incremental",
      "kind": "function",
      "path": "src/aiden/index/incremental.py",
      "start_line": 121,
      "end_line": 150,
      "lang": "python",
      "signature": "def sync_incremental(indexer: Indexer, *, embeddings: bool = True) -> ReindexReport:",
      "code": "def sync_incremental(indexer: Indexer, *, embeddings: bool = True) -> ReindexReport:\n    \"\"\"Fast incremental update scoped to git working-tree changes.\n\n    Falls back to a full (hash-based) reindex for non-git projects.\n    \"\"\"\n    changes = git_changes(indexer.root)\n    …",
      "truncated": false,
      "called_by": [
        {"name": "apply", "kind": "function", "path": "src/aiden/tools/incremental_tools.py", "start_line": 23, "speculative": true}
      ],
      "calls": [
        {"name": "git_changes", "kind": "function", "path": "src/aiden/index/incremental.py", "start_line": 82, "speculative": false},
        {"name": "reindex", "kind": "function", "path": "src/aiden/index/indexer.py", "start_line": 297, "speculative": false}
      ],
      "tests": [
        {"name": "test_sync_incremental_non_git_falls_back", "kind": "function", "path": "test/aiden/test_incremental.py", "start_line": 64, "speculative": false}
      ]
    }
  ],
  "warnings": []
}

symbol_id is illustrative; the rest is real, including the one speculative: true edge. The caller of sync_incremental is a method literally named apply — every Tool.apply is (incremental_tools.py:23, SyncIndexTool.apply) — so that name resolves to dozens of definitions project-wide and the edge is flagged, even though sync_incremental itself is unique (_ambiguous_names, context.py:159-162).

Two notes. First, "the budget" is lines and counts (max_symbols=3, body_lines=80, related=5). The module docstring mentions "an explicit token budget", but nothing counts tokens. Second, the speculative flag is computed on the related symbol's name. A caller of an ambiguous focus symbol such as save is not flagged if the caller's own name is unique, even though the edge might point at a different save. The test heuristic is a substring match, so inspector.py counts as a test file.

6.8 Clone detection

The minimum pairwise similarity is reported because similarity is not transitive. A chain A~B~C "can contain an A/C pair that is not similar at all", and a group with a high mean and a low minimum is such a chain. Both whole-index tools raise when there are no vectors, instead of returning []: "'no findings' must never be how a missing vector index reports itself." The diff gate also used to catch every exception, which "reported a broken backend as a clean diff". Both fixes apply the same rule as 6.5: an empty result has to mean empty.

6.9 The Diary bridge (src/aiden/diary.py)

AIDEN is itself an MCP client. Its eight memory_* tools are thin proxies. None of them touches Diary's Postgres database. Each one calls Diary's public tools over a persistent stdio session.

• Launch. AIDEN_DIARY_COMMAND is split with shlex and defaults to diary-mcp-local. The diary-mcp repo's pyproject.toml only defines diary-mcp, diary-admin-mcp and diary-web, so the default name has to be supplied separately, presumably by a local wrapper script. StdioServerParameters is built with no env. In the MCP Python SDK that normally means the child gets only a small whitelist of variables, not AIDEN's full environment. That makes a wrapper that sets DIARY_DATABASE_URL and similar variables likely necessary.
• Lifetime. start_blocking_portal() runs an anyio event loop in a background thread. One task (_serve) owns stdio_client and ClientSession for the whole life of the bridge and waits on a stop event. It is torn down in that same task because anyio's context managers must be exited in the task that entered them. Synchronous Serena tools call portal.call(self._call_tool, ...) under an RLock, so Diary calls are serialized. The session starts lazily, on the first memory tool call.
• Timeouts. AIDEN_DIARY_TIMEOUT_SECONDS (default 30) applies to the startup handshake, each call_tool read, and shutdown. A transport failure closes the bridge, and the next call starts a new one. A tool-level isError becomes DiaryBridgeError and leaves the session open.
• No fallback. If Diary cannot start, the tool fails with "Diary is required but could not be started with ...".
• Project auto-registration. memory_project_context derives a slug from the directory name ([^a-z0-9]+ → -). It then calls memory_set_project_dir(slug, root) before memory_project_context(slug). Diary appends to config.dirs, so two different checkouts that are both called api end up sharing one /projects/api node.

Example — one memory_* call, two Diary calls underneath. MemoryProjectContextTool.apply (memory_tools.py:26-38) is the proxy that does the auto-registration above. The model only ever sees one tool call and one result; everything between — the slug derivation and the two nested calls over the persistent stdio session — happens inside AIDEN's process:

system: [system prompt, tool schemas incl. AIDEN's memory_* tools]

user: Load this project's Diary context before we start.

assistant: I'll load the Diary context for this project.
{"type": "tool_use", "id": "toolu_01M9…", "name": "mcp__aiden__memory_project_context", "input": {}}

 waiting for the tool result

MemoryProjectContextTool.apply(project_slug_override=None, only_pinned=True)
root = get_project_root() = "/home/user/projects/volantic-codescope"
slug = project_slug(root) = "volantic-codescope"  (diary.py:234-239)
 starting diary-mcp-local over stdio (AIDEN_DIARY_COMMAND, diary.py:46)-> call_tool("memory_set_project_dir", {"project_slug": "volantic-codescope", "dir_path": "/home/user/projects/volantic-codescope"})
 Diary: appending to config.dirs<- structuredContent.result: "OK" (illustrative)

-> call_tool("memory_project_context", {"project_slug": "volantic-codescope", "only_pinned": true})
 Diary: loading pinned project memories<- structuredContent.result: "# /projects/volantic-codescope\n(3 pinned memories, illustrative)"

user: {"type": "tool_result", "tool_use_id": "toolu_01M9…", "content": "# /projects/volantic-codescope\n(3 pinned memories, illustrative)"}

assistant: Loaded. Diary has three memories pinned for this project — here's what they say…

The unwrap on the way back (structuredContent.result, then falling back to joined TextContent, diary.py:144-156) is why every Diary reply is a plain string to AIDEN's tools, not nested JSON.

If both diary-mcp and AIDEN are registered in Claude Code. There is no name collision, because Claude Code namespaces MCP tools per server (mcp__diary__memory_search versus mcp__aiden__memory_search). The functional duplication is real, though: the model sees two sets of near-identical memory tools, and both schemas are paid for in context (Ch 2). There are two costs beyond context:

• Every AIDEN session starts its own Diary child on first use, in addition to the one Claude Code started. The embedding-model leader election in Ch 3 limits the memory cost of that.
• The hint in 6.1 pushes the model toward AIDEN's copy.

The fix is on the server side. Add excluded_tools: [read_memory, write_memory, delete_memory, list_memories] to Serena's serena_config.yml, to the project's .serena/project.yml, or to a custom context. Through the alias map those four legacy names remove all eight Diary proxies. Naming the eight new names directly also works. Removing memory_project_context also removes the activation hint (its condition becomes false) and the automatic directory registration. A Claude Code permissions.deny rule would block the calls. Only the server-side exclusion verifiably removes the tools from tools/list.

6.10 The explorer web UI (src/aiden/web/)

The explorer is a Flask app on a fixed address, 127.0.0.1:24256 (0x5EC0, chosen to sit next to Serena's dashboard port 0x5EDA). It runs as a daemon thread inside whichever AIDEN process activates a project first. Later instances POST /api/projects with {root, pid} and attach to it instead of starting their own. Its tabs:

• Search: the same hybrid search, with the test filter
• Call graph, and a whole-project directory dependency ring
• File tree and per-file symbols
• Clone clusters (min_lines=8, similarity=0.92)
• Index health
• Four actions: reindex, sync, watch start, watch stop

Editing, deletion and shell access are deliberately absent. Actions the user triggers are reported to the agent in the next AIDEN tool result, framed as "a notification, not a request." Only the hosting process delivers these notices, which means other sessions never see them. The browser is opened from a separate Python process, because "a stdio MCP server shares stdout with the protocol" (Ch 2).

b411090, "stop treating loopback as a security boundary". Binding to 127.0.0.1 keeps out the network, but not two other attackers: any local process, and any web page the user visits. A page can point a hostname at 127.0.0.1 (DNS rebinding), or submit a cross-origin form, which is a "simple" request with no CORS preflight. Before the fix, POST /api/shutdown "took no body and no headers". Worse, the pid sent at registration was trusted and later passed to os.kill, which amounted to "an arbitrary-process-kill primitive for every process this user owns." After the fix:

Some exposure remains. Reads are still open to any local process of any user that can reach loopback: code search, file lists, and directory listings of $HOME. The pid check matches a substring. Shutdown still stops every attached AIDEN instance, including MCP servers that belong to other Claude Code sessions.

6.11 Dev-ops tools

• run_tests / detect_test_framework. Detects pytest, gradle, maven, npm/yarn/pnpm, cargo or go from project files and runs it with a 1,800 s subprocess timeout. The result carries parsed counts and the tail of the output.
• git_status, git_diff, git_commit, generate_changelog. Wrappers around git with a 60 s timeout. add_all runs git add -A -- ., scoped to the project on purpose. git_commit strips AI-attribution lines from the message (Co-Authored-By: ...Claude..., "Generated with ...", any line starting with 🤖) and reports sanitized: true.
• github_*. Seven tools: repo create, PR list/create, issue list/create, Actions runs, release create. They shell out to gh with a 120 s timeout and use its existing login. AIDEN stores no credentials of its own.
• create_project. Python/node/rust scaffolds. It refuses a non-empty target directory.

6.12 Tool inventory

That is 45 in total. After exclusions the Serena side registers about 44 tool classes, 13 of them JetBrains-only. Commit 8081f1f records a real stdio initialize → tools/list handshake that returned 66 tools, which means about 21 Serena tools in a default session. Serena's claude-code context removes six more (read_file, execute_shell_command, ...).

6.13 Traps

• vec0 rejects INSERT OR REPLACE. A backfill run works from a snapshot of "symbols missing a vector" taken minutes earlier. If the watcher or CLI filled some of them in meanwhile, the old plain INSERT failed with "UNIQUE constraint failed on chunks_vec". The fix (129dfdd) runs a DELETE followed by an INSERT.
• The atomic vector-table swap. When the embedder changes, every vector is computed in memory first. DROP + CREATE + inserts then run in one transaction, because SQLite DDL is transactional (41b2295). Before that fix, three autocommitted statements could leave the project with no vectors at all. A swap by renaming the table was rejected because ALTER TABLE ... RENAME does not rename vec0's shadow tables.
• Concurrency. WAL and BEGIN IMMEDIATE serialize writers, but nothing coordinates processes:
• An agent's reindex, a watcher (one per process), the CLI, and explorer actions can all write at once. The explorer's "already running" guard (_INFLIGHT) only knows about its own actions.
• The busy timeout is Python's default (5 s). A long rebuild_vec_table transaction can therefore make other writers fail with "database is locked".
• Language-server cap. Autodetection only enables languages with at least 10% of the source files, and at most MAX_AUTODETECTED_LANGUAGES = 4. Files in a fifth language get the improved "not enabled" error until the language is added to project.yml.
• Memory and disk. Each AIDEN process holds its own model (~0.9 GB), its language servers, a possible Diary child, and in the hosting process the explorer's reindex work. That is Ch 2's N-copies problem again. Bodies up to 20,000 characters are stored in both FTS tables, plus about 3 KB of vector per symbol.
• Tool timeout. Serena's default tool_timeout is 240 s, but a first reindex with a model download, or a long run_tests, can take longer. This is presumably why the README recommends aiden index build from a shell.
• Single-project mode. With --project and a single_project context such as claude-code, Serena excludes activate_project. The explorer hook wraps that tool's apply, so the explorer never starts automatically. The Diary hint still reaches the system prompt through the activation message.
• The wrong binary. The package also installs serena and serena-agent scripts. Starting those runs plain Serena, without AIDEN's tools and with local Markdown memory.

6.14 What to take away

• Extend by registration, not by edits. A plugin prefix, an exclusion set and an alias map keep a fork small. The claim "unmodified upstream" still has to be checked against the diff, and a merge strategy is untested until an upstream merge has actually happened.
• Make empty mean empty. Rankers that abstain, clone tools that raise when there are no vectors, and an index_status that reports "semantic search silently degraded to hash vectors" all protect the agent from reading "nothing found" as evidence.
• Measure memory, don't reason about it. count × longest² and longest-first ordering came from watching ONNX's arena grow. Both effects are invisible if you only count items.
• Say how exact an answer is. Name-based graphs are fast and approximate, so the code marks their edges speculative, tags fallback answers resolved_by: index, and points to the LSP tool for precise answers.
• Loopback is not authentication. A local web UI needs Host/Origin checks, a secret for state-changing requests, and verification of anything it is about to signal.

Two small repos that have nothing to do with each other. ccacct works on Claude Code's own config directory. cis-api wraps a university portal that has no API and exposes it as an MCP server. Each gets its own part.

Part 7A — ccacct

7.1 Where Claude Code keeps identity and setup

Claude Code allows one login per config directory. That directory is ~/.claude by default, and the CLAUDE_CONFIG_DIR environment variable overrides it. ccacct builds on this: one config directory per account, and the variable selects which one a process uses.

What sits in the config directory, sorted by role (this host's ~/.claude, names only, plus the script's own comments):

.claude.json has two quirks. The first is where it lives. Without CLAUDE_CONFIG_DIR it sits in $HOME, not inside ~/.claude. With the variable set, it sits inside that directory. The script encodes this rule once:

global_json_for() {
  local dir="$1"
  if [ "$dir" = "$PRIMARY" ]; then
    printf '%s\n' "$(dirname "$PRIMARY")/.claude.json"
  else
    printf '%s\n' "$dir/.claude.json"
  fi
}

_{claude-accounts/bin/ccacct:90}

The second quirk is what the file holds. Setup keys (mcpServers, projects with trust flags and allowedTools, hasCompletedOnboarding, skillUsage) sit next to identity keys (oauthAccount, userID, machineID). The comment at bin/ccacct:179 says it directly: this is the one place where setup and identity share a file, so the file can be neither symlinked nor ignored.

7.2 Profile creation: link everything, exclude a list

ccacct add work creates ~/.claude-accounts/work (mode 700). It then symlinks every entry of the primary directory into the new one, except for a denylist:

ISOLATED=(
  .credentials.json          # OAuth-Tokens: DAS unterscheidet die Accounts
  .claude.json               # enthält oauthAccount; wird stattdessen gemergt
  .config.json               # würde Claude Codes Pfadauflösung kapern
  .git .gitignore            # ~/.claude ist ein Repo; ein Link machte das Profil zum Worktree
  history.jsonl
  sessions tasks jobs queue
  file-history session-env shell-snapshots
  cache paste-cache statsig todos stats-cache.json
  daemon daemon.lock daemon.log daemon.status.json
  ...
)
OPTIONAL_ISOLATED=(projects)

_{claude-accounts/bin/ccacct:20}

is_isolated also skips anything matching *.log. --isolate-projects adds projects to the denylist and records that choice as a marker file, .ccacct-isolate-projects, inside the profile. Later sync/doctor runs read the marker back instead of asking again.

Why it is a denylist: the header comment (bin/ccacct:9) says new files that Claude Code or the user creates later should show up in every profile automatically. Commit c5aa9af records the change from the first version's allowlist to this denylist.

Two of the exclusions need explaining:

• .git/.gitignore. The author keeps ~/.claude in git. A symlinked .git would make git treat the profile directory as a working tree of the same repository. Every profile file would then show up as a change against the primary's index.
• .config.json. The comment only says it "would hijack Claude Code's path resolution." Presumably this refers to a legacy fallback: if a .config.json exists in the config directory, Claude Code uses it as the global config file instead of .claude.json. A symlinked copy would then point the profile at the primary's global config, identity included. This host has no ~/.claude/.config.json, so the entry is defensive.

share_one (bin/ccacct:147) is idempotent. A link that already points at the right target is left alone. A link pointing elsewhere is replaced. A real file or directory where a link should be is deleted with rm -rf and relinked. The comment names the cause: Claude Code writes files atomically (write a temp file, then rename), and the rename replaces the symlink with a regular file. link_shared then removes orphans, meaning links into $PRIMARY whose target is gone or has since become isolated.

Example: what a profile directory actually contains. After ccacct add work, most entries are symlinks into the primary; only the names in ISOLATED — plus .claude.json, merged rather than linked — are real files or directories. Ownership, sizes and timestamps below are illustrative; the names and the link/real-file split are not.

$ ls -la ~/.claude-accounts/work
drwx------  … .
lrwxrwxrwx  … CLAUDE.md -> /home/jane/.claude/CLAUDE.md
lrwxrwxrwx  … settings.json -> /home/jane/.claude/settings.json
lrwxrwxrwx  … skills -> /home/jane/.claude/skills
lrwxrwxrwx  … plugins -> /home/jane/.claude/plugins
lrwxrwxrwx  … hooks -> /home/jane/.claude/hooks
lrwxrwxrwx  … projects -> /home/jane/.claude/projects
-rw-------  … .claude.json           (real file — written by merge_claude_json, never linked)
-rw-------  … .credentials.json      (real file — written on `ccacct login work`; ISOLATED)
drwx------  … sessions               (real dir — ISOLATED)
drwx------  … cache                  (real dir — ISOLATED)
-rw-------  … history.jsonl          (real file — ISOLATED)

projects is a symlink here because work was created without --isolate-projects; with that flag it would be a real directory instead, from OPTIONAL_ISOLATED (bin/ccacct:36). Everything not named in ISOLATED (bin/ccacct:20-34) stays a link, so a rules/ directory added to the primary later shows up in work on the next link_shared pass (bin/ccacct:160-177) without any code change here.

7.3 The .claude.json merge

merge_claude_json passes source, destination, force flag, window and the key list to an inline Python program:

for key, value in primary.items():
    if key in account_keys:
        continue
    if key == "projects" and isinstance(value, dict):
        merged = dict(profile.get("projects") or {})
        merged.update(value)          # Primärprofil gewinnt, Eigenes bleibt erhalten
        profile["projects"] = merged
    else:
        profile[key] = value
for key in [k for k in profile if k not in primary and k not in account_keys]:
    del profile[key]
fd, tmp = tempfile.mkstemp(dir=os.path.dirname(dst) or ".", prefix=".claude.json.")
...
os.replace(tmp, dst)
os.chmod(dst, 0o600)

_{claude-accounts/bin/ccacct:208}

The semantics, one rule at a time:

1. ACCOUNT_KEYS (31 names, bin/ccacct:41) are never copied. The list covers identity (oauthAccount, userID, machineID), counters (numStartups, firstStartTime) and account-scoped caches: GrowthBook/experiment features, passes, overage credit, metricsStatusCache, groveConfigCache, among others.
2. projects is merged one level deep. A path key that exists in both files takes the primary's whole entry. Paths only the profile knows stay.
3. Every other key is replaced wholesale. That includes mcpServers: there is no per-server merge.
4. Deletions propagate. A setup key removed from the primary is removed from the profile. So is any non-account key the profile has and the primary lacks.
5. Write is atomic. mkstemp in the destination directory (the file is born 0600), then os.replace (an atomic rename(2) on the same filesystem), then an explicit chmod 600. A running Claude Code never reads a half-written file.
6. Live-session skip. If the destination's mtime is less than LIVE_WINDOW_SECONDS=120 old, the script prints SKIPPED and exits unless --force was given. The comment (bin/ccacct:54-56) only says a .claude.json that young "probably belongs to a running session — so don't write into it, except with --force." Presumably the underlying worry is that a running session writes .claude.json often and may hold its own copy in memory, so writing under it would either be overwritten when the session next saves, or clobber what the session just saved — but that mechanism is this chapter's inference, not something the comment itself states. This is a heuristic, not a lock. A session that has written nothing for two minutes counts as "not live".

Example: one sync, two keys. Say the primary has just gained a new MCP server and a newly trusted project; the profile's copy is a few days old. Emails and paths are illustrative; which key wins is not.

Primary (~/.claude/.claude.json, excerpt):

{
  "oauthAccount": { "emailAddress": "jane@example.com" },
  "mcpServers": { "cis": { "command": "/opt/cis-api/cis", "args": ["mcp"] } },
  "projects": { "/home/jane/main-project": { "hasTrustDialogAccepted": true } }
}

Profile before sync (~/.claude-accounts/work/.claude.json):

{
  "oauthAccount": { "emailAddress": "jane+work@example.com" },
  "mcpServers": {},
  "projects": { "/home/jane/side-project": { "hasTrustDialogAccepted": true } }
}

Profile after ccacct sync work --force:

{
  "oauthAccount": { "emailAddress": "jane+work@example.com" },
  "mcpServers": { "cis": { "command": "/opt/cis-api/cis", "args": ["mcp"] } },
  "projects": {
    "/home/jane/main-project": { "hasTrustDialogAccepted": true },
    "/home/jane/side-project": { "hasTrustDialogAccepted": true }
  }
}

oauthAccount is one of the 31 ACCOUNT_KEYS (bin/ccacct:41-52), so work's own login survives untouched. mcpServers is not on that list, so the primary's value replaces the profile's wholesale — there is no per-server merge. projects is the one key merged one level deep (bin/ccacct:211-214): the primary's path is added, and the profile's own unrelated path stays, because merged.update(value) only overwrites keys the primary itself has.

add always calls the merge with force (bin/ccacct:269). A new profile therefore starts with hasCompletedOnboarding and the primary's project trust, but no oauthAccount. That likely explains the hint cmd_login prints, "If no login dialog appears, type /login in the chat": the onboarding flow that would normally ask for a login is marked as completed.

7.4 Commands

Example: ccacct list. Three profiles: default is active, work is logged in under a different account, test has never logged in. Emails and the subscription name are illustrative; the column layout and the German status strings are exact.

$ ccacct list
   PROFIL   ACCOUNT                ABO     STATUS
*  default  jane@example.com       pro     aktiv
   work     jane+work@example.com  max20x  aktiv
   test     —                      —       nicht eingeloggt

The * marks whichever profile's directory equals $CLAUDE_CONFIG_DIR (or default if that variable is unset). account_info derives STATUS purely from .credentials.json's claudeAiOauth.accessToken/expiresAt/refreshTokenExpiresAt (bin/ccacct:113-143); test shows —/—/nicht eingeloggt because both files fail to parse and load() returns {}. Column widths are computed in a Python pass (bin/ccacct:299-325), not bash printf, because printf pads by byte count and the — placeholder is a multi-byte character.

Why use must be a shell function. A child process cannot change its parent shell's environment. A ccacct binary that exports CLAUDE_CONFIG_DIR changes only its own environment, and that change is gone when it exits. The dispatcher turns this into an error on purpose (bin/ccacct:682). shell-init prints a wrapper that runs inside the shell:

ccacct() {
  if [ "\${1:-}" = "use" ]; then
    ...
    dir="\$(command $SELF path "\$2")" || return 1
    export CLAUDE_CONFIG_DIR="\$dir"
    return 0
  fi
  command $SELF "\$@"
}

_{claude-accounts/bin/ccacct:610}

The fish version uses set -gx / set -e and adds completions that get profile names by parsing ccacct list. $SELF is expanded when the wrapper is generated, so the function contains the script's absolute path.

Inconsistency. run default and exec default clear the variable with env -u. login default runs a plain exec "$CLAUDE_BIN" (bin/ccacct:284). In a shell where ccacct use work is active, ccacct login default therefore starts Claude Code in the work profile.

doctor --fix ignores the live window. It calls sync_profile "$name" no yes (bin/ccacct:475), and the third argument is force=yes.

7.5 autosync install: a SessionStart hook in the shared settings.json

groups.append({"hooks": [{"type": "command", "command": command, "timeout": 15}]})

_{claude-accounts/bin/ccacct:532}

The command is CCACCT_AUTOSYNC=1 "<abs path>/ccacct" sync --all --links-only --quiet (bin/ccacct:495). Details:

• Event: SessionStart, no matcher. It therefore fires on every trigger (startup, resume, clear, compact; see Ch 1 and Ch 3's pin hook).
• Where: $PRIMARY/settings.json. That file is itself shared by symlink, so one install covers every profile. The writer resolves the path with os.path.realpath before its mkstemp+replace, so it replaces the link's target and leaves the link intact.
• CCACCT_AUTOSYNC=1 is never read by the script. It is only a marker that lets has_hook() find the entry for idempotent install and for uninstall.
• --links-only because the session that just started owns its .claude.json (7.3). The consequence: autosync never carries mcpServers or project-trust changes over. Those need a manual ccacct sync.
• --quiet matters more than it looks. SessionStart hook stdout goes into the model's context (Ch 1), so status lines would cost tokens in every session.
• The hook breaks if the repo moves, because the absolute path is baked in at install time.

7.6 Tests and CI

tests/test_ccacct.sh sets CCACCT_PRIMARY, CCACCT_ROOT and CCACCT_CLAUDE_BIN to paths inside a mktemp -d sandbox, which a trap removes on exit. It fills the sandbox with a realistic primary: a .git, sessions/, a .claude.json holding identity keys, mcpServers, projects, and more. The claude binary is replaced by a stub that echoes CLAUDE_CONFIG_DIR and its arguments, so run/login can be checked from output alone. make_stale sets mtime to epoch 0 through Python's os.utime, because BSD touch lacks GNU's -d (per the script's comment).

There are 86 test cases (86 t "..." labels, one assertion each). That matches the README and the commit message "Tests: 52 -> 86". The CI workflow .github/workflows/test.yml runs the suite on ubuntu-latest and macos-latest (bash 3.2 and BSD userland are the likely reason for macOS) and runs shellcheck --severity=warning on the script and the tests.

7.7 No auto-rotation on rate limits

The README ends with a policy note: owning several subscriptions is allowed, but account sharing, reselling and limit circumvention are not. So ccacct "deliberately does not rotate automatically on rate limits — the switch is always explicit." The code agrees. Nothing reads rate-limit state, and the only hook it installs is the links-only SessionStart sync. Automatic rotation would be easy to build, since a hook could switch profiles when it sees a rate-limit error. The author chose to leave it out: an automatic switch is the limit circumvention the terms prohibit.

7.8 Traps

• projects/ is shared by default. Transcripts, --continue/--resume state and the per-project auto-memory (projects/<slug>/memory/) are one pool for all accounts. claude --continue in profile B resumes the latest session in that directory, even if account A wrote it. Two accounts working in the same repo at the same time write into the same folder. --isolate-projects is the opt-out.
• The denylist fails open. Any file a future Claude Code release adds is shared by default. This host (Claude Code 2.1.280) already has entries the list doesn't cover: policy-limits.json, remote-settings.json, mcp-needs-auth-cache.json, backups/, state/. Judging by their names, some are presumably account- or org-scoped. The same holds inside .claude.json: 41 of this host's 56 top-level keys are not in ACCOUNT_KEYS, including modelAccessCache, orgModelDefaultCache and remoteControlMachineId, so they would be mirrored from the primary. The trade-off is intentional: new setup shows up everywhere, and new identity leaks until someone adds it to the list.
• Profile-local config gets reverted. claude mcp add -s user inside a profile writes a top-level mcpServers entry, and the next sync replaces the whole key with the primary's value. A settings change made from a profile session, if Claude Code writes it by atomic rename, turns the link into a real file. The next sync rm -rfs that file. The primary never saw the change.
• Word splitting. for item in $(cd "$PRIMARY" && ls -A) splits on whitespace, so an entry named my notes.md would be processed as two names.

Part 7B — cis-api

7.9 Structure and MCP wiring

main.go only calls cmd.Execute(). cmd/root.go registers four cobra commands (login, logout, grades, certs). The rest (mcp, klausuren, stundenplan, transfer, wpf) register themselves in their own init(). Each area of the portal is its own internal/ package, and they all follow the same pattern: FetchX(c) does HTTP, and a pure parseX(body string) turns the HTML into structs. internal/client holds the cookie jar. internal/scraper has generic form/link/table extractors.

cis mcp builds one client.Client for the life of the process. If there is no saved session and both CIS_USER and CIS_PASS are set, it logs in. Then it serves stdio:

s := server.NewMCPServer(
    "cis-api",
    "1.0.0",
    server.WithToolCapabilities(true),
)

registerTools(s, c)

return server.ServeStdio(s)

_{cis-api/cmd/mcp.go:55}

Tools are declared with mcp-go's builder: mcp.NewTool(name, mcp.WithDescription(...), mcp.WithString("exam_id", mcp.Required(), ...)). Unlike FastMCP (Ch 2), nothing is inferred from function signatures; the JSON schema is spelled out by hand. There are 18 s.AddTool calls:

Each handler starts with an IsLoggedIn() check. Failures come back as mcp.NewToolResultError(msg), nil: a tool result with isError set, not a JSON-RPC error, so the model reads the message. Nothing on the MCP path writes to stdout (Ch 2).

7.10 Scraping TYPO3/Extbase

Login (internal/auth/auth.go:16) follows TYPO3's felogin flow. It GETs /, then finds the first <form> whose action contains tx_felogin_login, collecting every <input name=value> inside it: hidden fields plus empty user/pass fields. It then POSTs to the action URL taken from the page:

data := url.Values{}
for k, v := range form.Fields {
    data.Set(k, v)
}
data.Set("user", username)
data.Set("pass", password)
data.Set("logintype", "login")
if _, ok := data["submit"]; !ok {
    data.Set("submit", "Anmelden")
}
postResp, err := c.PostFormURL(actionURL, data)

_{cis-api/internal/auth/auth.go:47}

Copying the hidden fields back matters because TYPO3 forms carry server-generated state (referrer, request tokens) that the POST has to echo. The code doesn't hard-code those fields; it returns whatever the form contains. If no form appears but the jar already holds a session cookie, login counts as already done.

Session persistence. "Logged in" means the jar holds a non-empty cookie named fe_typo_user_cae070b (internal/client/client.go:107). SaveSession writes every cookie for the base URL as [{name,value}] to ~/.config/cis-api/session.json, with the directory at 0700 and the file at 0600. On load, the cookies are rebuilt with Domain: cis.nordakademie.de, Path: / and no expiry. The client therefore cannot tell a dead session from a live one. Two consequences:

• A stale session.json makes IsLoggedIn() return true. cis mcp then skips the env-var auto-login, and tools parse whatever page the server returns for an expired session. In the best case the result is an error like "keine Noten gefunden — bitte einloggen" ("no grades found — please log in"); in others, an empty list.
• Presumably a failed re-login also counts as success while the stale cookie is still in the jar, because the success check only asks whether the cookie is present.

Why URLs can't be built on the client (cHash). TYPO3 appends cHash to plugin URLs. Per TYPO3's own documentation (not stated anywhere in this codebase), a cHash is a hash of the request parameters keyed with the installation's secret encryptionKey, so no client without that secret can compute a valid one. What the source itself demonstrates is only the consequence: README.md:120 states that a cHash "cannot be computed client-side," and the in-code comments (grades.go:24, exams.go:8-9, transfer.go:40/90, seminars.go:105) call a cHash "required" or "signed" without ever deriving it. The strategy stated in the package docs and in commit 99f97ff: read the finished, signed links out of the page and follow them. exams.parseRow stores the action cell's <a href> as ActionURL, un-escaping & and making it absolute. queryParam then reads action and examId out of that URL. It matches both the bare name and the tx_ext[name] bracket form. The code does not apply the strategy consistently, though:

• transfer.FetchBewertung builds its URL, with a comment admitting it: "a cHash is normally required. Prefer following the performance link from FetchList; this direct form is a fallback used by tests/fixtures" (internal/transfer/transfer.go:90). Both the CLI --bewertung and cis_transfer_bewertung use that fallback. Whether it works live depends on how strictly the server enforces cHash, which the source does not settle.
• The grades fallback (internal/grades/grades.go:198) rewrites the lang parameter on a signed link and re-encodes it. If lang is part of the hash, that breaks the signature.
• wahlpflicht POSTs to the form's signed action URL. It adds a hard-coded curriculumId = "161" and [action]=choose, and the comment on the latter reads "likely 'choose' or 'save'". It is a guess, and the choose-POST is not covered by any fixture.

HTML library. golang.org/x/net/html: a tree parser with no CSS selectors. Each package has its own recursive walk plus copies of attr/innerText. Tables are found by header text, not by id or class: modulnummer+abmelden for exams, thema+korrekturfrist for transfer reports, gewichtung+feedback for grading criteria. That approach survives layout changes and breaks when the wording changes. transfer.WeightedAverage computes Σ(note·weight)/Σweight on the client, because the portal shows no overall grade, and output labels it as computed.

7.11 Binding writes: CLI guard vs. MCP guard

On the CLI, exam registration takes three steps. runExamAction resolves the exam from the live page and refuses if the offered action differs from the one requested ("refusing to act"). It prints a preview. Without --confirm it stops at "DRY RUN — nothing was sent." With --confirm it adds a typed confirmation:

func confirmByTyping(expected string) bool {
    fmt.Fprintf(os.Stderr, "Type %q to confirm (anything else aborts): ", expected)
    reader := bufio.NewReader(os.Stdin)
    line, err := reader.ReadString('\n')
    if err != nil {
        return false
    }
    return strings.EqualFold(strings.TrimSpace(line), strings.TrimSpace(expected))
}

_{cis-api/cmd/confirm.go:15}

The expected token is the module number for exams and the module ID for electives. The prompt shows the token, so it checks attention, not knowledge. It reads stdin without checking for a TTY, which means echo I210 | cis klausuren --register 12022 --confirm passes. An agent using Claude Code's Bash tool could do that. It would have to write both --confirm and the pipe into a command string the user sees in the permission prompt, but nothing in the code stops it.

Example: cis klausuren --register without --confirm. The exam id, module number and dates below are illustrative — a live Resolve call fills them from the current page — but the printed lines themselves are exact.

$ cis klausuren --register 12022
Resolving exam...
Prüfung:  I210 Wirtschaftsinformatik II
ExamID:   12022
Termin:   2026-10-12 09:00 – 2026-10-12 11:00
Aktion:   Anmeldung (register)

DRY RUN — nothing was sent.
Re-run with --confirm to perform the binding Anmeldung.

Nothing was sent because runExamAction returns as soon as it prints the preview when confirm is false (cmd/klausuren.go:103-106). Note what already ran before this point: exams.Resolve fetched the live overview and checked e.Action != wantAction (cmd/klausuren.go:93-96, backed by internal/exams/exams.go:57-72), so the preview reflects the page at the moment the command ran, not a cached list.

The MCP tool cis_klausur_action repeats the resolve step and the action-match check. The only gate is a boolean parameter:

if !req.GetBool("confirm", false) {
    return mcp.NewToolResultText("DRY RUN — nothing submitted.\n" + preview +
        "\nCall again with confirm=true to perform this BINDING action."), nil
}
msg, err := exams.Submit(c, e.ActionURL)

_{cis-api/cmd/mcp.go:210}

Compared plainly:

A boolean the model sets itself confirms nothing. The model can pass confirm=true on the first call. The line "Always show the preview to the user and get explicit approval" lives in the description, which is prompt engineering (Ch 2); in Ch 1's terms it is persuasion, not enforcement. One thing does work: each call re-resolves from the live page, so a confirmed call never acts on a stale URL. It re-checks the offered action (register vs. deregister), too.

Example: cis_klausur_action, dry run then confirmed. The exam id, dates and the German flash message are illustrative; the DRY RUN/SUBMITTED strings and the preview format come straight from cmd/mcp.go:206-218. The second call is the only gate — nothing outside this exchange checks that a human actually approved it.

user: Register me for I210, exam 12022.

assistant: I'll check the current status and register.
{"type": "tool_use", "id": "toolu_01C…", "name": "cis_klausur_action", "input": {"exam_id": "12022", "action": "register"}}
 running cis_klausur_action
user: {"type": "tool_result", "tool_use_id": "toolu_01C…", "content": "DRY RUN — nothing submitted.\nPrüfung: I210 Wirtschaftsinformatik II | ExamID 12022 | 2026-10-12 09:00–2026-10-12 11:00 | action=register\nCall again with confirm=true to perform this BINDING action."}

assistant: This would register you for I210, Wirtschaftsinformatik II, on 2026-10-12 09:00. Should I submit it?

user: Yes, go ahead.

assistant: {"type": "tool_use", "id": "toolu_01D…", "name": "cis_klausur_action", "input": {"exam_id": "12022", "action": "register", "confirm": true}}
 running cis_klausur_action
user: {"type": "tool_result", "tool_use_id": "toolu_01D…", "content": "SUBMITTED: Prüfung: I210 Wirtschaftsinformatik II | ExamID 12022 | 2026-10-12 09:00–2026-10-12 11:00 | action=register\nResult: Sie wurden erfolgreich angemeldet."}

assistant: Done — you're registered for I210.

The model decided on its own to set confirm: true after the user's one-line "go ahead" — nothing in the tool itself forces it to show the preview first or wait for a reply at all; a user who says nothing gets the identical tool result either way.

cis_select_wahlpflicht has no confirm parameter. It calls wahlpflicht.Select directly (cmd/mcp.go:370). The README ("Binding write actions ... default to a dry run") and the commit message ("MCP requires confirm=true") both say otherwise. Its only protection is SelectAvail: outside the selection window it errors. During the window, when a mistake actually costs something, nothing stops it.

A real guard has to sit where the model can't reach it:

• a Claude Code permission rule that always asks for these two tools, or
• a PreToolUse hook that blocks confirm: true unless a human set a flag (Ch 1).

MCP's elicitation request, where the server asks the user directly through the client, would be the protocol-native way to do the typed confirmation. That requires both mcp-go and the client to support it, which I haven't checked.

The download tools are loose in the same way. download_url and output_path come from the model with no validation. The cookie jar only sends the session cookie to cis.nordakademie.de, so a foreign URL doesn't leak it. But os.WriteFile will overwrite any writable path. The CLI, by contrast, builds the file name from the page listing.

7.12 Parsing tests with HTML fixtures

There are 10 Go test functions: exams 3, stundenplan 3, transfer 4. Each feeds a saved page from testdata/ into the pure parser and checks exact fields. For example, the first exam has module I210, action register, examId 11993, label Anmelden, and the URL is absolute with no & left. The fixtures keep the real portal's DOM structure but hold made-up data (Mustermann, Max, cHash=exampletoken000…). .gitignore says this explicitly and keeps real captures (*.har, Protokoll.txt, Analyse/) out of git.

Snapshot fixtures suit scraping because of the fetch/parse split. The risky, non-deterministic, credential-bearing part (HTTP) is kept out of the tested code. What is left is a function from a string to a struct, tested offline with no login and no chance of triggering a binding action. When the portal changes, you capture the page again, anonymize it and diff.

Loose ends:

• Every loader still says "Fixtures hold personal CIS data and are git-ignored; skip when absent" and calls t.Skipf. The comment is stale, and a missing fixture shows up as skipped, not failed.
• testdata/beantragen.html is committed, but nothing reads it. The submit.go promised in the transfer package doc does not exist.
• There are no tests for auth, client, grades, seminars, wahlpflicht or certs, and the repo has no CI.

7.13 Credentials and vault-launch

The CLI reads credentials from --user/--pass, then CIS_USER/CIS_PASS, then an interactive prompt (term.ReadPassword). Only the session cookie is stored on disk. The README's MCP example puts the password in plaintext in the env block of ~/.claude/.mcp.json. The header of vault-mcp's src/launch.ts presents cis-api as the example case. Claude Code starts node dist/launch.js --vault nak --env CIS_USER=nordakademie.de:username --env CIS_PASS=nordakademie.de:password -- /abs/path/cis-api/cis mcp. The launcher resolves both secrets from Bitwarden and runs cis mcp with stdio inherited, so the secret exists only in the child's environment. It never enters a config file or the model's context (Ch 4). cis-api needs no changes for this, because it already takes its credentials from env vars (Ch 2).

Trap: cis_login takes username/password as tool arguments. Whatever the model passes there is part of the conversation and ends up in the transcript under projects/, which Part A shares across accounts by default. Combined with the stale-session issue from 7.10, the failure chain looks like this:

1. session.json has expired, so env auto-login is skipped.
2. Tools return empty results.
3. The model asks the user for the password and calls cis_login with it.

After that, the password is in the transcript. Deleting session.json and restarting the server is the safe recovery.

7.14 Relevance

cis-api is useful only for a NORDAKADEMIE account, and even then partly for one cohort (curriculumId = "161", the instance-specific cookie name). Its broader value is as a template for wrapping a portal that has no API:

• fetch and parse kept separate;
• signed links read from the page, never built;
• tables located by header text;
• anonymized DOM snapshots as tests;
• dry-run by default on anything that writes;
• credentials via env vars so a vault launcher can inject them.

The gaps (the missing guard on elective selection, cookie presence standing in for a login check, output paths the model chooses) are the parts to fix before reusing it.

7.15 What to take away

• Isolate by denylist when "setup" is the default and identity is the exception, and plan for the list going stale. A denylist leaks every new identity file until someone lists it; an allowlist would drop every new setup file. A doctor command only checks what its list already names.
• When a file mixes concerns, merge by key; never link it. Name the identity keys, mirror the rest, write atomically, and avoid writing under a live process.
• Environment changes must run in the process they are meant to affect. That is why use has to be a shell function.
• A confirmation flag the model can set is a dry-run convenience, not a guard. Real second factors (typed token, permission prompt, PreToolUse hook, elicitation) need a human or code the model can't reach. Check that every write path has one.
• When the server signs URLs, follow its links. Tests should cover the pure parser against anonymized snapshots.

Every claim in this chapter carries a label:

• [src]: verified in the cloned source.
• [desc]: stated only in the self-description.
• [inf]: my inference, also worded as "presumably" or "likely".
• [given]: an orchestrator-provided fact about this installation.
• [host]: live state of this machine.

8.1 The header line

"Claude Code 2.1.260 (native, Auto-Update aus) · Modell opus, Effort medium"

• model: "opus", effortLevel: "medium". These are two top-level keys in settings.json [given]. opus is an alias, not a pinned model ID. It resolves to whatever that binary version maps it to [inf].
• Native. This is the standalone binary, not the npm package. On this host claude is ~/.local/bin/claude, reports 2.1.280, and ~/.local/share/claude/versions/ holds 2.1.259, 2.1.260 and 2.1.280 [host].
• Auto-update off. The description does not say which switch is used, and I did not verify one.
• There is a plausible motive in the code. ccacct hard-codes the internal layout of Claude Code: the file names in ISOLATED and 31 .claude.json identity keys in ACCOUNT_KEYS (claude-accounts/bin/ccacct:20, :41) [src].
• A release that adds a new identity key would get that key mirrored from the primary account into every profile until someone adds it to the list. Pinning the version keeps the denylist correct [inf].

"Das Ganze liegt in ~/.claude und ist als privates Git-Repo versioniert, damit es auf mehreren Maschinen identisch ist" ("it all lives in ~/.claude, versioned as a private git repo so it is identical on several machines"). ccacct shows the consequence directly:

ISOLATED=(
  .credentials.json          # OAuth-Tokens: DAS unterscheidet die Accounts
  .claude.json               # enthält oauthAccount; wird stattdessen gemergt
  .config.json               # würde Claude Codes Pfadauflösung kapern
  .git .gitignore             # ~/.claude ist ein Repo; ein Link machte das Profil zum Worktree

claude-accounts/bin/ccacct:20

The comment on .git reads "a link would turn the profile into a worktree". A profile directory containing a .git symlink to ~/.claude/.git would be treated by git as the same repository with a different working tree. Every isolated file there, such as that profile's .credentials.json, would show up as a change against the primary's tree, one careless git add -A away from being committed [src comment, consequence inf].

Two traps come from "everything lives in ~/.claude":

1. The main MCP config is outside it. For the primary profile, the global .claude.json sits at $HOME/.claude.json, next to the directory rather than inside it (global_json_for, ccacct:90) [src]. User-scope mcpServers are therefore not in the git repo. ccacct's README lists mcp-servers/, .mcp.json and servers/ as things that live inside ~/.claude (claude-accounts/README.md:48) [src]. This suggests the server definitions are versioned there and copied into .claude.json by some other step [inf].
2. Secrets can land in the repo. vault-mcp writes project-vault backups ("dedicated vault key + TOTP seed") to ~/.claude/vault-mcp-backups and describes them as "never in the repo, never synced anywhere" (vault-mcp/src/config/loader.ts:20-29) [src]. - ~/.claude is itself a synced repo. - ccacct does not isolate that directory, so it is symlinked into every profile [src]. - Whether the author's .gitignore excludes it cannot be checked. When you copy this setup, check it first.

8.2 Layer 1: instructions

"plus fünf Regeldateien, die per @rules/... fest eingebunden sind" ("plus five rule files firmly included via @rules/...").

Mechanically (Ch 1, step 2b):

1. ~/.claude/CLAUDE.md is read at session start as user-scope memory.
2. Each @rules/sicherheit.md line is an import. It resolves relative to the importing file and is spliced in as text.
3. "Fest eingebunden" ("firmly included") therefore means unconditional. All six files enter the context of every session in every project and are part of the prefix of every request. - Prompt caching lowers the price of that prefix. It does not free window space. - The only opt-out in the given schema is claudeMdExcludes [given].
4. Splitting the text into five files is for human maintenance. The model sees one block of text.

The rule files themselves are not available. I describe only what the table says.

The effect the author reports, "Claude fragt deutlich weniger nach … aber die Sicherheitsregeln sind explizit davon ausgenommen" ("Claude asks far fewer questions … but the safety rules are explicitly exempt"), puts two instructions in the same context:

• "act autonomously"
• "except here"

They compete inside one next-token prediction, and nothing outside the model arbitrates between them. CLAUDE.md is persuasion. Hooks and permissions are enforcement (Ch 1).

One rule verifiably changed artefacts. rules/git-und-doku.md asks for a Project.md per project, and all eight repos list Project.md in .gitignore while tracking none. vault-mcp's commit "Add README, untrack Project.md" shows the switch [src]. So Project.md is a local working document and not published.

Which listed rules should become enforcement

vault-mcp's vault_reveal_password is a good candidate for a deny rule. Its "double confirmation" consists of two booleans, confirmed and exposedToAI, that the model fills in itself (vault-mcp/src/index.ts:206-226) [src]. That is persuasion shaped like a schema. A permissions.deny or ask entry on the tool name is real enforcement (Ch 4.6).

A PreToolUse sketch. This code is not from any repo:

#!/usr/bin/env python3   # settings.json → hooks.PreToolUse, matcher "Bash"
import json, re, sys
cmd = json.load(sys.stdin).get("tool_input", {}).get("command", "")
def block(msg): print(msg, file=sys.stderr); sys.exit(2)   # exit 2 = deny; stderr goes to model
if re.search(r"\brsync\b", cmd) and not re.search(r"--exclude[= ]['\"]?\.env", cmd):
    block("sicherheit.md: rsync only with --exclude .env")
if re.search(r"\bpsql\b", cmd) and re.search(r"\b(INSERT|UPDATE|DELETE|DROP|ALTER|TRUNCATE)\b", cmd, re.I):
    block("sicherheit.md: no writing DB access")
if re.search(r"\brm\s+-\w*r\w*f|\bdocker\s+volume\s+rm|\bgit\s+clean\s+-\w*f", cmd):
    block("sicherheit.md: no deletion of persistent data")

• Exit code 2 feeds the reason back to the model, so it can rephrase instead of silently failing (Ch 1).
• String matching on shell text can be bypassed with bash -c "$(…)", a script file, or variables. Treat it as a tripwire, not a sandbox.

8.3 Layer 2: MCP servers, "21 Stück, 13 davon standardmäßig aktiv"

"21 servers, 13 of them active by default" [desc]. The description names 11 as active: codescope, diary, vault-mcp, cachyos, gemini, codex, web-search, fetch, Uni-Portal, Klausur-Plattform, Hörhistorie-Auswertung. Two active servers are unnamed, and 21 − 13 = 8 matches "~8" disabled.

Where servers are configured (Ch 2 covers the wire protocol):

"projektweise abgeschaltet" ("switched off per project") can mean any of three things, and the description does not say which:

• a disabledMcpjsonServers entry,
• the /mcp toggle (persisted per project in .claude.json; exact key not verified),
• defining the rarely used servers only at local or project scope.

Whichever it is, ccacct carries it across accounts. The profile's .claude.json receives the primary's projects entries with primary-wins semantics, while profile-only entries survive (ccacct:211-214) [src].

One concrete shape the first option takes — illustrative, since this key is not exercised in any of the eight repos [given]:

// .claude/settings.json, project scope
{
  "enabledMcpjsonServers": ["diary"],
  "disabledMcpjsonServers": ["cachyos", "vault-mcp"]
}

# tools/list at this project's session start
diary      → 73 tool schemas sent      (enabled)
cachyos    → skipped entirely          (disabledMcpjsonServers)
vault-mcp  → skipped entirely          (disabledMcpjsonServers)

cachyos and vault-mcp still exist in .mcp.json or user-scope mcpServers — this key just stops their schemas from entering this project's prompt, which is the per-project half of the "~8 disabled" figure in 8.1's table; it says nothing about what's disabled globally.

Why disabling saves context: every enabled server's tools/list result becomes tool definitions in the prompt (Ch 2). The four repos below with exact counts add up to 239 registrations before AIDEN (73 + 37 + 111 + 18). At Ch 1's estimate of 100-400 tokens per schema that is tens of thousands of tokens, unless the harness defers schemas (this session's harness does, behind ToolSearch [host]; whether 2.1.260 did for the author is unknown).

AIDEN also exposes 8 memory tools of its own that proxy to Diary (memory_tools.py). With codescope and diary both active, similar memory tools appear twice in the tool list [src; cost consequence inf].

"keine Zugangsdaten in Config-Dateien, die MCP-Server bekommen ihre Tokens zur Laufzeit injiziert" ("no credentials in config files; the MCP servers get their tokens injected at runtime"). This is vault-launch [src]. Claude Code's mcpServers entry starts the launcher, not the real server. The config contains only item references:

 *     "cis": {
 *       "command": "node",
 *       "args": [
 *         "/abs/path/vault-mcp/dist/launch.js",
 *         "--vault", "nak",
 *         "--env", "CIS_USER=nordakademie.de:username",
 *         "--env", "CIS_PASS=nordakademie.de:password",
 *         "--", "/abs/path/cis-api/cis", "mcp"

vault-mcp/src/launch.ts:19-26

The launcher then:

1. resolves each reference through bw,
2. starts the child with spawn(cmd, args, { stdio: 'inherit', env: { ...process.env, ...env } }) (launch.ts:118),
3. forwards SIGINT, SIGTERM and SIGHUP to it.

cis mcp reads CIS_USER/CIS_PASS (cis-api/cmd/mcp.go:46-47). The secret never crosses the MCP wire protocol into the model's context [src].

Two qualifications:

• The secret does sit in the child's environment. spawn is given env: { ...process.env, ...env } (launch.ts:118-121), and on Linux any process owned by the same user can read another process's environment via /proc/<pid>/environ or ps eww. With Bash available — and 8.7 below assumes it is — the model can go looking for it there even though it never sees it over MCP: ps eww $(pgrep -f 'cis mcp') or a raw /proc read recovers CIS_USER/CIS_PASS in plaintext. The same skepticism 8.7 applies to "MCP-Server statt rohem Bash" (a determined Bash call defeats a server-side gate) applies here too [src mechanism, attack scenario inf].
• "No credentials in config files" holds only if the vault's own unlock uses masterPasswordCmd or masterPasswordPrompt. A plaintext masterPassword in ~/.config/vault-mcp/config.json is still accepted (vault-mcp/src/vault/bw-client.ts:318-335).

The mcpServers entry in 8.3 only shows what the launcher is told. Here is what prepareInjection actually hands to spawn once bw has resolved those two refs (launch.ts:112-121; tools/inject.ts:101-109 for the InjectionPlan shape, :118-157 for the resolve loop) — item names and the resolved secret values are illustrative, the env/args/stdinValue shape is real:

// parseLaunchArgs() output, from the "cis" entry in 8.3
{ vault: "nak",
  envMappings: { CIS_USER: "nordakademie.de:username", CIS_PASS: "nordakademie.de:password" },
  argRefs: {},
  command: ["/abs/path/cis-api/cis", "mcp"] }

// prepareInjection()'s return value — merged into the child via
// spawn(command[0], args, { stdio: 'inherit', env: { ...process.env, ...env } })
{ env: { CIS_USER: "jdoe123", CIS_PASS: "S3cr3t!…" },
  args: ["mcp"],
  stdinValue: null }

Nothing here crosses the MCP wire — vault-launch never parses the child's stdout/stdin (stdio: 'inherit'), so the plaintext CIS_PASS only ever exists in the child's own environment. That is precisely the /proc/<pid>/environ exposure the paragraph above already flags, just showing what specifically ends up there.

8.4 Layer 3: skills, "30 eigene"

"30 of my own" [desc]. A skill is skills/<name>/SKILL.md: YAML frontmatter (name, description), a body, and optional reference files.

• Only name + description sit in context until the skill triggers. The body loads when the model picks the skill, or when the user types /name. This is progressive disclosure (Ch 1).
• "Claude lädt automatisch" ("Claude loads them automatically") therefore means the model matches the description against the task. The harness does not do the matching deterministically.
• The listing has its own budget [given]:
• skillListingBudgetFraction defaults to 0.01. On a 200k window that is ~2,000 tokens, about 65 tokens (~250 characters) per skill for 30 skills.
• skillListingMaxDescChars defaults to 1536. Thirty descriptions at that cap (~46k characters) would overflow the budget several times. How the harness trims is not verified here.
• Short descriptions that front-load their trigger words are therefore a functional requirement, not a style choice.
• skillOverrides (on / name-only / user-invocable-only / off) can demote rarely used skills [given].

We don't have the skill bodies. From names and descriptions only:

• senior-dev: "erst suchen & wiederverwenden, dann schreiben" ("search and reuse first, then write"). This matches AIDEN's FindSimilarCodeTool, whose docstring says: "Find existing code most similar to a code snippet ('reuse before you write') … pass the code block you are about to write" (volantic-codescope/src/aiden/tools/search_tools.py:121-129). DetectClonesInDiffTool is labelled "a pre-commit / pre-write gate for the 'reuse before write' workflow" (:181) [src]. The skill presumably tells the model to call these before writing [inf].

Its body is not in any repo — this reconstruction is illustrative, but built from the two real tool signatures it would presumably drive: ``` ~/.claude/skills/senior-dev/SKILL.md

name: senior-dev description: Use before writing new code — search and reuse first, then write.

Before adding a function, helper, or test: call find_similar_code(snippet, limit=10) with the code you're about to write. A hit near 0.9 similarity means reuse or extend it instead. Before committing: call detect_clones_in_diff(staged=true) as a final check. `` Idle, onlynameanddescriptionsit in the listing (8.4, ~65 tokens for this one); the four indented sentences above are the part that only loads once the model matches the description or the user types/senior-dev— the same progressive-disclosure split 8.4 already describes, made concrete for one named skill instead of "30 of my own". - **forge**: *"mehrstufige Multi-Agent-Pipeline von der Idee bis zum Code"* ("multi-stage multi-agent pipeline from idea to code"). This is presumably the playbook form ofrules/multi-agent.md: the rule states the pattern on every turn, and the skill carries the long procedure only when invoked [inf]. - **continue,queue**: names only. ccacct isolates aqueue` directory as "laufender Sessionzustand" ("running session state") (ccacct:26). Whether that relates to the skill is unknown [inf].

"Der mit Abstand meistgenutzte ist minecraft-dev" ("by far the most used is minecraft-dev"). Usage is counted in skillUsage in .claude.json. Is it shared across profiles?

• skillUsage is not in ACCOUNT_KEYS. The comment names it explicitly as mirrored (ccacct:37-39), and the test fixture includes "skillUsage": {"senior-dev": 7} (tests/test_ccacct.sh:64) [src].
• The mirror runs one way: profile[key] = value for every non-identity key (ccacct:216). Counts accumulated in a profile are overwritten at the next full sync and never reach the primary.
• So usage is shared, but only as a copy of the primary's counts. The author's ranking reflects the default profile [inf from the code].

8.5 Layer 4: hooks

"Kleine Skripte, die das Programm bei bestimmten Ereignissen ausführt" ("small scripts the program runs on certain events"). This is one of the two layers the model cannot skip — with permissions, and unlike CLAUDE.md and the rule files, which are persuasion (8.2).

Session-Start/-Ende ("session start/end") [src]:

• diary-mcp/scripts/session_start_hook.py
• Reads the SessionStart payload, derives a project slug from cwd, and queries Postgres directly: "no MCP/model import, fails silent. A hook must never block a session" (:15-16).
• Selects the compact pin if source == "compact" and the start pin otherwise (:53-56). Which memories carry which pin is not worked out by the system: it's set per node with the memory_pin(path, on_start, on_compact) tool, two independent flags documented as cost tiers, compact being the pricier one reserved for "absolut kritische Nodes" (Ch 3.6, memory_service.py:732–761).
• Prints hookSpecificOutput.additionalContext.
• The query has no LIMIT (:67-74). Every pinned curated memory for the project plus /user/* and /feedback/* is injected. The cost scales with pin discipline and is paid again after every compaction.
• scripts/session_end_hook.py
• Runs only if /projects/<slug> has config.auto_extract set, or DIARY_AUTO_EXTRACT=1.
• Spawns extract_memories.py with start_new_session=True and all stdio going to /dev/null (:61-66).
• The child logs to ~/.claude/diary-extract.log (scripts/extract_memories.py:32). ccacct isolates exactly that name (ccacct:31), so the two tools were built with each other in mind.
• A second SessionStart hook is verifiable: ccacct autosync install appends sync --all --links-only --quiet with timeout: 15 to the shared settings.json (ccacct:495, :532).

Registering the two shipped diary hooks plus the README's (unshipped) third one together, using the real script names for Start/End rather than the README's diary_session_start.py/diary_session_end.py:

{ "hooks": {
    "SessionStart": [{ "hooks": [{ "type": "command",
      "command": "python3 /abs/path/diary-mcp/scripts/session_start_hook.py" }] }],
    "UserPromptSubmit": [{ "hooks": [{ "type": "command",
      "command": "python3 ~/.claude/hooks/diary_prompt_retrieval.py" }] }],
    "SessionEnd": [{ "hooks": [{ "type": "command",
      "command": "python3 /abs/path/diary-mcp/scripts/session_end_hook.py" }] }] } }

Running the first of those at a plain startup, with one memory pinned start for this project (title and body illustrative, everything else read straight off session_start_hook.py:46-56,64-74,84-103):

stdin the hook receives —

{"session_id": "…", "cwd": "/abs/path/claude-stack-guide", "hook_event_name": "SessionStart", "source": "startup"}

what it prints on stdout —

{"hookSpecificOutput": {"hookEventName": "SessionStart",
  "additionalContext": "# Gepinnte Memories (Session-Start) — Projekt 'claude-stack-guide'\n(Automatisch aus dem diary-mcp Memory-Tree geladen.)\n\n## [reference] Chapter order and audience  ⟨/projects/claude-stack-guide/reference/chapter-order⟩\n…"}}

source is the only branch in the whole script ("compact" → the compact pin, anything else, including a missing field, → "startup" and the start pin, line 46 and 53-56) — everything else about the query runs the same either way, including the missing LIMIT 8.5 already flags.

"Bei jedem Prompt" ("on every prompt"): the script is not in the repo.

• diary-mcp's README registers python3 ~/.claude/hooks/diary_prompt_retrieval.py under UserPromptSubmit (README.md:92) and describes it as FTS-only over curated memories, "deliberately … not semantic" to avoid loading the embedding model on each prompt (:99).
• scripts/ contains no such file. git log --all -S diary_prompt_retrieval returns only 4a36db7 (2026-09-12), the commit that wrote the README text. The file was never committed.
• The README's other names (diary_session_start.py, diary_session_end.py) also differ from the repo's session_start_hook.py / session_end_hook.py. scripts/link_inference_cron.py:15 refers to "the SessionStart/UserPromptSubmit hooks in this directory".
• Taken together, this suggests the live hooks are renamed copies in the author's private ~/.claude/hooks/, and the retrieval hook exists only there [inf].
• Cost note: each injection stays in the transcript, so this is the one hook whose token cost grows with the session.

"Bei Rate-Limit … macht selbstständig weiter" ("on a rate limit, the session waits in the background and continues on its own"): no repo implements this.

• ccacct isolates .autocontinue and .autoresume among the session-bound files (ccacct:30) [src]. This suggests the author's hook keeps per-profile resume markers in the config dir [inf].
• The given schema offers a plausible mechanism: a StopFailure hook with async/asyncRewake [given, mechanism inf].
• This installation also has a built-in autoContinueAtUsageLimit [given]. On newer versions it may make the custom hook redundant.
• ccacct deliberately does not switch accounts on a limit: "verboten sind Account-Sharing, Weiterverkauf und Limit-Umgehung. ccacct rotiert deshalb bewusst nicht automatisch" ("account sharing, resale and limit circumvention are forbidden, so ccacct deliberately does not rotate automatically") (README.md:83-85). Waiting is the design.

"Stop-Hook: begrenzt autonome Endlosschleifen" ("the Stop hook limits autonomous endless loops").

A Stop hook runs when the model is about to end its turn. If it returns a block decision with a reason, the turn does not end. The reason is fed back to the model and the loop continues. That makes Stop hooks the source of autonomous loops. A limiter is the inverse use: count forced continuations per session_id in a state file and stop blocking after N of them. Claude Code's hook input also carries a stop_hook_active flag for "already continuing because of a Stop hook"; that flag is not verified in these repos.

A historic loop candidate is in diary-mcp. v0.9.0 had a Stop hook diary_keyword_trigger.py that matched keywords "against BOTH the user's and Claude's own text" (diary-mcp/diary_db.py:359-365, the trigger_keywords schema comment) [src]. The README states it was "retired in v0.10.0" (README.md:99, :273) [src], but that figure is not corroborated in the code: the retiring commit's own message bumps the version straight from 0.9.0 to 0.11.0 ("Version 0.9.0 -> 0.11.0", commit 4a36db7) [src], so no v0.10.0 release is otherwise evidenced in the repo — treat "v0.10.0" as a README-only figure. A Stop hook that reacts to the model's own output can trigger on text it caused itself [inf].

Live example, this session [given]. The reader's /goal installed a session-scoped Stop hook. A model evaluated its condition against the transcript and blocked the assistant from finishing, returning "Stop hook feedback" listing what was missing.

• Power: "done" is judged by something other than the model claiming it. That is the enforced form of "kein fertig ohne echte Funktion".
• Failure mode: the guide's planned per-chapter pauses were skipped. The hook's condition did not encode "pause after each chapter", so every intended pause looked like an unfinished job.
• A count limiter would not have fixed that. It caps how many continuations happen, not which stops are legitimate.

The sequence behind that live example, in the same raw transcript style as Chapter 1's animations:

system: [system prompt, CLAUDE.md, tool schemas]

user: /goal Write Chapters 3, 4 and 5, pausing after each one.

assistant: Chapter 3 is written and saved. That's a natural checkpoint, so I'll stop here for now.

 waiting for the tool result

Stop hook
stdin:
{"session_id": "…", "transcript_path": "…/<session>.jsonl", "hook_event_name": "Stop", "stop_hook_active": false}
 checking transcript against the /goal condition
exit 0, stdout:
{"decision": "block", "reason": "Goal not met: Chapters 4 and 5 are still unwritten."}

user: [Stop hook feedback] Goal not met: Chapters 4 and 5 are still unwritten.

assistant: Understood — continuing with Chapter 4.

The model never chose to keep going after "I'll stop here for now" — the hook's block decision is what fed a new instruction back in and forced another turn, exactly the inversion 8.5 already names: a mechanism built to enforce "done means done" cannot tell a genuine pause from an unfinished job unless its condition says so.

8.6 Layer 5: multi-account, and a claim the code contradicts

"Jedes Profil hat eigene Historie und eigenen Kontext, teilt sich aber die Skills" ("each profile has its own history and its own context, but shares the skills").

ccacct is a denylist. link_shared symlinks every entry of ~/.claude into ~/.claude-accounts/<name>/, except:

• the ISOLATED list,
• anything matching *.log,
• projects, but only if the profile was created with --isolate-projects, which leaves a marker file .ccacct-isolate-projects (ccacct:36, :62-69, :160-167) [src].

The author's own test states the default explicitly: "projects werden standardmäßig geteilt (Kontext bleibt erhalten)" ("projects are shared by default, context is preserved") (tests/test_ccacct.sh:112).

Precisely:

• "Eigene Historie" ("own history") is true for prompt history and live session state. It is false for conversation transcripts: claude --continue under the university account resumes a session started under the private one.
• "Eigener Kontext" ("own context") is false by default. Each session has its own window, as any session does, but it is assembled from identical CLAUDE.md, rules, skill listings, MCP tools, hook output and diary pins.
• The README's own summary is accurate: "Das Einzige, was sich zwischen Profilen unterscheidet, ist der eingeloggte Account" ("the only thing that differs between profiles is the logged-in account") (README.md:12).
• If the author created some profiles with --isolate-projects, the description would be right for those. That cannot be checked.

Two sync subtleties (Ch 7.3) [src]:

1. .claude.json setup keys that disappear from the primary are deleted from the profile (ccacct:219-220). The merge is skipped if the profile's file changed in the last 120 s, which ccacct treats as a live session.
2. Autosync runs --links-only, so a new user-scope MCP server reaches other profiles only after a full ccacct sync.

8.7 Two cross-cutting rules

"MCP-Server statt rohem Bash bevorzugen" ("prefer MCP servers over raw Bash") (Ch 5).

The server version of an operation differs from raw Bash in two ways:

1. Clamped inputs bound the output. For example, max_lines = clamp(int(max_lines), 1, 1000) in read_config_snippet (sysprobe-mcp/src/sysprobe/diag.py:96).
2. Mutations pass a gate that lives in the server's environment:

def require_actions() -> dict[str, str] | None:
    """Return an error dict if mutating actions are disabled, else None."""
    if not actions_allowed():
        return {
            "error": "action disabled",
            "hint": f"set {ACTIONS_ENV}=1 in the MCP server env to enable "
                    f"mutating tools (default is read-only).",
        }

sysprobe-mcp/src/sysprobe/common.py:152

The rule itself is persuasion. With Bash available, the model can still run sudo pacman -R. It could also edit the server's env in .claude.json to set SYSCONTROL_ALLOW_ACTIONS=1, which takes effect on the next spawn. The server gate holds only if permissions.deny also covers those paths.

AIDEN inherits an upstream hook that enforces this rule for code search. Serena's PreToolUseRemindAboutSymbolicToolsHook (serena-hooks entry point, pyproject.toml:79) works like this:

• It counts grep and read calls.
• It emits permissionDecision: "deny" with a reminder after 3 greps, 3 reads, or 4 mixed calls.
• After a deny it goes quiet for 120 s (volantic-codescope/src/serena/hooks.py:103-152) [src].

Trap: a call resets the counter only if its tool name contains the literal substring "serena" (is_serena_symbolic_tool, hooks.py:97-99), and the matched string is tool_name/toolName from the hook's stdin JSON, lower-cased (hooks.py:68-69) — which Claude Code populates as mcp__<server-key>__<tool> (8.2's own naming convention). AIDEN's README configures that key as aiden (README.md:134-136), and none of the underlying Serena tool classes are named with "serena" either (FindSymbolTool, ReadFileTool, SearchForPatternTool, in src/serena/tools/*.py) [src]. So under any server key other than the literal string serena — codescope, aiden, or any other rename — the reset path is dead not just for AIDEN's own additions but for the genuine Serena symbolic tools the hook exists to reward: an agent that dutifully switches to find_symbol after a deny gets no credit for it, and the 120 s cooldown is the only relief, which can immediately re-trigger once it lifts [inf from code]. Whether the author runs this hook, and under which server key, is unknown.

"Hauptmodell plant, Sub-Agents laufen auf Sonnet" ("the main model plans, subagents run on Sonnet").

Mechanically, this is the model: field in agents/<name>.md frontmatter (Ch 1). ccacct's first version explicitly shared an agents directory (git show 6702364:bin/ccacct, SHARED=(…)) [src].

There are two payoffs:

• Price: the bulk reading and editing happens on the cheaper model.
• Context isolation: only the subagent's final report enters the Opus window.

The cost is that a subagent knows only its brief. This chapter was produced that way, with a brief that had to carry every fact the orchestrator knew.

Commit evidence is weak but consistent. All 8 Claude co-author trailers in diary-mcp and all 3 in vault-mcp name "Claude Sonnet 5", while AIDEN's and cachyos-mcp's name Opus 4.8 [src]. A trailer names the session model that made the commit, so this does not prove the orchestrator pattern [inf].

8.8 The go-to order: Diary, Vault, CachyOS

"Wenn ich jetzt ein neues Setup aufsetzen würde, wäre mein Go-To: 1. Diary MCP 2. Vault MCP 3. CachyOS MCP" ("if I set up a new machine now, my go-to would be 1. Diary 2. Vault 3. CachyOS"). The dependencies explain the order [facts src, ordering logic inf]:

1. Diary depends only on Postgres (DIARY_DATABASE_URL, default postgresql://localhost/diary_mcp), so it needs nothing from Vault. Other layers depend on it: - all three hooks, - presumably rules/memory.md, - AIDEN, which opens a persistent MCP client session to diary-mcp-local and has "no local fallback" (volantic-codescope/src/aiden/diary.py:46; README.md:54-57).

Trap: diary-mcp-local is not among diary-mcp's entry points (diary-mcp, diary-admin-mcp, diary-web in pyproject.toml:17-20). On a fresh host you need a wrapper with that name, or AIDEN_DIARY_COMMAND=diary-mcp. 2. Vault is the credential channel for everything installed after it. Installing it before cis-api and other credentialed servers means their secrets never touch a config file in the first place. 3. CachyOS is a leaf: no credentials, env-gated, Arch-specific. - It imports netmcp.register and sysprobe.register inside try/except Exception: pass (cachyos-mcp/src/cachyosmcp/init.py:20-29). - A missing path dependency therefore shows up as 21 tools instead of 111, with no error.

AIDEN is not on the list. It depends on Diary and is per-codebase tooling rather than machine infrastructure [inf].

8.9 Interlock

 ccacct:  N x CLAUDE_CONFIG_DIR --symlinks--> ~/.claude (private git repo)
          + .claude.json merge (mcpServers, projects, skillUsage; minus ACCOUNT_KEYS)
                        |
   CLAUDE.md + @rules/*  (persuasion, every turn)     settings.json: model, effort,
   skills/ (listing budget)   agents/ (model: sonnet)  hooks, permissions
                                                        |
        SessionStart ---- ccacct autosync (links) ------+
        SessionStart ---- diary pins (start|compact) ---+--> Postgres diary DB
        UserPromptSubmit  diary FTS (script not in repo)+       ^   ^  ssh-tunnel LWW
        SessionEnd ------ detached extract_memories ----+       |   +-- other hosts (Ch 3)
                                                                |
   AIDEN (codescope) --stdio MCP client--> diary-mcp-local -----+
   diary-mcp (MCP server) --------------------------------------+
   vault-launch --bw--> Vaultwarden
        | env CIS_USER/CIS_PASS, stdio inherit
        +--> cis mcp (Uni-Portal)
   cachyos-mcp --import register()--> network-mcp (31) + sysprobe-mcp (59)

8.10 Transferable vs machine-specific

8.11 What to take away

• An unconditional import is a per-turn tax. @import is inlining. Material that is only sometimes relevant belongs in a skill, and skill listings have their own budget.
• A rule that must never break belongs outside the prompt. In rising order of strength: PreToolUse hook, permission rule, the backend's own permissions (a read-only role, execute=False).
• Check isolation claims against the file list. "Own history and context" turned out to mean "own history.jsonl and credentials".
• Stop hooks cut both ways. The mechanism that enforces "done means done" also overrides pauses the user wanted. Every source of continuation needs a counter and a precise condition.
• Install the dependency roots first: memory (others lean on it), then credentials (others need them), then leaves.