alex-feel/claude-code-toolbox — Summary

alex-feel/claude-code-toolbox is a YAML-declarative environment configuration framework for Claude Code that lets users define a complete development environment (agents, MCP servers, slash commands, hooks, skills, model settings, permissions, status line) in a single YAML file and install everything with one command across Windows, macOS, and Linux. Unlike all other starters in the batch that ship pre-built agent/command/skill sets, this framework is a meta-installer: it reads a YAML config pointing at a user-defined repository and installs whatever that config specifies. It ships Python scripts (setup_environment.py, install_claude.py), platform-specific shell/PowerShell scripts, and a comprehensive configuration guide. The YAML supports: base-url for remote resource resolution, configuration-inheritance (extend/override parent configs), dependency-management (apt/brew/choco), file-downloads, private repository support (GitHub/GitLab tokens), and all 4 Claude Code hook types (command, HTTP, prompt, agent).

differs_from_seeds: No seed ships a meta-installer framework — all seeds ship pre-built content. Most similar to agent-os (bash-bundle installer) but inverted: agent-os ships content + installs it; alex-feel ships the installer + reads user-defined content from a YAML. The YAML-driven environment definition (config.yaml → my-env global command) most closely resembles kiro's .kiro/ project configuration approach but for Claude Code. Configuration inheritance (extend parent configs) is a unique feature not present in any seed.

alex-feel/claude-code-toolbox — Overview

Origin

Published by alex-feel. 13 GitHub stars, MIT license, Python language. Last pushed 2026-04-15. 2 contributors.

Philosophy

From the README:

"Define your complete Claude Code environment in a single YAML file -- custom agents, MCP servers, slash commands, hooks, skills, model settings, and more -- and install everything with one command."

The framework addresses a specific pain point: Claude Code environment setup is manual, repetitive, and platform-dependent. By moving all configuration to a single YAML file with a base-url pointing at a remote repository, teams can share environments, version-control them, and install with one command regardless of platform.

YAML as Environment Spec

The YAML configuration is the central innovation. Example:

name: "My Development Environment"
command-names:
  - "my-env"
base-url: "https://raw.githubusercontent.com/my-org/my-configs/main"
agents:
  - "agents/code-reviewer.md"
slash-commands:
  - "commands/review.md"
mcp-servers:
  - name: "context-server"
    transport: "http"
    url: "http://localhost:8000/mcp"
model: "sonnet"
effort-level: "high"
hooks:
  events:
    - event: "PostToolUse"
      matcher: "Edit|MultiEdit|Write"
      type: "command"
      command: "linter.py"

This creates a global my-env command that launches Claude Code with the specified configuration.

Four Hook Types

The YAML supports all 4 Claude Code hook types:

• command — shell scripts
• HTTP — webhooks
• prompt — LLM evaluation
• agent — subagent with tools

The HTTP and prompt hook types are unusual — most frameworks use only command hooks.

alex-feel/claude-code-toolbox — Architecture

Distribution

Standalone GitHub repository. Python-based installer.

Install Method

# Linux
export CLAUDE_CODE_TOOLBOX_ENV_CONFIG='https://raw.githubusercontent.com/org/repo/main/config.yaml' && \
curl -fsSL https://raw.githubusercontent.com/alex-feel/claude-code-toolbox/main/scripts/linux/setup-environment.sh | bash

# macOS
export CLAUDE_CODE_TOOLBOX_ENV_CONFIG='https://raw.githubusercontent.com/org/repo/main/config.yaml' && \
curl -fsSL https://raw.githubusercontent.com/alex-feel/claude-code-toolbox/main/scripts/macos/setup-environment.sh | bash

# Windows PowerShell
$env:CLAUDE_CODE_TOOLBOX_ENV_CONFIG='...' ; iex (irm '.../scripts/windows/setup-environment.ps1')

# Local file
export CLAUDE_CODE_TOOLBOX_ENV_CONFIG=./my-env.yaml && curl ... | bash

# Private GitHub/GitLab
export GITHUB_TOKEN='ghp_...' # or GITLAB_TOKEN

Directory Tree

alex-feel/claude-code-toolbox/
├── docs/
│   ├── cross-shell-launcher-architecture.md
│   ├── environment-configuration-guide.md
│   └── installing-claude-code.md
├── scripts/
│   ├── __init__.py
│   ├── hooks/                    (hook scripts)
│   ├── install_claude.py         (Claude Code installer)
│   ├── linux/
│   │   └── setup-environment.sh
│   ├── macos/
│   │   └── setup-environment.sh
│   ├── models/                   (model configuration)
│   ├── setup_environment.py      (main Python installer)
│   └── windows/
│       └── setup-environment.ps1
├── tests/
├── .github/
├── .markdownlint.json
├── .pre-commit-config.yaml
├── CITATION.cff
├── CLAUDE.md
└── pyproject.toml

Required Runtime

• Python 3 (for setup_environment.py)
• bash (Linux/macOS)
• PowerShell (Windows)
• Claude Code (installed by install_claude.py if not present)

YAML Config Keys (comprehensive)

name:                    # Environment name
command-names:           # Global command name(s)
base-url:                # Base URL for remote resources
agents:                  # List of agent file paths
slash-commands:          # List of command file paths
rules:                   # List of rule file paths
skills:                  # List of skill packages
mcp-servers:             # MCP server definitions (name, transport, url/command)
model:                   # Model selection
effort-level:            # Reasoning effort (low|medium|high|max)
command-defaults:
  system-prompt:         # System prompt file path
  mode:                  # append | replace
hooks:
  files:                 # Hook script files to install
  events:                # Hook event registrations
permissions:             # allow/deny/ask lists
dependencies:            # Platform-specific packages (apt/brew/choco)
downloads:               # Arbitrary files to download
configuration-inheritance:
  parent:                # Parent config URL to extend
  overrides:             # Per-key merge strategy
private-repo:
  provider:              # github | gitlab
  token-env:             # Env var containing token

alex-feel/claude-code-toolbox — Components

Note: This is a meta-installer, not a content framework

alex-feel-cc-toolbox does NOT ship pre-built agents, commands, skills, or hooks. It ships the installer that reads a user-defined YAML and fetches/installs whatever the YAML specifies.

Python Scripts (core)

• scripts/setup_environment.py — main installer; reads YAML config, downloads resources from base-url, assembles settings.json, creates global command, installs dependencies
• scripts/install_claude.py — installs Claude Code itself if not present on the system
• scripts/models/ — model configuration utilities

Platform Scripts

• scripts/linux/setup-environment.sh — Linux wrapper: sets env, runs Python installer
• scripts/macos/setup-environment.sh — macOS wrapper
• scripts/windows/setup-environment.ps1 — Windows PowerShell wrapper

Hook Scripts

• scripts/hooks/ — hook script utilities (not pre-built hooks; infrastructure for hook installation)

YAML Config Features

Configuration Inheritance

configuration-inheritance:
  parent: "https://raw.githubusercontent.com/org/base/main/base-env.yaml"
  overrides:
    agents: merge     # append parent's agents to mine
    model: replace    # my model overrides parent's

Allows building specialized environments from a base environment. No seed has this feature.

Private Repository Support

private-repo:
  provider: github  # or gitlab
  token-env: GITHUB_TOKEN

Fetches agents/commands/hooks from private repos using tokens.

Dependency Management

dependencies:
  apt: ["ripgrep", "fd-find"]
  brew: ["ripgrep", "fd"]
  choco: ["ripgrep"]

Platform-specific package installation as part of environment setup.

HTTP MCP Servers

mcp-servers:
  - name: "my-server"
    transport: "http"
    url: "http://localhost:8000/mcp"

All 3 MCP transports supported: stdio, SSE, HTTP.

Four Hook Types

hooks:
  events:
    - event: "PostToolUse"
      type: "command"       # shell script
      command: "linter.py"
    - event: "PreToolUse"
      type: "HTTP"          # webhook
      url: "http://..."
    - event: "Stop"
      type: "prompt"        # LLM evaluation
      prompt: "Summarize..."
    - event: "PostToolUse"
      type: "agent"         # subagent with tools
      agent: "quality-checker.md"

alex-feel/claude-code-toolbox — Uniqueness

differs_from_seeds

No seed ships a meta-installer framework. All seeds ship pre-built content (agents, commands, hooks). alex-feel-cc-toolbox inverts the model: it ships the installer that reads a user-defined YAML. The configuration inheritance feature (extend/override parent environments) is unique — no seed has a hierarchy of environment configs. The YAML effort-level key as a configuration parameter (not just a runtime flag) is an unusual design. The 4 hook types including HTTP webhooks and prompt (LLM evaluation) hooks are not present in any seed. The private-repo support (GitHub/GitLab token-based fetching) enables enterprise environment distribution without public repos. The closest conceptual parallel in the seeds is kiro's .kiro/ project configuration, but kiro is an IDE; this is a Claude Code meta-installer.

Positioning

Infrastructure tool for teams managing Claude Code environments at scale. The combination of YAML config + configuration inheritance + private repo support suggests enterprise team adoption where a DevOps engineer manages a shared base environment and developers extend it.

Observable Failure Modes

1. No pre-built content: Users must create their own YAML config and host their own agents/commands. High initial setup cost for inexperienced users.
2. base-url resolution: If the base-url repository changes path structures or goes down, all resource downloads fail.
3. HTTP hook type: Webhook hooks require the user to run a local HTTP server. Not a zero-setup feature.
4. Python dependency: setup_environment.py requires Python 3. On vanilla Windows, Python may not be present.
5. 13 stars: Low adoption signal. Maintenance uncertain.
6. No pre-built examples: The docs show YAML examples but no working reference environment is included in the repo.

Cross-References

• CITATION.cff suggests academic/research interest in this work
• cross-shell-launcher-architecture.md documents the technical design of cross-platform shell launchers