Claude Code
The first host. The version the plugin needs, what it adds to a session, and the settings a home sets for you.
Claude Code is where every feature is exercised first. The plugin registers its skills, four hooks, the mods module and the agent MCP server, so a session launched from a home gets all of it with no per-home wiring.
| Requires | Claude Code 2.1.314 or newer (below) |
| Launch | claude from the home, or agent for an agent on its own subscription |
| Skills | /agentlayer:<skill> |
| Manual | AGENTS.md through the @-imports in .claude/CLAUDE.md |
| Hooks, mods and MCP server | Bundled with the plugin |
| Settings | .claude/settings.json (permissions) and .claude/settings.local.json (env, gitignored) |
| Reload after a plugin update | /reload-plugins; new hooks need a full relaunch |
Required version
The plugin needs Claude Code 2.1.314 or newer, and so does everything it adds, mods included. Setup and upgrade stop below it, and the session banner warns until you update:
claude --version
claude updateHooks
The four hooks ship with the plugin. Claude Code runs a plugin's hooks only for sessions started where the plugin is enabled, so a session can only ever be captured by the agent whose home it launched in. See Hooks for what each one does.
The shell guard checks the Monitor tool's commands as well as Bash ones. A Monitor command that cds out of the home is refused like a Bash one, though its cd never carries over, so keep a cd there in a subshell.
Do not add capture hooks to ~/.claude/settings.json
Machine-wide hooks hand every session on the machine to one brain. Plugin hooks are the only supported path.
Mods
Beside the hooks, the plugin loads one module that runs inside Claude Code itself. It adds commands that answer without a model turn, such as /capture and /task, a queue for prompts, and sync progress and upgrade notices above the prompt. Mods lists all of it.
Status line
Setup sets the home's footer to the plugin's status line (bun "<plugin root>/src/cli.ts" statusline):
- Line one: the agent's emoji, the model with its effort level, the folder as a clickable link, and the git branch.
- Line two: a context bar, the session cost with its hourly rate, the elapsed time, and your plan's five-hour and weekly limits when Claude Code reports them. Each limit shows the time left until it resets (
16% ↻ 2h · 56% ↻ 3d: minutes under an hour, then hours, then days). - The agent rows under the prompt are drawn by the plugin's mod: each subagent's type, its description and a context bar.
It follows your theme. A light Claude Code theme switches it to colours that read on a light background; with the theme on auto, or none set, it follows the macOS appearance. Dark output is unchanged.
The entry lives in .claude/settings.local.json, since it runs a program by an absolute path on this machine. upgrade repoints it after a plugin move and keeps a status line you set yourself.
Permissions and the sandbox
Setup grants the always-on core tools in settings.json. A pack's tools land there only when you switch the pack on, so the file stays an accurate record of what the agent can reach.
A few entries sit in permissions.ask (git push, gh pr create, curl_run, seed_import). An ask rule is evaluated before Claude Code's auto-mode classifier and cannot be approved past, which makes it the one durable form of "nothing leaves this machine without a human".
The Bash tool runs under a sandbox that denies reads of .state/secrets/ and every .env. The MCP server runs outside that sandbox, which is how the GitHub tools, worktree setup, and the run_upgrade tool do the writes the sandbox blocks. See MCP tools.
Idle compaction
Every home turns idle compaction off: setup writes "idleCompaction": false to .claude/settings.json, and upgrade adds it to a home where neither settings file sets the key. With it on, Claude Code compacts a long conversation while the session sits idle, so a session you stepped away from comes back as a summary. Auto-compact when the context fills still runs, and a value you set yourself is kept.
Artifacts off
Every home turns Claude Code's Artifact tool off: setup writes "enableArtifact": false to .claude/settings.json, and upgrade adds it to a home where neither settings file sets the key. With it on, finished pages, plans and proposals are published to claude.ai, and the copy left in the home is written without its <html>, <head> and <body>, so it doesn't open cleanly from disk. With it off, the agent writes them as complete files in the home: in the project they belong to, otherwise the closest reports/ folder. To have Artifacts back, set the value to true; deleting the key doesn't work, since upgrade puts it back.
Memory routing
Claude Code ships an auto-memory directory under ~/.claude/projects/. Your agent does not use it. The .claude/CLAUDE.md bridge overrides that instruction so every correction, preference, project fact, and reference goes into the knowledge/ tree, which is what stays portable across hosts and what every other tool in the home reads.
Multiple accounts
Each home can run on its own Claude subscription. /login holds one account per OS user, so the home keeps a token of its own and a small agent command starts Claude Code with it. Setup, checks and troubleshooting are on Billing per agent.
Claude Code keeps that token out of hook environments, so the token file also sets AGENT_SUBSCRIPTION. That is how the session banner can warn when a home has the file but the session started without it.
Verifying subscription billing
The host does the thinking, so nothing bills the API. To see it:
- Open Anthropic Console → Usage and note the API cost.
- Run the
knowledge-compileskill. - Refresh. The API cost should not change, and your subscription usage should go up.
If the API cost does change, open an issue.
Recommended settings
CLAUDE_CODE_NO_FLICKER=1in your user-level env block turns on the fullscreen renderer: click-to-position in the prompt, no flicker, flat memory in long sessions. See Terminal.- Model training off in your Claude account. The home already turns telemetry, crash reports and transcript uploads off. See Privacy.