Claude Code

Vendor: Anthropic Install name: claude-code Status: GA Native config: ~/.claude/

InstallationCopy Anchor Link

apothem install --harness claude-code

The claude-code adapter installs the shared Apothem corpus into Claude Code's native discovery tree. Markdown agents, rules, skills, output styles, and settings are installed in their native locations; command prompts are converted into skills so reusable workflows stay visible through the current Claude Code skill surface. The statusline renderer is copied to ~/.claude/statuslines/ but not wired: Claude Code reads its status line from the statusLine setting, which the adapter leaves unset. To turn it on, add a statusLine entry of "type": "command" that runs ~/.claude/statuslines/render.py to settings.json. The snippet's commandWindows value runs on Windows and names the interpreter unquoted. When the interpreter path contains a space, the install writes its Windows 8.3 short form in that value when the volume has one. The hook entries in settings.json keep the full path.

Files written: settings.json, the Apothem block in CLAUDE.md, agents/, rules/, skills/, statuslines/, output-styles/, and the .apothem/support/ support subtree (.apothem/support/hooks/, .apothem/support/conformity/, .apothem/support/schemas/, .apothem/support/templates/) under ~/.claude/. Command files are converted into child skill directories. The hook dispatcher and conformity gate run from their materialized copies — settings.json hook entries invoke ~/.claude/.apothem/support/hooks/dispatch.py and ~/.claude/.apothem/support/conformity/gate.py by absolute path, so no importable apothem package is needed on the host.

~/.claude/CLAUDE.md stays operator-owned. The adapter writes one sentinel-delimited Apothem block into it, holding the profile projection (identity, preferences, rules, seriousness, and opted-in behaviors) and an Apothem support files section, and preserves every line outside the sentinels verbatim. The support files section names the absolute directory each repository-style citation in the installed rules, skills, and agents resolves against: rules/<name>.md under ~/.claude/rules/, and templates/..., schemas/..., hooks/..., and conformity/... under ~/.claude/.apothem/support/. It also points at the rule index, ~/.claude/rules/apothem-rule-index.md. The rest of the Apothem governance surface reaches Claude Code through the propagated rules/ tree and the SessionStart hook. OpenCode also loads ~/.claude/CLAUDE.md when no ~/.config/opencode/AGENTS.md exists, so the block names no single tool as its reader.

Profile-to-native-config mappingCopy Anchor Link

On every apothem install or apothem update, the adapter propagates the shared apothem corpus into ~/.claude/ per the propagation manifest. The adapter uses native directories directly where possible and converts command prompts into skill folders. Existing matching Apothem-managed children are backed up before replacement; unrelated operator-authored entries are preserved. settings.json is merged so operator-authored keys remain recoverable.

Operator-authored files are kept only outside the folders below. Every install and update removes each of these folders under ~/.claude/ that exists, whether or not Apothem wrote it: src/, conformity/, schemas/, hooks/, config/, scripts/, tools/, lib/, templates/, docs/, tests/, packaging/, mcp/, examples/, assets/, site/, public/, and commands/. It also removes statuslines/__init__.py and the AGENTS.md files in agents/, rules/, skills/, statuslines/, and output-styles/. A removed folder goes whole, including the files you placed in it. Slash commands you keep in commands/ are removed too, and Apothem installs its own command prompts as skills under skills/. A hook script you keep in hooks/ is removed, which leaves any settings.json entry that calls it pointing at nothing. The sweep runs before the install writes its own files. Each removed path is copied to ~/.apothem/backups/ first, and the install record names that copy. Uninstall does not restore it. To restore a removed path, run apothem rollback --harness claude-code --install-id ID for the install that removed it, as described in the rollback reference. A plain apothem rollback reverses only the latest install. Install records and their copies are kept for the newest 10 installs, so a removed path can be restored only while its install is among them. apothem diff --harness claude-code lists these removals as Prune stale files before you install.

Installed skills, and the skills bundled in the Claude Code plugin, carry user-invocable instead of the source corpus's userInvocable, because Claude Code reads only the hyphenated key. The two template containers (plan-suite, research-suite) set it to false, so they stay out of the / menu. Every output style sets keep-coding-instructions: true, so selecting one keeps Claude Code's built-in software engineering instructions.

Both also carry the Apothem-only frontmatter keys (version, updated, archetype, portability) under a trailing metadata: map of quoted strings, in that fixed order. Claude Code ignores unknown top-level keys, and the open skill format keeps client-specific extras in metadata. The source files do not change. The user-level skill folders (~/.agents/skills/, ~/.codebuddy/skills/, ~/.kiro/skills/, and ~/.trae/skills/) use the same metadata form, so installs that share a folder never rewrite each other's files. Every other harness receives the keys at the top level as before.

Rules and what loads at launchCopy Anchor Link

Claude Code loads a rule file at launch unless its frontmatter carries a paths: list that scopes it. With paths: it loads the rule when it reads or edits a file that matches. A list made only of ** scopes nothing, so that rule also loads at launch; no Apothem rule uses one. The install turns each rule's pathFilter into that list. Five rules carry none and load in every session: agnostic-posture, authority-inquiry, session-closure, context-management, and the rule index, apothem-rule-index. Every other rule is installed under ~/.claude/rules/ with paths: and loads on a matching touch.

Claude Code matches those globs, with .gitignore semantics, against the path of the file relative to the working directory, and never against a file outside it. The auto memory directory sits under ~/.claude/projects/, so auto-memory and auto-memory-topic-files never load on a path match. Editing ~/.claude/CLAUDE.md or a file under ~/.claude/rules/ from another project does not load the rules scoped to those files either. These rules reach a session through the index.

The index names each rule and the situation that calls for it. A step that cites rules/<name>.md as its procedure reads that file first. After a context compaction, read again any rule you were applying: Claude Code does not re-inject a path-scoped rule until a matching file is touched again. The name apothem-rule-index.md is reserved, because an install backs up and overwrites a rule file with that name.

The rules that govern Apothem's own surfaces are scoped to CLAUDE.md, AGENTS.md, and the Markdown under rules/, commands/, skills/, agents/, hooks/, and output-styles/. An application repository rarely contains those files, so in one these rules reach a session through the index, through a skill, command, or helper that cites them, and through the hooks, not through a path match.

The rule copies are written without their closing ## Bindings section, as command skills are. The section holds reciprocal references for maintainers and the conformity gate. The source files keep it, and so do the copies other harnesses receive.

To keep a scoped rule on in every session, you can try importing it from text outside the Apothem block in ~/.claude/CLAUDE.md, for example @rules/definitiveness.md. The Claude Code memory page documents the import and says an imported path resolves relative to the importing file. It does not say how an imported rule's paths list is treated, and Apothem has not verified this. Check with the InstructionsLoaded hook that the rule loads at launch and does not load a second time on a path match.

Command skills and reference filesCopy Anchor Link

After a context compaction Claude Code re-attaches only the first 5,000 tokens of each invoked skill, and it recommends a SKILL.md of about 500 lines or fewer with detail in sibling files. The command prompts run to 67 KB, so the Claude Code emission splits each one into a slim SKILL.md plus files under references/:

• The ## Bindings section is dropped. It is maintainer text for the conformity gate and the model never needs it.
• The Pipeline Contract, Foundational Stanzas, Decision Tree, examples, mode sections and a few cited inventories move to reference files. The heading stays, and a one-line pointer under it names the file and says when to read it. The pointers for the Pipeline Contract and the Foundational Stanzas also list what the file covers.
• When SKILL.md is still over 15,800 bytes, the largest Workflow steps move to references/step-NN-<slug>.md, largest first, until it fits. The slug is the step title without its Step N: prefix and without a trailing parenthesised mandate or discipline id. Steps under 600 bytes stay inline. If that is not enough, the Output, Mandates, Critical Rules and Instructions sections move in that order.
• A short note after the preamble tells the model where the files are (${CLAUDE_SKILL_DIR}/references/) and that it MUST re-read the ones that govern its current step after a compaction.

Every emitted SKILL.md, including the ## Installed Reference Paths note the install appends, stays at or under 17,000 bytes for an install root of up to 140 characters. The plugin ships the same files without that note, and its commands are skills under skills/, so it has no commands/ folder; the invocation /apothem:<name> is unchanged. The split is deterministic and reversible: the text of SKILL.md and its reference files rebuilds the source command minus Bindings. The source files, and the output for every other harness, are unchanged. Other tools also read skills from ~/.claude/skills/, so they see the same files; apothem install names them.

To see the numbers for every command, run the measurement script from a checkout:

python scripts/dev/measure_claude_skills.py          # per-command table
python scripts/dev/measure_claude_skills.py --check  # exit 1 on a breach

It reports source, SKILL.md and reference sizes, the headroom to the budget, and an estimated token count, and lists the native skills for comparison. research-suite, a native skill whose source is not split, is the one skill above the cap.

Compatibility notesCopy Anchor Link

Command prompts are converted into skill directories and rules are rendered as described above; skills and output styles are copied as they are, and agents are copied as written except that a helper the profile's agent_mcp_servers key lists gains an mcp__<server>__* entry per named server in its tools line (see MCP servers). Install validates that the profile is well-formed and all hook bindings in settings.json are resolvable. The adapter authors no MCP server entries: register servers with claude mcp add (see MCP servers).

~/.claude/agents/ is a shared root that Claude Code owns, as is ~/.claude/skills/: other supported tools load those folders, so the agents and skills a Claude Code install writes there appear in those tools as well, and the install prints a note that names them. The harness registry lists the readers of each root.

Claude Code applies all hook bindings in settings.json on every session start. Each adapter is verified against its own native harness — there is no privileged "reference" harness.

Permission rule limitsCopy Anchor Link

The settings template denies Read(...) on secret and cache paths such as .env* and ~/.ssh/**. Claude Code applies a Read deny to its file tools, to the file commands it recognizes in Bash (cat, head, tail, sed, tee), and to redirection targets. It does not apply the deny to a search that reads files without naming them, such as grep -r pattern ., or to a script that opens files itself (permissions reference). On macOS, Linux, and WSL, Claude Code leaves the Glob and Grep tools out of the default tool set and searches through Bash instead, so the template's Glob and Grep allow entries take effect only where those tools are present. To block every process from reading a path, enable the Claude Code sandbox.

The skills and helper definitions that name TodoWrite also name TaskCreate, TaskGet, TaskList, and TaskUpdate, because Claude Code turns TodoWrite off by default in favor of those tools.

VerificationCopy Anchor Link

apothem verify --harness claude-code

The verify command confirms that:

1. The native config exists at the expected path.
2. Each managed target exists; managed files are non-empty, and JSON or YAML configs parse. Add --profile PATH to also confirm that the installed files match that profile.
3. The adapter-specific verification routine reports success.

UpdatingCopy Anchor Link

apothem update --harness claude-code

Re-derives the native config from the current shared profile. Run after the installed apothem package is updated, so the propagated convention surface (agents, rules, skills, statuslines, output-styles) reflects the new version. In CLAUDE.md, update rewrites only the Apothem block between its sentinels.

UninstallingCopy Anchor Link

apothem uninstall --harness claude-code

Removes the Apothem block from ~/.claude/CLAUDE.md and keeps any other text in it. The file is deleted only when nothing else remains in it. Removes the entries the adapter added to ~/.claude/settings.json (your own permission rules, keys, and hook handlers stay, and the file is deleted only when Apothem created it and nothing of yours is left). Also removes the Apothem files in ~/.claude/agents/, ~/.claude/rules/, ~/.claude/skills/, ~/.claude/statuslines/, ~/.claude/output-styles/, and ~/.claude/.apothem/support/; other files in those folders stay. Each file is backed up under ~/.apothem/backups/ before it is changed or removed. The installed apothem package and source repository are unaffected.

Conformity gateCopy Anchor Link

python -m apothem.conformity.gate --all .

Run against the repository, the gate requires the ## Bindings section on every rule, command, helper, and skill. Run against an installed ~/.claude/ tree, it accepts a rule or skill copy that has no such section, because the install leaves it out, and still checks a section that is present.

TroubleshootingCopy Anchor Link

Configuration knobsCopy Anchor Link

See alsoCopy Anchor Link

• All harnesses — the full catalog of supported tools
• Install guide — install Apothem into this harness
• apothem harnesses reference — list and inspect adapters from the CLI