Claude Code Toolbox

Overview

Claude Code Toolbox is a cross-platform installer and YAML-based environment-configuration framework for Claude Code, Anthropic's AI coding assistant. The toolbox lets you describe everything a Claude Code environment needs — custom agents and subagents, MCP servers, slash commands, hooks, skills, system prompts, rules, permissions, model defaults, and platform-specific dependencies — as a single declarative YAML file, and install the whole setup with one command on Windows, macOS, or Linux.

The full source is on GitHub under the MIT license, and the project ships a companion library of reusable Claude Code artifacts for users who want working building blocks to start from.

The Problem

Claude Code is powerful precisely because you can extend it: custom agents for specialized workflows, slash commands for the things you do every day, hooks that run on specific events, MCP servers that give the assistant access to your tools and knowledge, skills that package multi-file capabilities, and rules that shape how Claude behaves in your codebase. But that power comes with a fragmentation cost.

By summer 2025, I had accumulated a growing collection of Claude Code artifacts — subagents, slash commands, hooks, system prompts, and skills — and was hitting the same friction every time I set up a new machine or a new teammate joined:

• Moving the setup between machines was manual and error-prone. Copying the right files into the right directories, installing the right shell tools, wiring up MCP servers, and remembering which permissions to allow added up to a long, undocumented checklist.
• Reproducing a specific setup was unreliable. There was no single artifact you could point at and say "this is the environment" — the environment lived in scattered dotfiles, manual notes, and tribal knowledge.
• Central updates didn't exist. Once a teammate had copied a hook or an agent from me, my improvements to that file never propagated back. Everyone ended up running a slightly different version of everything.

While building agentic systems on top of Claude Code, the cost of this fragmentation grew sharply: multi-agent workflows depend on a coherent, versioned set of agents, hooks, and MCP servers — and maintaining that coherence by hand across machines stopped being tractable.

I wanted one file that described a complete Claude Code environment, and one command that installed it.

The Solution

Claude Code Toolbox introduces the concept of an environment configuration — a single YAML file that captures every Claude Code artifact and setting the environment needs:

• Agents and subagents — specialized Claude Code personas downloaded to ~/.claude/agents/.
• Slash commands — custom workflows placed in ~/.claude/commands/.
• Rules — user-scope coding-standard and policy files under ~/.claude/rules/.
• Skills — multi-file skill packages under ~/.claude/skills/<name>/.
• MCP servers — HTTP, SSE, and stdio transports, with automatic permission pre-allowing.
• Hooks — four hook types (shell command, HTTP webhook, LLM-prompt evaluation, full subagent-with-tools) wired into Claude Code events.
• System prompts — replace or append to Claude Code's default prompt.
• Permissions, model defaults, effort level, status line, and direct settings.json / ~/.claude.json control — everything that shapes how Claude behaves.
• Platform-specific dependencies — apt, brew, choco, and more, declared per OS.
• Configuration inheritance — a child config can inherit a parent and selectively override keys, so teams can share a base configuration and layer on per-role customizations without copy-pasting.

One command on each platform — a single PowerShell or curl-bash one-liner — points the toolbox at a YAML config URL (or local file, or private-repo path with GitHub/GitLab token auth) and installs Claude Code itself plus everything the config describes. Re-running the same command later picks up changes to the hosted config, so "central updates" are simply "update the YAML in the repo, tell people to rerun."

For the full schema — every YAML key, authentication patterns, inheritance rules, merge semantics, and security considerations — see the environment configuration guide. For standalone Claude Code installation (just the CLI, without a custom environment config), see the installing Claude Code guide, which documents the native-installer-with-npm-fallback chain, version pinning, and recovery cascade the toolbox uses under the hood.

Usage and Adoption

• Public GitHub repository at alex-feel/claude-code-toolbox under the MIT license, with CI/CD and release automation via Release Please.
• Actively developed — a fast release cadence driven by real use; features land as soon as they prove useful in practice.
• Cross-platform parity — the same YAML config works on Windows (PowerShell, CMD, Git Bash), macOS (bash, zsh, fish), and Linux (bash, zsh, fish).
• Companion artifacts repository at alex-feel/claude-code-artifacts-public publishes ready-made Claude Code artifacts — skills, hooks, and more — that anyone can reference from an environment config and install with the one-liner straight from GitHub.
• Used as the delivery mechanism for AEGIS — the curated multi-agent Claude Code environment I build and use on top of it — so the toolbox gets exercised end-to-end every time I ship an agent-facing project.

Why I Built It

The direct trigger was simple: by mid-2025, I was actively using Claude Code across multiple machines and projects, and I was building multi-agent workflows on top of it. Both trends pointed at the same unmet need — a way to describe a complete Claude Code environment declaratively and install it reproducibly. Once the environment concept was in place, it solved a class of problems at once: machine-to-machine portability, reproducibility across teammates, central updates to shared artifacts, and a clean substrate for agent-system work that needs a coherent set of agents, hooks, and MCP servers to operate on.

The project stays open-source and under an MIT license because the Claude Code artifact ecosystem benefits from shared infrastructure. The more people who can define, share, and install environments the same way, the healthier the agent-tooling landscape becomes.

My Role

I designed, built, and maintain Claude Code Toolbox end-to-end as a solo open-source project — the Python installers and setup scripts, the YAML schema and the Pydantic validation layer, the native-with-npm-fallback Claude Code installer, the cross-platform one-liners, the configuration-inheritance and deep-merge semantics, the hook wiring and MCP-server registration logic, the pytest suite (including E2E coverage), and the release automation. It lives on my personal GitHub under an MIT license, and I accept issues and contributions from the wider Claude Code community.