Architecture¶

This document describes how claude-toolbox components fit together. For conventions on authoring skills, profiles, and agents, see CLAUDE.md.

Overview¶

claude-toolbox provides a development environment for two AI coding providers (Claude Code and Codex) through three integrated components:

klaude-plugin/          (canonical source)
    |
    |-- generate-kodex --> kodex-plugin/      (generated Codex variant)
    |                      .codex/agents/     (generated sub-agents)
    |
.claude/                (Claude Code config)
.codex/                 (Codex config — hand-authored)
.github/                (template sync infrastructure)

Components¶

kk Plugin (klaude-plugin/)¶

The canonical source of truth for all workflow functionality. Contains:

• skills/ — 10 workflow skills (/kk:design, /kk:implement, /kk:review-code, /kk:test, /kk:document, etc.)
• commands/ — Slash commands for isolated/variant invocations
• agents/ — Sub-agent definitions (code-reviewer, design-reviewer, spec-reviewer, architecture-reviewer, eval-grader, profile-resolver)
• profiles/ — Per-domain content (Go, Java, JS/TS, Kotlin, K8s, Python) with detection rules, review checklists, implementation gotchas, design prompts, test validators, and doc rubrics
• hooks/ — Hook definitions (SessionStart plugin-root export, PreToolUse Bash validation)
• scripts/ — Hook scripts (set-plugin-root.sh, validate-bash.sh)

Skills reference shared instructions via symlinks to skills/_shared/. Profiles are referenced via ${CLAUDE_PLUGIN_ROOT}/profiles/ paths (substituted at plugin-load time by the Claude Code harness).

Codex Generation (cmd/generate-kodex/)¶

A Go tool that transforms klaude-plugin/ into Codex-compatible artifacts:

• kodex-plugin/ — Skills with ${CLAUDE_PLUGIN_ROOT} and ${TOOLBOX_PLUGIN_ROOT} resolved to relative paths, installed-path root-resolution instructions, injected headers, and copied profiles
• .codex/agents/*.toml — Sub-agent markdown converted to TOML format with developer_instructions

Driven by scripts/kodex-generate-manifest.yml. Run via make generate-kodex.

Codex resolves the plugin root from the installed skill's absolute SKILL.md path: the root is the parent of skills/. Generated relative paths such as ../../profiles/ are relative to the installed skill directory, not the consumer's working directory. The generator rewrites Claude-specific shell lookup instructions; Codex does not look up TOOLBOX_PLUGIN_ROOT. When delegating, the parent supplies the absolute root under ## Plugin Root and expands checklist paths before passing them. Sub-agents report a missing root instead of discovering one themselves. Profile authoring checklists retain literal Claude variable names because they describe the canonical Claude plugin's conventions.

Agent generation also translates the canonical frontmatter tools list into a Codex Tool Access section. Read, Grep, and Glob permit their native Codex equivalents, including read-only exec_command calls when dedicated file tools are unavailable. Tool wrappers such as functions.exec carry those calls without granting additional operations. Capy search is included only for agents that declare it. The eval grader keeps only file reading and its fixture-access prohibition; the profile resolver keeps its worktree/plugin path restriction. Unknown tool declarations fail generation instead of being silently discarded. An explicit empty list permits no tool operations; an omitted list keeps the source's inherited-access behavior.

These operation restrictions are instructions, not a separate Codex runtime tool allowlist. Generated agents retain sandbox_mode = "read-only" and explicitly prohibit edits, test/script execution, and permission escalation. This follows the Codex custom-agent configuration model. The read_only_tool_guidance transform removes contradictory Claude-only tool claims from generated agents and runtime-read skill procedures. Canonical Claude files and profile authoring guidance retain their provider-specific conventions.

Plugin Graph Analysis (cmd/plugin-graph/)¶

A Go tool that builds a directed dependency graph of klaude-plugin/ and reports complexity metrics, impact analysis, and structural health. It gives maintainers and review skills a measured view of the skill web rather than a felt one.

It discovers six edge types across the plugin's link taxonomy: markdown links, symlinks, ${CLAUDE_PLUGIN_ROOT} template references, parameterized navigation paths (<name>/<phase>/<checklist> expanded over known sets), agent delegations (subagent_type table rows), and /kk: skill/command invocations. Edges use a dual-layer model — raw file endpoints drive broken-edge validation, while endpoints normalized to the owning artifact node drive metrics (fan-in/out, depth, transitive closure, coupling). Intra-artifact self-references are suppressed from the metric graph.

Subcommands: graph (emit the graph), metrics (complexity numbers), validate (broken-edge/orphan gate, exit 1 on findings). Output formats: text, json, dot, mermaid. Global --root selects the plugin directory; --ref <git-ref> analyzes a past commit via a throwaway git worktree. graph/metrics support targeted mode (positional args slice the graph to nodes reachable from a start set); validate rejects targets because its findings are whole-graph health signals.

Broken-edge detection exempts non-operative sources — links from evals/ fixtures (deliberately partial) and example-*.md templates — mirroring the orphan-detection evals/ exemption. Run via make plugin-graph (Go tests + validate against the real plugin); see Testing.

The model at a glance¶

The six edge types connect a handful of artifact types. Each arrow below is one edge type; the concrete graph expands these over every skill, command, agent, profile phase, and shared instruction.

flowchart LR
    cmd["Command<br>/kk:name"] -->|"/kk: invocation"| skill["Skill<br>SKILL.md"]
    skill -->|"subagent_type delegation"| agent["Agent"]
    skill -->|"symlink · markdown link"| shared["_shared/<br>instruction"]
    skill -->|"plugin-root ref · &lt;name&gt;/&lt;phase&gt; nav"| pidx["Profile phase<br>index.md"]
    pidx -->|"markdown link"| chk["Checklist /<br>content file"]
    agent -->|"plugin-root ref"| pidx
    agent -->|"markdown link"| shared

For the complete, zoomable node-and-edge graph of the real plugin, see Plugin Graph.

Current metrics¶

Regenerated from the live plugin on every docs build (make plugin-graph-docs), so these numbers track the plugin as it stands:

NAME                   FAN-OUT  FAN-IN  DEPTH  TRANSITIVE
model                  12       0       -1     24
merge-docs             2        0       -1     19
review-architecture    6        6       -1     19
design                 15       11      -1     18
document               2        6       -1     18
implement              9        10      -1     18
review-code            8        25      -1     18
review-design          5        3       -1     18
review-spec            8        14      -1     18
test                   2        9       -1     18
chain-of-verification  3        3       1      2
dependency-handling    1        12      1      1
diff-skill             1        0       1      1

Hotspots (26):
  skills/review-code/  (fan-in 25)
  skills/review-spec/  (fan-in 14)
  skills/_shared/capy-knowledge-protocol.md  (fan-in 12)
  skills/dependency-handling/  (fan-in 12)
  skills/design/  (fan-in 11)
  skills/implement/  (fan-in 10)
  skills/test/  (fan-in 9)
  skills/_shared/profile-detection.md  (fan-in 6)
  skills/document/  (fan-in 6)
  skills/review-architecture/  (fan-in 6)
  commands/chain-of-verification/  (fan-in 5)
  profiles/twelve-factor/design/  (fan-in 3)
  skills/chain-of-verification/  (fan-in 3)
  skills/review-design/  (fan-in 3)
  commands/review-code/  (fan-in 2)
  skills/_shared/pal-codereview-invocation.md  (fan-in 2)
  skills/_shared/review-scope-protocol.md  (fan-in 2)
  agents/code-reviewer.md  (fan-in 1)
  agents/design-reviewer.md  (fan-in 1)
  agents/spec-reviewer.md  (fan-in 1)
  commands/review-spec/  (fan-in 1)
  profiles/k8s/  (fan-in 1)
  skills/_shared/contact-ratio-guard.md  (fan-in 1)
  skills/_shared/fact-flip-propagation.md  (fan-in 1)
  skills/_shared/open-question-pass.md  (fan-in 1)
  skills/_shared/requirements-harvesting.md  (fan-in 1)

Coupling (45):
  skills/merge-docs/ <-> skills/model/  (19 shared)
  skills/merge-docs/ <-> skills/review-architecture/  (19 shared)
  skills/model/ <-> skills/review-architecture/  (19 shared)
  skills/design/ <-> skills/merge-docs/  (18 shared)
  skills/design/ <-> skills/model/  (18 shared)
  skills/design/ <-> skills/review-architecture/  (18 shared)
  skills/document/ <-> skills/merge-docs/  (18 shared)
  skills/document/ <-> skills/model/  (18 shared)
  skills/document/ <-> skills/review-architecture/  (18 shared)
  skills/implement/ <-> skills/merge-docs/  (18 shared)
  skills/implement/ <-> skills/model/  (18 shared)
  skills/implement/ <-> skills/review-architecture/  (18 shared)
  skills/merge-docs/ <-> skills/review-code/  (18 shared)
  skills/merge-docs/ <-> skills/review-design/  (18 shared)
  skills/merge-docs/ <-> skills/review-spec/  (18 shared)
  skills/merge-docs/ <-> skills/test/  (18 shared)
  skills/model/ <-> skills/review-code/  (18 shared)
  skills/model/ <-> skills/review-design/  (18 shared)
  skills/model/ <-> skills/review-spec/  (18 shared)
  skills/model/ <-> skills/test/  (18 shared)
  skills/review-architecture/ <-> skills/review-code/  (18 shared)
  skills/review-architecture/ <-> skills/review-design/  (18 shared)
  skills/review-architecture/ <-> skills/review-spec/  (18 shared)
  skills/review-architecture/ <-> skills/test/  (18 shared)
  skills/design/ <-> skills/document/  (17 shared)
  skills/design/ <-> skills/implement/  (17 shared)
  skills/design/ <-> skills/review-code/  (17 shared)
  skills/design/ <-> skills/review-design/  (17 shared)
  skills/design/ <-> skills/review-spec/  (17 shared)
  skills/design/ <-> skills/test/  (17 shared)
  skills/document/ <-> skills/implement/  (17 shared)
  skills/document/ <-> skills/review-code/  (17 shared)
  skills/document/ <-> skills/review-design/  (17 shared)
  skills/document/ <-> skills/review-spec/  (17 shared)
  skills/document/ <-> skills/test/  (17 shared)
  skills/implement/ <-> skills/review-code/  (17 shared)
  skills/implement/ <-> skills/review-design/  (17 shared)
  skills/implement/ <-> skills/review-spec/  (17 shared)
  skills/implement/ <-> skills/test/  (17 shared)
  skills/review-code/ <-> skills/review-design/  (17 shared)
  skills/review-code/ <-> skills/review-spec/  (17 shared)
  skills/review-code/ <-> skills/test/  (17 shared)
  skills/review-design/ <-> skills/review-spec/  (17 shared)
  skills/review-design/ <-> skills/test/  (17 shared)
  skills/review-spec/ <-> skills/test/  (17 shared)

Diagnostics (1):
  cycle detected affecting: README.md, agents/architecture-reviewer.md, agents/profile-resolver.md, agents/spec-reviewer.md, profiles/go/review-code/, profiles/java/, profiles/java/review-code/, profiles/js_ts/, profiles/js_ts/review-code/, profiles/k8s-operator/design/, profiles/k8s/design/, profiles/k8s/document/, profiles/k8s/implement/, profiles/k8s/review-code/, profiles/k8s/review-spec/, profiles/k8s/test/, profiles/kotlin/, profiles/kotlin/review-code/, profiles/python/, profiles/python/review-code/, profiles/skill-md/review-code/, profiles/twelve-factor/, profiles/twelve-factor/design/, skills/_shared/profile-detection.md, skills/_shared/review-scope-protocol.md, skills/design/, skills/document/, skills/implement/, skills/merge-docs/, skills/model/, skills/review-architecture/, skills/review-code/, skills/review-design/, skills/review-spec/, skills/test/

Claude Code Config (.claude/)¶

• settings.json — Permission baselines (allow/deny lists), env vars, model, plugin marketplace
• settings.local.json — Per-repo overrides (never synced)
• CLAUDE.extra.md — Behavioral instructions (synced downstream)
• scripts/ — Statusline scripts (basic and enhanced themes)

Codex Config (.codex/)¶

Hand-authored (not generated):

• config.toml — Model, approval policy, features, MCP server config (capy)
• hooks.json — SessionStart (injects context) and PreToolUse (Bash validation) hooks
• rules/default.rules — Starlark command policies (ported from Claude deny list)
• scripts/ — Hook scripts (session-start.sh, pretooluse-bash.sh)

Generated (by cmd/generate-kodex/):

• agents/*.toml — Sub-agent definitions

Documentation Site (docs/, mkdocs.yml)¶

MkDocs Material site with a custom Tokyo Night color scheme, deployed to GitHub Pages via mike for versioned documentation.

• mkdocs.yml — Site config: Tokyo Night theme (tokyonight:dark/tokyonight:light), tabs nav, pymdownx extensions, mike versioning
• docs/ — Content pages (getting-started, user-guide, providers, contributing, about) alongside internal docs (adr, wip, done — excluded from search)
• docs/overrides/ — Template overrides: main.html (base with Space Mono font, OG tags), home.html (custom landing page with scroll-pinned hero→pipeline transition and matrix rain effect)
• docs/assets/ — stylesheets/tokyonight.css (color scheme), stylesheets/extra.css (site-wide tweaks), javascripts/terminal.js (placeholder for future non-homepage JS)
• requirements.txt — Python deps (mkdocs-material, mike, mkdocs-minify-plugin, mkdocs-panzoom-plugin)
• .github/workflows/docs.yml — CI: builds and deploys via mike on master push or version tags

Template Infrastructure (.github/)¶

• template-cleanup.sh — Initializes a new repo from the template (interactive or CI)
• template-sync.sh / template-sync.yml — Pulls upstream config updates into downstream repos via PR
• template-state.json — Sync manifest tracking version, variables, and exclusions

Installation Modes¶

Users interact with claude-toolbox through three distinct modes, each providing a different subset of functionality:

Plugin-only (Claude): /plugin install kk@claude-toolbox — skills, commands, hooks, agents, profiles.

Plugin-only (Codex): codex plugin marketplace add serpro69/claude-toolbox — skills and profiles only. Hooks, agents, rules, and config require template setup.

Template / Sync: Full configuration for both providers, kept in sync with upstream via GitHub Actions.

Full repo checkout: Everything above plus the generation tools (cmd/), test suites (test/), and maintainer workflows.

Marketplace gotchas¶

Plugin source paths must use "./", not "." In marketplace.json, the source field for each plugin entry must use "./" (with trailing slash) for repo-root plugins, not bare ".". Claude Code's path resolver does not treat them equivalently — "." causes plugin install to fail with a misleading "source type not supported" error. Paths to subdirectories (e.g., "./klaude-plugin") already include the "./" prefix and are unaffected.

Stale marketplace cache after fixing. Claude Code caches cloned marketplace repos under ~/.claude/plugins/. After fixing marketplace.json and pushing, marketplace add or marketplace update may still use the stale cache. For a clean slate: remove the marketplace entry from ~/.claude/plugins/marketplaces/<name>/, delete any references in ~/.claude/plugins/known_marketplaces.json and ~/.claude/plugins/installed_plugins.json, then re-add with claude plugin marketplace add.

Data Flow¶

Skill execution¶

User invokes /kk:review-code
  → Claude Code loads SKILL.md (${CLAUDE_PLUGIN_ROOT} substituted)
  → Skill reads shared instructions via symlinks
  → Profile detection runs (git diff --stat → DETECTION.md matching)
  → Profile content loaded (index.md → always-load + conditional files)
  → Subject-matter action (read diff, produce findings)

Template sync¶

Downstream repo triggers sync workflow
  → Sparse-clones upstream at specified version
  → Reads .github/template-state.json for variables and exclusions
  → Copies .claude/, .codex/ to staging
  → Applies variable substitutions (CC_MODEL, CODEX_MODEL, etc.)
  → Smart-merges settings.json (new keys added, existing preserved)
  → Creates PR with changes

Documentation publishing¶

Push to master
  → .github/workflows/docs.yml triggers
  → mike deploy --push dev (unreleased docs)

Push tag v0.14.0
  → .github/workflows/docs.yml triggers
  → Extracts major.minor → "0.14"
  → mike deploy --push --update-aliases "0.14" latest
  → mike set-default --push latest (bare URL → latest release)
  → GitHub Pages serves from gh-pages branch

Codex generation¶

make generate-kodex
  → go test (unit tests for generation tool)
  → go run cmd/generate-kodex -manifest scripts/kodex-generate-manifest.yml
    → Copy skills with ${CLAUDE_PLUGIN_ROOT} → relative path transform
    → Copy profiles as-is
    → Convert agents/*.md → agents/*.toml
    → Generate .codex-plugin/plugin.json
  → make test-structure (validate bidirectional invariants)

ADRs¶

Architecture decisions are recorded in docs/adr/: