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.
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
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
- 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
- Context7 API key — for library documentation lookups
- Gemini API key for Pal (or any other provider) — for multi-model code review
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:
- Serena (no API key needed) — semantic code analysis via LSP. Works immediately after setup.
- Context7 (needs API key) — up-to-date library documentation and code examples.
- Pal (needs API key) — multi-model AI integration for code review, debugging, planning, and security audit.
- Capy (optional, auto-configured by bootstrap) — persistent knowledge base across sessions. Install with
brew install serpro69/tap/capy.
Example mcpServers configuration
{
"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.
-
Create a new project from this template using the Use this template button.
-
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.shInteractive 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-
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. -
Finalize initialization:
chmod +x .github/scripts/bootstrap.sh && ./.github/scripts/bootstrap.shThis installs the kk plugin, wires up the Capy knowledge base (if installed), and commits the configuration.
-
Recommended: Run
/configin 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.
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.
After setup, try the core workflow:
-
Start with an idea. Type
/analysis-processand 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 indocs/wip/. -
Review the design. Run
/design-review your-featureto catch gaps before writing code. -
Build it. Type
/implementation-process— Claude executes the task list with code review checkpoints between batches. -
Review the code.
/solid-code-reviewchecks for SOLID violations, security risks, and quality issues. Use/solid-code-review:isolatedfor 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.
Four servers provide complementary capabilities:
| Server | Purpose |
|---|---|
| Context7 | Up-to-date library documentation and code examples |
| Serena | Semantic code analysis via LSP — symbol navigation, reference tracking, targeted reads |
| Pal | Multi-model AI integration — chat, debugging, code review, planning, security audit |
| Capy | Persistent knowledge base — cross-session project memory with FTS5 search |
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: analysis-process, implementation-process, testing-process, documentation-process, development-guidelines, solid-code-review, implementation-review, design-review, merge-docs, cove (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.
- 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 insettings.local.json. - Status line (
.claude/scripts/statusline_enhanced.sh) — rich statusline with model, context %, git branch, session duration, thinking mode, and rate limits. Themes: setCLAUDE_STATUSLINE_THEMEtodarcula,nord, orcatppuccin, andCLAUDE_STATUSLINE_MODEtodark(default) orlightto match your terminal background - Serena config (
.serena/project.yml) — language detection, gitignore integration, encoding settings
- 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
Tip
Configure via claude /config. The config file is usually at ~/.claude.json.
This is my current config, tweaked for best results. I can't recommend enough disabling auto-compact — I've seen many a time claude starting to compact conversations in the middle of a task, which produces very poor results for the remaining work it does after compacting.
Full /config settings
> /config
────────────────────────────────────────────────────────────
Configure Claude Code preferences
Auto-compact false
Show tips true
Reduce motion false
Thinking mode true
Prompt suggestions true
Rewind code (checkpoints) true
Verbose output false
Terminal progress bar true
Default permission mode Default
Respect .gitignore in file picker true
Auto-update channel latest
Theme Dark mode
Notifications Auto
Output style default
Language Default (English)
Editor mode vim
Show code diff footer true
Show PR status footer true
Model opus
Auto-connect to IDE (external terminal) false
Claude in Chrome enabled by default false
Repos created from this template can pull configuration updates via the Template Sync workflow.
Note
Claude Code settings are split between two project-scoped files:
.claude/settings.json— upstream-managed defaults, synced from this template (permissions baseline, env vars, model, plugins, statusline).claude/settings.local.json— your per-repo overrides, never synced (hooks, MCP server enables, additional permissions, personal preferences)
You can edit settings.json directly if you like, they will be intelligently merged with this repo's settings, but the general advice is to place your customizations in settings.local.json. As an added bonus, "Don't ask again" grant prompts in claude-code sessions land in local settings automatically (as of v2.1.92).
.github/template-state.jsonmust exist (created automatically for new repos, or manually for older ones)- Allow actions to create pull-requests: repo Settings → Actions
- Go to Actions → Template Sync → Run workflow
- Choose a version:
latest(default),master, or a specific tag (e.g.,v1.2.3) - Optionally enable dry_run to preview changes without creating a PR
- Review and merge the created PR
- Merge to apply updates
Updated: .claude/ (settings, CLAUDE.extra.md, statusline scripts), .serena/, and the sync infrastructure itself. Skills, commands, and hooks are managed by the plugin system — not template sync.
Preserved: Project-specific values (name, language, prompts), settings.local.json, gitignored files
settings.json merge behavior: The sync uses smart-merge semantics — your downstream settings.json is "master" and upstream fills gaps:
- New keys from upstream are added (e.g., new deny patterns, new env vars)
- Existing values are never overwritten (your customizations are preserved)
- Arrays are concatenated with deduplication (e.g., new upstream deny rules are appended)
- Manifest variables (
CC_MODEL,CC_EFFORT_LEVEL, etc.) still override after the merge — these are your explicit choices
If you've removed template files you don't need, prevent sync from re-adding them:
Edit .github/template-state.json and add a sync_exclusions array:
{
"schema_version": "1",
"upstream_repo": "serpro69/claude-toolbox",
"template_version": "v0.2.0",
"synced_at": "2025-01-27T10:00:00Z",
+ "sync_exclusions": [
+ ".claude/CLAUDE.extra.md",
+ ".claude/settings.json"
+ ],
"variables": { "..." : "..." }
}Pattern syntax:
- Patterns use glob syntax where
*matches any characters including directory separators - Patterns are matched against project-relative paths (e.g.,
.claude/settings.json) - Common patterns:
.claude/CLAUDE.extra.md(single file),.serena/*(entire directory)
Behavior:
- Excluded files are NOT added if they exist upstream but not locally
- Excluded files are NOT updated if they exist in both places
- Excluded files are NOT flagged as deleted if they exist locally but not upstream
- Excluded files appear as "Excluded" in the sync report for transparency
Task Master MCP was removed in favor of native markdown-based task tracking integrated into the analysis-process and implementation-process skills.
The easiest way to migrate is to run the migration command in Claude Code:
/kk:migrate-from-taskmaster:migrate
It will port pending tasks, clean up TM files, update configs, and walk you through each step with confirmation prompts.
Manual migration steps
If you prefer to migrate manually, follow these steps after syncing:
-
Port any pending tasks to the new format: create
/docs/wip/[feature]/tasks.mdfiles following the example task file. Completed tasks don't need porting. -
Remove Task Master files and config:
rm -rf .taskmaster rm -rf .claude/commands/tm rm -f .claude/TM_COMMANDS_GUIDE.md rm -f .claude/agents/task-orchestrator.md rm -f .claude/agents/task-executor.md rm -f .claude/agents/task-checker.md
-
Remove Task Master from
~/.claude.json: delete thetask-master-aientry from yourmcpServersconfig. -
Remove TM variables from
.github/template-state.json: deleteTM_CUSTOM_SYSTEM_PROMPT,TM_APPEND_SYSTEM_PROMPT, andTM_PERMISSION_MODEfrom thevariablesobject. -
Remove TM references from
CLAUDE.md: delete the "Task Master Integration" and "Task Master AI Instructions" sections (including the@./.taskmaster/CLAUDE.mdimport). -
Update the template-sync workflow (why?): the old workflow contains taskmaster-specific sync logic that will break future syncs. Run
/kk:sync-workflow:sync-workflow latestor manually replace both files:VERSION="v0.3.0" # or use latest tag curl -fsSL "https://raw.githubusercontent.com/serpro69/claude-toolbox/${VERSION}/.github/workflows/template-sync.yml" \ -o .github/workflows/template-sync.yml curl -fsSL "https://raw.githubusercontent.com/serpro69/claude-toolbox/${VERSION}/.github/scripts/template-sync.sh" \ -o .github/scripts/template-sync.sh chmod +x .github/scripts/template-sync.sh
Task tracking now lives in simple markdown files (/docs/wip/[feature]/tasks.md) created by the analysis-process skill and consumed by implementation-process. No external MCP server required.
Skills and commands have moved from the template to the kk plugin:
- Skills remain unprefixed:
/analysis-process(annotated with(kk)in the menu) - Commands are now namespaced:
/project:cove→/kk:cove:cove - The template-sync workflow handles migration automatically on next sync
- After merging the sync PR, run
/plugin install kk@claude-toolbox
You don't need to create a repo from this template to use the full configuration and sync infrastructure. Any existing repo can adopt it:
-
Install the kk plugin to get all skills, commands, and hooks:
/plugin install kk@claude-toolbox -
Set up sync infrastructure. Create
.github/template-state.json:{ "schema_version": "1", "upstream_repo": "serpro69/claude-toolbox", "template_version": "v1.0.0", "synced_at": "1970-01-01T00:00:00Z", "variables": { "PROJECT_NAME": "my-cool-project", "LANGUAGES": "go", "CC_MODEL": "default", "SERENA_INITIAL_PROMPT": "" } }Copy
.github/workflows/template-sync.ymland.github/scripts/template-sync.shfrom the template repository. -
Run Template Sync from your repo's Actions tab to pull in the configuration (settings, Serena config, statusline, permissions). Review and merge the PR.
Tip
Step 1 works standalone if you only want the skills. Steps 2-3 add the opinionated configuration and keep it in sync with upstream improvements.
Tests across 5 suites cover the plugin structure, template sync/cleanup infrastructure:
# Run all test suites
for test in test/test-*.sh; do $test; done
# Run individual suites
./test/test-plugin-structure.sh # Plugin manifest, skills, commands, hooks validation
./test/test-template-sync.sh # template-sync.sh function tests + plugin migration
./test/test-template-cleanup.sh # generate_manifest() tests
./test/test-claude-extra.sh # CLAUDE.extra.md detection and auto-import
./test/test-manifest-jq.sh # jq JSON pattern tests| Test Suite | Coverage |
|---|---|
| test-plugin-structure.sh | Plugin/marketplace manifests, skills, commands, hooks, cross-refs |
| test-template-sync.sh | CLI parsing, manifest validation, substitutions, plugin migration |
| test-template-cleanup.sh | Manifest generation, variable capture, git tag/SHA detection |
| test-claude-extra.sh | CLAUDE.extra.md existence, compare_files detection, auto-import |
| test-manifest-jq.sh | JSON generation, special character handling, round-trip validation |
klaude-plugin/ # kk plugin (distributed via plugin system)
├── .claude-plugin/plugin.json # Plugin manifest
├── skills/ # 10 development workflow skills
├── commands/ # 4 slash commands
├── hooks/hooks.json # Bash validation hook config
└── scripts/validate-bash.sh # Hook script
.claude-plugin/marketplace.json # Marketplace catalog
.claude/
├── CLAUDE.extra.md # Always-loaded instructions
├── settings.json # Upstream-managed: permissions baseline, env, model, plugins
├── settings.local.json # Per-repo: hooks, MCP enables, additional permissions
└── scripts/ # statusline.sh, statusline_enhanced.sh, sync-workflow.sh
.serena/
└── project.yml # Serena LSP configuration
.github/
├── scripts/ # template-cleanup.sh, template-sync.sh, bootstrap.sh
├── workflows/ # template-cleanup, template-sync
└── template-state.json # Sync manifest and variables
test/
├── helpers.sh # Shared test utilities and assertions
├── test-*.sh # 5 test suites
└── fixtures/ # Test manifests and templates
Examples of actual Claude Code workflows executed using this template's configs, skills, and tools: examples/
Feel free to open new PRs/issues. Any contributions you make are greatly appreciated.
Copyright © 2025 - present, serpro69
Distributed under the ELv2 License.
See LICENSE.md file for more information.