serpro69/claude-toolbox — Summary

One-Line Description

ELv2-licensed, battle-tested development workflow toolkit for Claude Code and OpenAI Codex: 11 pipeline skills, Capy MCP context router, multi-model review via sub-agents, and language-specific profiles — distributed as an installable plugin with Go-based cross-provider code generation.

What This Is

claude-toolbox is a structured development workflow framework built around an 11-skill pipeline covering the full cycle from idea to documentation. The canonical content lives in klaude-plugin/ (for Claude Code) and is auto-generated into kodex-plugin/ (for Codex) by a Go tool (cmd/generate-kodex/). It is NOT a template to fork — it distributes via Claude Code's plugin marketplace system, pointing to the author's own GitHub repository as a custom marketplace.

The core loop is: /kk:design → /kk:review-design → /kk:implement → /kk:review-code → /kk:test → /kk:document

Scale

• Stars: 142 (2026-05-26)
• License: ELv2 (Elastic License v2)
• Skills: 11 (design, review-design, implement, review-code, review-spec, test, document, diff-skill, merge-docs, chain-of-verification, dependency-handling)
• Agents: 5 (code-reviewer, design-reviewer, eval-grader, profile-resolver, spec-reviewer)
• Commands: 5 directories (chain-of-verification, migrate-from-taskmaster, review-code, review-spec, template)
• Hooks: 1 PreToolUse Bash validator
• MCP Servers: 1 (Capy — context-window routing with BM25 + SQLite knowledge.db)
• Language profiles: 8 (go, java, js_ts, kotlin, k8s, k8s-operator, python, skill-md)

Target Audience

Experienced developers who want structured, repeatable agentic development workflows across multiple languages and multiple projects — with persistent context via a knowledge base and multi-model code review. Not a beginner-friendly quickstart; more like professional tooling for power users.

Installation

1. Add to an existing project (adopting) or use as a repository template
2. Enable via settings.json: "enabledPlugins": {"kk@claude-toolbox": true}
3. Point at custom marketplace: "extraKnownMarketplaces": {"claude-toolbox": {"source": {"source": "github", "repo": "serpro69/claude-toolbox"}}}

Skills are then available as /kk:<name>. Three setup paths: template, adopt-existing, plugin-only.

Key Differentiators

1. Cross-provider code generation: klaude-plugin/ is the canonical source; make generate-kodex produces Codex-compatible output (resolves ${CLAUDE_PLUGIN_ROOT}, converts agents to TOML). CI checks freshness.
2. Capy MCP router: Local SQLite knowledge base (knowledge.db) with BM25 search for context-window-aware retrieval. Blocks curl/wget to prevent exfiltration. Sandboxed subprocess.
3. Language-specific profiles: 8 distinct profile directories providing per-language implementation, testing, and review guidance — invoked dynamically via profile-resolver agent.
4. Multi-model code review: /kk:review-code:isolated spawns independent sub-agent reviewers with no authorship bias; supports routing to external Gemini models.
5. Non-permissive license: ELv2 restricts commercial SaaS use — unique among batch peers.
6. Opinionated behavioral CLAUDE.extra.md: Direct/challenging interaction style, explicit assumption-stating, document-deferred-work protocol — not soft guardrails but hard behavioral contracts.

serpro69/claude-toolbox — Distribution & Installation

Distribution Type

Plugin-based (Claude Code plugin marketplace + GitHub repository template). Not a static fork-and-use scaffold; distributes as a live plugin that can be updated independently of the user's project.

Install Methods

Path 1: Template (new projects)

Use the GitHub template to create a new repository — gets the full configuration including .claude/, klaude-plugin/, template sync infrastructure, and Makefile targets.

Path 2: Adopt into existing project

Follow the adopting guide — copies .claude/ settings, hooks, and scripts; wires up the plugin; sets up template sync to pull future updates.

Path 3: Plugin-only

Add to settings.json:

{
  "enabledPlugins": {
    "kk@claude-toolbox": true
  },
  "extraKnownMarketplaces": {
    "claude-toolbox": {
      "source": {
        "source": "github",
        "repo": "serpro69/claude-toolbox"
      }
    }
  }
}

Config Files

Runtime Requirements

• Claude Code (primary target)
• OpenAI Codex (secondary; auto-generated kodex-plugin/)
• Go 1.x (for make generate-kodex — developer workflow only)
• Bash (hook scripts, statusline)
• Python (requirements.txt — capy dependencies)

Template Sync Infrastructure

The repo ships template-sync.sh — a mechanism to pull future toolbox updates into downstream projects. The sync script preserves project-specific customizations while applying upstream changes. Running make sync-template or equivalent keeps the .claude/ config fresh.

Makefile Targets

License Implications

ELv2 (Elastic License v2): free to use for internal/personal projects, cannot be offered as a hosted SaaS service to others. This is the most restrictive license in the batch — all other frameworks use MIT/Apache/CC0/unlicensed.

serpro69/claude-toolbox — Primitives

Claude Code Primitives Used

Skills (11 — via klaude-plugin/)

All prefixed /kk: — invoked as slash skills:

Skills are organized in klaude-plugin/skills/<name>/SKILL.md with supporting files per skill.

Commands (5 directories in klaude-plugin/commands/)

Agents (5)

Hooks (1 event, 1 rule)

Pre-validates all Bash tool calls before execution. Analogous to zbruhnke-cc-starter's validate-bash.sh but shipped via plugin hooks.json rather than project-level hooks.

MCP Servers (1)

Capy — local context-window routing server:

• Launched as bash .claude/scripts/capy.sh serve
• SQLite knowledge store at .capy/knowledge.db
• BM25 full-text search over indexed knowledge
• Tools: capy_execute, capy_batch_execute, capy_fetch_and_index, capy_index, capy_search
• Blocks outbound curl/wget (sandboxed subprocess)
• Config: .capy.toml with store.path = ".capy/knowledge.db"

Language Profiles (8)

Stored in klaude-plugin/profiles/:

• go/ — Go-specific implementation + test + review guidance
• java/ — Java profile
• js_ts/ — JavaScript/TypeScript profile
• kotlin/ — Kotlin profile
• k8s/ — Kubernetes profile
• k8s-operator/ — Kubernetes operator pattern profile
• python/ — Python profile
• skill-md/ — Skill file authoring template

Profiles are selected dynamically via the profile-resolver agent which detects the project language and injects the appropriate profile.

Shared Instruction Pattern

klaude-plugin/skills/_shared/ contains shared instruction files referenced via per-skill symlinks (shared-<name>.md → ../_shared/<name>.md). This prevents path traversal in bundled skills while keeping instructions DRY.

Codex Primitives (Generated)

kodex-plugin/ — auto-generated from klaude-plugin/ via cmd/generate-kodex/:

• Resolves ${CLAUDE_PLUGIN_ROOT} variable references
• Injects required headers
• Parallel structure: same skills, same agents (converted to TOML at .codex/agents/)
• Hand-authored Codex files (not generated): .codex/config.toml, .codex/hooks.json, .codex/rules/default.rules

Settings.json Configuration

{
  "effortLevel": "high",
  "model": "claude-opus-4-6[1m]",
  "env": {
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "64000",
    "CLAUDE_STATUSLINE_MODE": "dark",
    "CLAUDE_STATUSLINE_THEME": "catppuccin",
    "MAX_MCP_OUTPUT_TOKENS": "64000"
  },
  "permissions": {
    "allow": ["Bash(cat:*)", "Bash(grep:*)", "Bash(ls:*)", "Bash(mkdir:*)", "Bash(sort:*)", "Skill(kk:*)", "Read(~/.claude/plugins/cache/claude-toolbox/*)", "WebSearch"],
    "deny": ["Bash(rm:*)", "Read(./**/.env)", "Read(./**/*.lock*)", "Read(.git/)", ...]
  },
  "statusLine": {
    "command": "bash $CLAUDE_PROJECT_DIR/.claude/toolbox/scripts/statusline_enhanced.sh",
    "type": "command"
  }
}

Notable: effortLevel: "high" (not "max" — careful budget control), claude-opus-4-6[1m] 1M context window, explicit Bash(rm:*) deny rule.

serpro69/claude-toolbox — Components

Directory Tree

.
├── .claude/                          # Claude Code config (project-level)
│   ├── settings.json                 # Core settings (model, effort, permissions, statusline, plugin)
│   ├── settings.local.json           # Machine-local overrides (not committed)
│   ├── CLAUDE.extra.md              # Behavioral instructions (independent thinking, fail-loud, deferred work protocol)
│   ├── scripts/
│   │   └── capy.sh                  # Capy MCP launch script
│   └── toolbox/
│       └── scripts/
│           ├── statusline_enhanced.sh  # Rich statusline for Catppuccin theme
│           └── template-sync.sh        # Upstream template sync
├── klaude-plugin/                    # Canonical plugin source (Claude Code)
│   ├── agents/
│   │   ├── code-reviewer.md
│   │   ├── design-reviewer.md
│   │   ├── eval-grader.md
│   │   ├── profile-resolver.md
│   │   └── spec-reviewer.md
│   ├── commands/
│   │   ├── chain-of-verification/   # default + isolated
│   │   ├── migrate-from-taskmaster/
│   │   ├── review-code/             # default + isolated
│   │   ├── review-spec/             # default + isolated
│   │   └── template/
│   ├── hooks/
│   │   └── hooks.json               # PreToolUse Bash validator
│   ├── profiles/
│   │   ├── go/, java/, js_ts/, kotlin/, k8s/, k8s-operator/, python/, skill-md/
│   ├── scripts/
│   │   └── validate-bash.sh         # Bash pre-validation hook script
│   └── skills/
│       ├── _shared/                 # DRY shared instructions (symlinked into consuming skills)
│       ├── chain-of-verification/
│       ├── dependency-handling/
│       ├── design/                  # SKILL.md, idea-process.md, refinement-criteria.md, frameworks.md, evals/, shared-capy-knowledge-protocol.md, shared-profile-detection.md
│       ├── diff-skill/
│       ├── document/
│       ├── implement/
│       ├── merge-docs/
│       ├── review-code/
│       ├── review-design/
│       ├── review-spec/
│       └── test/
├── kodex-plugin/                    # Auto-generated Codex output (from klaude-plugin/)
├── .codex/                          # Codex config
│   ├── config.toml
│   ├── hooks.json
│   ├── rules/default.rules
│   ├── scripts/
│   └── agents/*.toml                # Auto-generated from klaude-plugin/agents/*.md
├── .agents/                         # Project-level agent definitions
├── .capy.toml                       # Capy config: store.path = ".capy/knowledge.db"
├── .capy/                           # Knowledge store
│   └── knowledge.db                 # SQLite (BM25 indexed)
├── .mcp.json                        # MCP server wiring for Capy
├── cmd/
│   └── generate-kodex/              # Go tool: klaude-plugin → kodex-plugin transformer
├── test/
│   ├── helpers.sh
│   ├── test-plugin-structure.sh
│   ├── test-codex-structure.sh
│   └── test-template-sync.sh
├── docs/wip/                        # Feature design docs + task files (generated by /kk:design)
├── examples/                        # Real workflow execution examples
├── go.mod, go.sum                   # Go module (generate-kodex tool)
├── requirements.txt                 # Python dependencies (Capy)
├── Makefile                         # Targets: generate-kodex, sync-template, test
├── CLAUDE.md                        # Repo guidance for Claude
├── AGENTS.md                        # Repo guidance for Codex
└── mkdocs.yml                       # Documentation site (serpro69.github.io/claude-toolbox/)

Component Deep-Dives

klaude-plugin/skills/design/ — Most Elaborate Skill

Contains:

• SKILL.md — main skill definition
• idea-process.md — step-by-step idea intake workflow
• existing-task-process.md — variant for pre-existing tasks
• refinement-criteria.md — how to evaluate and refine ideas
• frameworks.md — design framework references
• evals/ — evaluation rubrics
• shared-capy-knowledge-protocol.md — symlink to shared Capy integration protocol
• shared-profile-detection.md — symlink to shared profile detection instructions
• example-tasks.md — example task format

Capy MCP Server

Capy provides context-window-aware knowledge retrieval:

• BM25 search across the knowledge database
• SQLite persistence at .capy/knowledge.db — survives across sessions
• Sandboxed subprocess — blocks curl/wget (prevents exfiltration)
• capy_fetch_and_index — fetch a URL and index its content into knowledge.db
• capy_search — BM25 search over indexed knowledge
• capy_execute / capy_batch_execute — execute queries against the store

The knowledge base accumulates findings, decisions, and conventions that skills write during execution. Later invocations can query prior context via capy_search.

validate-bash.sh

PreToolUse hook that validates Bash commands before execution. Similar in intent to zbruhnke-cc-starter's validate-bash.sh but delivered via plugin hooks rather than project-level hooks.json.

cmd/generate-kodex/

Go binary that transforms klaude-plugin/ content into Codex-compatible form:

• Resolves ${CLAUDE_PLUGIN_ROOT} variable (Claude Code-specific)
• Rewrites /kk: prefix → $kk: (Codex convention)
• Converts .md agent files to .toml format
• Injects Codex-required headers

CI check: make generate-kodex && git diff --exit-code kodex-plugin/ .codex/agents/ fails if generated output is out of sync.

Catppuccin Statusline

statusline_enhanced.sh renders a rich terminal statusline with Catppuccin theme. Configured via:

• CLAUDE_STATUSLINE_THEME: "catppuccin"
• CLAUDE_STATUSLINE_MODE: "dark"

The statusline is invoked on every Claude Code prompt via settings.json > statusLine.command.

serpro69/claude-toolbox — Uniqueness Assessment

Tier Assessment: A (Genuinely Novel)

Top 5 Unique Traits

1. Cross-Provider Code Generation via Go Tooling

klaude-plugin/ is the canonical source for both Claude Code and Codex. A Go binary (cmd/generate-kodex/) transforms the Claude Code plugin format into Codex-compatible output:

• ${CLAUDE_PLUGIN_ROOT} variable resolved
• /kk: skill prefix rewritten to $kk:
• Agent .md files converted to .toml
• CI enforces freshness: make generate-kodex && git diff --exit-code

No other framework in the batch or seeds maintains a single-source plugin that generates two different provider formats. This is a genuine DRY solution to the multi-provider problem — not "here are two parallel directories" but "one source, one generator, two outputs."

2. Language-Specific Profile System with Dynamic Detection

8 language profiles (go, java, js_ts, kotlin, k8s, k8s-operator, python, skill-md) with distinct instructions for implementation, testing, and code review. A dedicated profile-resolver agent detects the project's language at skill invocation time and injects the appropriate profile.

This is the most explicit language-specificity in the batch. Most frameworks provide generic instructions with brief language notes. serpro69 treats each language as a first-class citizen with its own review criteria.

3. Isolated Code Review via Command Variants (default.md / isolated.md)

The klaude-plugin/commands/<skill>/isolated.md pattern encodes bias isolation as an architectural choice: an independent code-reviewer sub-agent reviews code with zero authorship context. The /kk:review-code:isolated vs /kk:review-code distinction is the cleanest formalization of the "no-authorship-bias" review principle seen in the entire batch.

The isolated mode also supports routing to external Gemini models — making this a true multi-model review pipeline.

4. ELv2 License

The only ELv2-licensed framework in the batch (and in all 11 seeds). ELv2 prohibits using the toolkit as the basis for a hosted commercial SaaS product. This is an intentional statement: the author built this for development workflows, not to be resold as an AI developer platform.

5. Opinionated Anti-Sycophancy Behavioral Contract

CLAUDE.extra.md explicitly contracts: "If the user is wrong, say 'no, that's wrong' and explain why. Don't soften with 'have you considered' when you mean 'that won't work.'" Most frameworks use soft behavioral suggestions. serpro69's CLAUDE.extra.md reads like a professional engagement contract — no apologies, no softening, challenge wrong assumptions directly.

The Exploration Phase directive ("Always explore on your own to gain complete understanding. Only delegate to exploration agents if the user explicitly requests it") is uniquely motivated by measured economics: it prevents Claude from spawning exploration agents and then re-reading the same files, doubling token consumption.

Secondary Differentiators

• Catppuccin statusline with dark mode — the most aesthetically deliberate configuration in the batch
• skill description budget documented in CLAUDE.md — explicit per-skill 1,536-char cap + 1,024-char OpenCode portability guidance (probably the most technically detailed skill-authoring guide in the batch)
• Shared instruction symlinks (shared-<name>.md → ../_shared/<name>.md) — clever bundling-safe indirection for DRY skill instructions
• Template sync infrastructure (template-sync.sh) — keeps downstream projects updated without a full fork-rebase cycle
• Bash(rm:*) in deny permissions — the explicit block on rm as a default deny rule is unusually cautious
• mkdocs full documentation site at serpro69.github.io/claude-toolbox/ — professional-grade external docs for a 142-star project

What This Framework Gets Right That Others Don't

1. The pipeline is a loop, not a DAG. Implement calls review, which calls test, which calls document — skills compose recursively within the pipeline. Other frameworks list skills as independent primitives; serpro69's skills reference each other explicitly.

2. Knowledge accumulates to the project, not the session. Capy's SQLite is committed to the repo. The knowledge base grows with the project. This means a new developer onboarding to a project immediately has access to prior design decisions — not just code history.

3. Multi-model review is architecturally embedded (not a one-off trick). The code-reviewer agent's ability to route to Gemini is part of the review design, not a workaround.

Limitations

• ELv2 is a real barrier for teams wanting to build commercial products on top
• Capy knowledge base management — BM25 without decay means knowledge.db grows unbounded; no pruning strategy
• 11 skills is a curated minimum — teams with different workflows (e.g., no formal design phase, or async code review) may find the pipeline over-prescribed
• Go toolchain dependency for cross-provider generation — adds friction for non-Go teams contributing to the project itself