claude-toolbox

claude-toolbox is a collection of "tools" for all your agentic workflows (currently supports claude-code and codex!) — 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, always 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... ¯\_(ツ)_/¯

Why claude-toolbox?

Tools like Claude Code and Codex are powerful on their own, but LLMs don'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 and Codex 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 and Codex.

A structured development pipeline — 10 workflow skills with explicit multi-language support 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 /kk:<skill-name>, with many skills integrated with each other.
• Multi-language support — precise and distinct instructions from design, to implementation, to testing, to review for: go, java, js/ts, kotlin, kubernetes, and 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 — no template needed. → Plugin-Only Setup

Providers

claude-toolbox supports two AI coding providers:

| | Claude Code | Codex (OpenAI) | | --------------------------- | ----------------------------------- | ------------------------------------------------------ | | Skills | klaude-plugin/ (authored) | kodex-plugin/ (generated) | | Sub-agents | klaude-plugin/agents/*.md | .codex/agents/*.toml (generated) | | Project instructions | CLAUDE.md | AGENTS.md | | Behavioral instructions | .claude/CLAUDE.extra.md | .codex/scripts/session-start.sh | | Config | .claude/settings.json | .codex/config.toml | | Hooks | klaude-plugin/hooks/ | .codex/hooks.json | | Rules/Permissions | .claude/settings.json | .codex/rules/default.rules (Starlark) | | Plugin install | /plugin install kk@claude-toolbox | codex plugin marketplace add serpro69/claude-toolbox | | Template sync | Full support | .codex/ synced |

klaude-plugin/ is the canonical source of truth. The generate-kodex tool produces kodex-plugin/ and .codex/agents/ with all necessary transformations.

[!IMPORTANT] Codex known limitations:

• Plugin-only installs provide skills and profile content only — hooks, sub-agents, rules, and project config require template setup or adopting into an existing repo.
• PreToolUse hooks are only wired for Bash commands. apply_patch and MCP tool hooks are documented in ADR 0005 but not yet implemented.
• MCP servers (Context7, Serena, Pal) must be configured at the user level — they are not packaged in the plugin. See Codex MCP 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

MCP servers are configured at the user level (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.

Claude Code

[!NOTE] Add MCP servers to ~/.claude.json under the mcpServers key.

{
  "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.

[!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.

Codex MCP Setup

[!NOTE] MCP servers are added via codex mcp add and stored in ~/.codex/config.toml. Capy is already configured at the project level in .codex/config.toml — no user setup needed.

# Context7 — streamable HTTP, no API key env var needed (key is in the URL header)
codex mcp add context7 --url "https://mcp.context7.com/mcp"

# Serena — stdio server via uvx
codex mcp add