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.

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.

/analysis-process → /design-review → /implementation-process → /solid-code-review → /testing-process → /documentation-process

Out of the box you get:

• 10 workflow skills — a complete development pipeline invoked as /skill-name
• 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.

{
  "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/BeehiveInnovations/pal-mcp-server.git pal-mcp-server"
    ],
    "env": {
      "PATH": "/usr/local/bin:/usr/bin:/bin:$HOME/.local/bin",
      # see https://github.com/BeehiveInnovations/pal-mcp-server/blob/main/docs/configuration.md#model-configuration
      "DEFAULT_MODEL": "auto",
      # see https://github.com/BeehiveInnovations/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/BeehiveInnovations/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.

[!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 /analysis-process 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 `/design-review y