claude-toolbox

claude-toolbox is a collection of "tools" for all your Claude Code workflows — pre-configured MCP servers, skills, sub-agents, commands, hooks, statuslines with themes, and more - everything you need for AI-powered development workflows, used and battle-tested daily on many of my own projects.

[!IMPORTANT] This project was created with the help of Claude-Code. Is it, however, reviewed, tested, and reworked with a human-in-the-loop.

No AI slop here. Purely AI-made skills are hot garbage, and that's putting it mildly.

That said, if you have any problems with code that is written by AI - you've been warned. But, then again, why would you be interested in AI-related configs and skills in the first place... ¯\\_(ツ)_/¯

<img width="3440" height="521" alt="image" src="https://github.com/user-attachments/assets/27ef7269-0153-47c0-b07d-ed6a9504a176" />

Why claude-toolbox?

Claude Code is powerful on its own, but it doesn't know your development workflow. This project started as a way for me to streamline claude configurations across all my projects without needing to copy-paste things. With time, patterns and re-curring prompts evolved into skills and agents. Currently, claude-toolbox gives you two things:

A minimal, opinionated Claude Code configuration — sensible permission baselines, a rich statusline, Serena LSP integration, MCP server wiring, and sync infrastructure to keep it all up to date across your projects. Think of it as a dotfiles repo for Claude Code.

A structured development pipeline — 10 workflow skills that take you from idea through design, implementation, code review, testing, to documentation, with persistent knowledge that carries across sessions.

/design → /review-design → /implement → /review-code → /test → /document

Out of the box you get:

• 10 workflow skills — a complete development pipeline invoked as /skill-name
• Multi-language support — precise and distinct instructions from implementation to testing to review for: go, java, js/ts, kotlin, python
• Multi-model code review — independent reviewers using sub-agents and external models (Gemini, etc.)
• Semantic code analysis — LSP-powered symbol navigation and reference tracking via Serena
• Persistent knowledge base — findings, decisions, and conventions that survive across sessions via Capy
• Up-to-date library docs — always-current documentation lookup via Context7
• Battle-tested configuration — permissions, statusline themes, hooks, sensible defaults

Choose Your Path

Starting a new project? Use the template — you get the full configuration and plugin pre-wired, plus sync infrastructure to pull future updates. → Template Setup

Existing project, want the full setup? Adopt the configuration, plugin, and sync infrastructure without creating from the template. → Adopting into Existing Repositories

Just want the skills? Install the kk plugin — all 10 skills, commands, and hooks in one command. No template needed. → Plugin-Only Setup

Requirements

• Claude Code — the AI coding assistant this toolbox extends
• npm — used by some MCP server installations
• uv — Python package runner for Serena and Pal MCP servers
• jq — JSON processor, required for template-cleanup

API Keys

• Context7 API key — for library documentation lookups
• Gemini API key for Pal (or any other provider) — for multi-model code review

MCP Server Configuration

[!NOTE] MCP servers must be configured in ~/.claude.json (not in the repo) to keep API keys safe. These configs are generic enough to reuse across all your projects.

You don't need all servers to get started. Add them incrementally:

1. Serena (no API key needed) — semantic code analysis via LSP. Works immediately after setup.
2. Context7 (needs API key) — up-to-date library documentation and code examples.
3. Pal (needs API key) — multi-model AI integration for code review, debugging, planning, and security audit.
4. Capy (optional, auto-configured by bootstrap) — persistent knowledge base across sessions. Install with brew install serpro69/tap/capy.

<details> <summary>Example <code>mcpServers</code> configuration</summary>

{
  "context7": {
    "type": "http",
    "url": "https://mcp.context7.com/mcp",
    "headers": {
      "CONTEXT7_API_KEY": "YOUR_CONTEXT7_API_KEY"
    }
  },
  "serena": {
    "type": "stdio",
    "command": "uvx",
    "args": [
      "--from",
      "git+https://github.com/oraios/serena",
      "serena",
      "start-mcp-server",
      "--context",
      "ide-assistant",
      "--project",
      "."
    ],
    "env": {}
  },
  "pal": {
    "command": "sh",
    "args": [
      "-c",
      "$HOME/.local/bin/uvx --from git+https://github.com/serpro69/pal-mcp-server.git pal-mcp-server"
    ],
    "env": {
      "PATH": "/usr/local/bin:/usr/bin:/bin:$HOME/.local/bin",
      # see https://github.com/serpro69/pal-mcp-server/blob/main/docs/configuration.md#model-configuration
      "DEFAULT_MODEL": "auto",
      # see https://github.com/serpro69/pal-mcp-server/blob/main/docs/advanced-usage.md#thinking-modes
      "DEFAULT_THINKING_MODE_THINKDEEP": "high",
      "GEMINI_API_KEY": "YOUR_GEMINI_API_KEY",
      # see https://github.com/serpro69/pal-mcp-server/blob/main/docs/configuration.md#model-usage-restrictions
      "GOOGLE_ALLOWED_MODELS": "gemini-3.1-pro-preview,gemini-3-flash-preview"
    }
  }
}

See Pal configuration docs for model and thinking mode options.

</details>

[!TIP] If you're using my claude-in-docker images, consider replacing npx and uvx calls with direct tool invocations. The images come shipped with all of the above MCP tools pre-installed, and you will avoid downloading dependencies every time you launch claude cli.

  "serena": {
    "type": "stdio",
    "command": "serena",
    "args": [
      "start-mcp-server",
      "--context",
      "ide-assistant",
      "--project",
      "."
    ],
    "env": {}
  },
  "pal": {
    "command": "pal-mcp-server",
    "args": [],
    "env": { ... }
  }

You also may want to look into your env settings for the given mcp server, especially the PATH variable, and make sure you're not adding anything custom that may not be avaiable in the image. This may cause the mcp server to fail to connect.

Template Setup

1. Create a new project from this template using the Use this template button.

2. Initialize the template — choose one method:

   Option A: GitHub Actions (recommended)

   Go to your new repo's Actions tab → Template Cleanup → Run workflow. Provide:

   • LANGUAGES (required) — programming languages, comma-separated (e.g., python, python,typescript). See supported languages.
   • SERENA_INITIAL_PROMPT — initial prompt given to the LLM on project activation
   • Other inputs are optional with sensible defaults.

[!TIP] Take a look at serena project.yaml configuration file for more details.

Option B: Run locally

./.github/scripts/template-cleanup.sh

Interactive mode walks you through each option. Run with --help for all flags, or pass them directly:

./.github/scripts/template-cleanup.sh --languages python,typescript -y

3. Clone your repo (if using Option A) and verify MCP servers:

   > /mcp
   ╭────────────────────────────────────────────────────────────────────╮
   │ Manage MCP servers                                                 │
   │                                                                    │
   │ ❯ 1. context7                  ✔ connected · Enter to view details │
   │   2. serena                    ✔ connected · Enter to view details │
   │   3. pal                       ✔ connected · Enter to view details │
   ╰────────────────────────────────────────────────────────────────────╯
   

   The kk plugin (skills, commands, hooks) is available via the claude-toolbox marketplace configured in .claude/settings.json.

4. Finalize initialization:

   chmod +x .github/scripts/bootstrap.sh && ./.github/scripts/bootstrap.sh
   

   This installs the kk plugin, wires up the Capy knowledge base (if installed), and commits the configuration.

5. Recommended: Run /config in Claude Code and disable Auto-compact. This prevents Claude from compacting context mid-task, which degrades quality significantly. See Recommended Settings for the full config.

6. Try it out!

Plugin-Only Setup

Already have a project? Install just the kk plugin to get all skills, commands, and hooks:

/plugin install kk@claude-toolbox

That's it. All 10 skills are now available as /skill-name (annotated with (kk) in the slash command menu). See the kk plugin documentation for details.

[!TIP] Want the full configuration too (settings, statusline, Serena, sync infrastructure)? See Adopting into Existing Repositories. For MCP servers, see MCP Server Configuration and add the configs you want to ~/.claude.json.

Try It

After setup, try the core workflow:

1. Start with an idea. Type /design and describe a feature you want to build. Claude will ask you refinement questions one at a time, then produce design docs and a task list in docs/wip/.

2. Review the design. Run /review-design your-feature to catch gaps before writing code.

3. Build it. Type /implement — Claude executes the task list with code review checkpoints between batches.

4. Review the code. /review-code checks for SOLID violations, security risks, and quality issues. Use /review-code:isolated for independent sub-agent reviewers with zero authorship bias.

This is the core loop. See the kk plugin README for all available skills and the full workflow pipeline.

What's Included

MCP Servers

Four servers provide complementary capabilities:

Knowledge Base (Capy)

Skills are knowledge-aware via Capy. They search for relevant context before executing (architecture decisions, review findings, language idioms) and index valuable learnings after producing output. Knowledge persists across sessions per-project using an FTS5 full-text search index.

Without Capy, each session starts fresh — all skills still work, they just don't carry learnings forward. Install when you want cross-session memory.

Installation: brew install serpro69/tap/capy then run capy setup in your project directory. The bootstrap script sets up Capy automatically if the binary is on PATH.

kk Plugin (klaude-plugin/)

The kk plugin contains all development workflow functionality — 10 skills, 4 commands, and hooks — distributed via the Claude Code plugin system. Skills are invoked as /skill-name, commands as /kk:dir:command.

Includes: design, implement, test, document, development-guidelines, review-code, review-spec, review-design, merge-docs, chain-of-verification. Plus commands for CoVe, implementation review, design review, Task Master migration, and sync workflow updates. See the plugin README for full details.

Alongside skills/, commands/, agents/, and hooks/, the plugin ships a top-level profiles/ directory. Each profile (e.g., go, python, k8s) bundles per-domain content — detection rules, review checklists, design prompts, test validators, doc rubrics — that the workflow skills consult when the code under work matches the profile. Profiles are the extension point for new languages and IaC DSLs; see the Profile Conventions section of CLAUDE.md for the full authoring contract.

Configuration

• Permission allowlist/denylist (.claude/settings.json) — baseline permissions: auto-approves safe bash commands and WebSearch while blocking dangerous patterns. Per-repo MCP tool permissions go in settings.local.json.
• Status line (.claude/scripts/statusline_enhanced.sh) — rich statusline with model, context %, git branch, session duration, thinking mode, and rate limits. Themes: set CLAUDE_STATUSLINE_THEME to darcula, nord, or catppuccin, and CLAUDE_STATUSLINE_MODE to dark (default) or light to match your terminal background
• Serena config (.serena/project.yml) — language detection, gitignore integration, encoding settings

Template Infrastructure

• template-cleanup — GitHub Action or local CLI script to initialize a new repo from this template
• template-sync workflow — pull upstream configuration updates into your project via PR
• Sync exclusions — prevent specific files from being re-added during sync
• Test suite — 157 tests across 5 suites covering the plugin structure, sync/cleanup infrastructure

Recommended Settings

[!TIP] Configure via claude /config. The config file is usually at ~/.claude.json.

Thi