Claude Code integration¶

Register AdaMAST with Claude Code so the agent checks its work against known failure modes while it runs and, after enough completed tasks, learns a catalog specific to your project. The integration installs hooks that call the AdaMAST runtime at session start, user-prompt submission, checkpoints, and final submission, either project-local or user-level (an interactive mode shared with Codex).

🛣️ Choose an install path¶

Two paths register the same hooks and produce the same runtime behavior. Pick one — running both double-registers every event.

Both end at the same dispatcher reading the same ~/.claude/adamast.json, so the runtime behavior is identical: same eight events, same checkpoints, same taxonomy picker, same blocking final gate. They differ only in what it takes to get there and what else comes along.

	A · Plugin	B · Package CLI
Install	`/plugin marketplace add …` + `/plugin install`	`uv tool install adamast` + `adamast claude install --user-level`
Package needed first	No — fetched on first use	Yes
Needs the `claude` binary on `PATH`	No	Yes — the installer verifies against it and aborts without it
First run	Live in the first new session	Live immediately
Ships the guidance skill	Yes, as a plugin component	Yes, into `~/.claude/skills/`
Taxonomy worker agent	Yes, as a plugin component	Yes, into `~/.claude/agents/`
Hooks registered in	The plugin registry	`~/.claude/settings.json`
Project-local scoping	No	Yes, `--project-dir`
Tuning knobs	Fixed defaults	41 install flags
Version pinning	Follows the marketplace	Yes, pin the package
Updates	`/plugin update`	Reinstall the package
Supported systems	Windows, macOS, Linux	Windows, macOS, Linux

Choose A for the shortest path, or when you cannot install the claude CLI. Choose B when you need project-local scope, an exact pinned version, any of the install flags, or a surface where plugins are unavailable.

🚀 Path A · Plugin (zero configuration)¶

/plugin marketplace add multi-agent-systems-failure-taxonomy/AdaMAST
/plugin install adamast@adamast

The plugin bundles the skill, all eight hook events, and the taxonomy worker subagent. Start a new conversation after installation. Its first SessionStart installs the version-pinned runtime into Claude Code's writable plugin data directory, writes ~/.claude/adamast.json with native paths, and continues that same conversation. Python, pip, and uv are not prerequisites.

It never edits ~/.claude/settings.json — Claude Code owns plugin hook registration. Bootstrap activity is logged inside the plugin data directory at state/bootstrap.log.

Implementation notes live in the plugin README.

🚀 Path B · Package CLI (zero configuration)¶

Note

This path assumes the general AdaMAST package is already installed from the documentation home, and that the claude CLI binary is on PATH. The installer verifies the hook contract against it and aborts with installed Claude Code executable was not found otherwise — set CLAUDE_CODE_EXECUTABLE to point at it explicitly.

Register AdaMAST for every Claude Code conversation:
```
adamast claude install --user-level
```
This also installs the guidance skill to ~/.claude/skills/adamast-failure-modes/. Pass --no-install-skill to skip it, --skills-dir to place it elsewhere, or --install-skill to add it to a project-local install, where it is off by default.
Check the install:
```
adamast doctor --claude-code
```
Fully restart an already-running Claude Code process, then begin a new conversation so the new registration is loaded.

The installer merges AdaMAST into ~/.claude/settings.json and writes ~/.claude/adamast.json; unrelated settings and plugins are preserved.

From then on, in each conversation AdaMAST will:

open the local taxonomy library for MAST (the built-in general-purpose catalog of 14 common agent failure modes; what is MAST?), stored taxonomies, or No taxonomy;
hold the first substantive prompt until that choice is resolved;
record checkpoint reflections privately at configured boundaries;
block final completion until a passing final-gate checkpoint is recorded;
record one canonical episode trace at each accepted Stop boundary;
trigger durable generation or refinement jobs when thresholds are reached.

Make it yours:

I want to…	Do this instead
Install for one project only	`adamast claude install --project-dir . --config adamast.json`, then start Claude Code in that project
Pick taxonomies inline in chat (numbered) instead of a browser page	`adamast claude install --user-level --selector-surface inline`
Turn built-in hooks off, or narrow them to certain tools	see "Customize the hooks" below
Undo the package CLI registration	`adamast claude uninstall --user-level` (also removes the skill; `--no-remove-skill` keeps it)
Undo the plugin	`/plugin uninstall adamast@adamast`
Point the plugin at a specific interpreter	set `ADAMAST_PYTHON`
Point the plugin at a specific config	set `ADAMAST_CONFIG`, or add `adamast.json` to the project root

🧭 The taxonomy picker¶

The user-level installer defaults to the browser selector. On the first substantive prompt, the synchronous UserPromptSubmit hook keeps that prompt paused while the browser is open. Selecting a taxonomy completes the hook and lets Claude process the original prompt immediately; do not send a second message.

If you never pick

If no choice is made before worker_timeout_seconds, AdaMAST blocks that prompt without echoing its full text, and the next prompt reopens the selector.

Your choice stays isolated and persistent:

Per conversation. Every new Claude conversation receives a durable conversation branch. Choosing a stored taxonomy uses it only as that branch's immutable seed; choosing MAST starts the branch from zero. Later traces and refinements never enter another conversation's branch.
Per host. Claude Code resolves a Claude-owned conversation branch for every conversation. Codex uses a separate branch even when its base trace_output, project root, and logical task-group name match. This prevents traces, active learned taxonomies, and native learning jobs from crossing between conversations or hosts.
Pinned to the session. The taxonomy choice remains pinned to Claude's session ID. Resuming the conversation from another shell or changing its current working directory does not recompute the project, reopen the browser selector, or replace the selected taxonomy.

Older inline-selector sessions

SessionStart also checks the transcript after the saved selector boundary. An exact offered reply such as MAST is migrated before the browser can reopen; ordinary task prose does not match.

🧠 Learning in the background¶

No external model API key, standalone claude -p process, or second login is required for claude_subagent learning:

A hook asks the active Claude Code session to launch a native generator Agent in the background and continue the user's task immediately.
After exact evidence checks, a separately claimed background support-review Agent evaluates every replacement code.
Each subtask reads only its phase-specific frozen prompt and schema and returns a signed receipt through SubagentStop.
Foreground reconciliation activates between episodes only after both phases pass.

One completed assistant episode is one trace. By default the first generation runs after five eligible traces, the first refinement review after k_init (ten), and later reviews every k (twenty); thresholds and counters are detailed in Traces and learning, the worker protocol in Native taxonomy learning.

MAST or the current learned taxonomy remains active while the worker runs. Trigger and completion notices appear in Claude's visible systemMessage and agent-facing additionalContext.

After activation, Claude context names the active learned taxonomy by display name and immutable ID. The original selector choice, including MAST, remains recorded only as the lineage seed; checkpoints use the active taxonomy's codes.

If a native Agent subtask disappears without a receipt, the coordinator expires its claim, keeps the current taxonomy active, and permits a retry from the same frozen evidence.

Background tasks disabled?

If CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1, AdaMAST leaves learning jobs queued for a later background-capable session instead of running them in the foreground.

📊 Live checkpoint monitor¶

Claude Code opens the same project/conversation monitor used by Codex. The conversation selector shows Claude's current custom title instead of exposing its session UUID, while the UUID remains the stable routing key in the URL.

Built-in checkpoints send their compact fields directly to adamast claude checkpoint; they do not print checkpoint blocks or long reflection prompts into the conversation. Claude's per-prompt ID is attached to every checkpoint created during that prompt, so several checkpoints may remain separate while still appearing under the same turn. A repair-required checkpoint continues to block until the recorded next action is addressed.

Card grouping, navigation, timeline filters, and both viewing modes are covered in Live monitor.

Secrets in traces

Automatic secret redaction runs before trace persistence by default. Redaction is a defense in depth measure, not permission to place credentials in task transcripts.

🎛️ Customize the hooks¶

Hooks are enabled automatically

The installer registers all eight built-in hooks for you; there is nothing to enable by hand. A user-level install needs no approval: hooks run in your next new conversation. For a project-level install, Claude Code itself asks once per project before running hooks from that project's settings; accepting that prompt completes the setup.

Built-in hooks can be disabled or narrowed at install time:

# Disable the built-in subagent checkpoint.
adamast claude install --project-dir . --config adamast.json --disable-hook SubagentStop

# Only run post-tool advisory nudges after selected tools.
adamast claude install --project-dir . --config adamast.json --post-tool-use-matchers Bash,Edit,Write

…or in adamast.json:

{
  "claude_code": {
    "built_in_hooks": {
      "SubagentStop": false,
      "PostToolUse": {
        "enabled": true,
        "matchers": ["Bash", "Edit", "Write"]
      },
      "PostToolUseFailure": ["Bash"]
    }
  }
}

Custom hooks make AdaMAST fire on a specific event or tool rather than every possible boundary:

adamast claude add-hook \
  --project-dir . \
  --name pre-bash \
  --event PreToolUse \
  --matcher Bash \
  --command-pattern "python .*eval" \
  --checkpoint-key fixed \
  --mode blocking

List or remove them:

adamast claude list-hooks --project-dir .
adamast claude remove-hook --project-dir . --name pre-bash

Option	When to use it
`--mode blocking`	The agent must satisfy the reflection contract before continuing.
`--mode advisory`	AdaMAST should nudge but not block.
`--command-pattern`	Narrows a broad tool matcher, for example `Bash`, to one recurring command.
`--checkpoint-key fixed`	Recurring events that should open one checkpoint and close it on the next matching event.

🛟 Gates fail open¶

A skipped gate is quiet

If an AdaMAST hook itself crashes or is killed at Claude Code's per-hook timeout, the agent continues normally and that checkpoint silently does not fire. This is deliberate: an AdaMAST bug must never leave your session unable to finish.

When gating matters (A/B runs, benchmarks), verify it happened rather than assuming:

[adamast] stderr lines report retry-guard releases; internal errors print as AdaMAST Claude Code hook error: lines;
<trace_output>/.adamast-runtime-evidence.json records each checkpoint; <trace_output>/decisions.log records custom-hook retry-guard releases;
adamast status --config adamast.json shows the total recorded checkpoints; verify one session's final gate in the evidence file or the live monitor.

🧹 Uninstall¶

Use the path you installed with.

Plugin¶

/plugin uninstall adamast@adamast

That disables the plugin and stops every hook. The marketplace stays registered so you can reinstall without re-adding it; drop it too with /plugin marketplace remove adamast.

Package CLI¶

# Remove only the user-level AdaMAST registration.
adamast claude uninstall --user-level

# Remove AdaMAST hook config from a project.
adamast claude uninstall --project-dir .

The user-level command also removes the managed guidance skill; pass --no-remove-skill to keep it.

What survives either path¶

Learned taxonomies, trace folders, and ~/.claude/adamast.json are left alone so a reinstall resumes where you stopped. Delete ~/.adamast/ and that config by hand when you want nothing left.

🗂️ Source layout¶

The adapter source is organized under adamast/hosts/claude_code/.

Continue with Live monitor or Troubleshooting.