A Claude Code orchestration framework with specialized AI agents, GitHub integration, and modern Python tooling for building robust software projects.

• Modern Python project structure (src layout)
• Fast dependency management with UV
• Comprehensive testing with pytest
• Code quality with Ruff (linting & formatting)
• Type checking with mypy
• Pre-commit hooks for automated checks
• GitHub Actions CI/CD pipeline
• Multi-Python version testing with tox
• 12 specialized AI agents for different development roles
• GitHub integration commands (PR creation, issue solving)
• Project context maintenance skill for agents

• Global guidelines for Claude Code
  • You can provide Claude Code with global project-agnostic guidelines
  • In this example, this global CLAUDE.md contains guidelines how it should organize and orchestrate itself
  • To provide your local Claude Code with those guidelines, all the files from the folder HOME_DIR_FILES must be copied to your home directory
  • On macOS, that would be ~/.claude
  • On Windows, it's C:\Users<your-username>.claude
• Project-specific guidelines for Claude Code live inside the CLAUDE.md in this repository.
• In .claude/agents you can see how you can set up individual agents, which Claude Code can spawn if necessary.
• In .claude/skills you can see how to set up skills which the agents can use.
• In .claude/commands you set up your own slash commands which YOU as user can use via the Claude Code CLI to run repetitive workflows.
  • Before starting slash commands, evaluate whether you want to run them in plan mode or act mode.
  • You can e.g. run /plan-to-issues to let Claude Code create several Github issues and epics based on a plan file it has created.
• Important configurations in settings.json
  • You can set up global project-agnostic settings.json in your home directory (like described above)
  • And you can set up project-specific settings.json in this project repo (.claude/settings.json)
  • Permissions: Configure what kind of bash commands Claude Code is allowed to run
  • Default Mode: Define the default mode (plan or act) which will be selected when starting the Claude Code CLI
  • Hooks:
    • Hooks are extremely important for Claude Code
    • With hooks, you can provide Claude Code with automated feedback right after its actions / tool use (e.g., linting or testing right after writing code).
    • Hooks can also be used to enforce a certain behavior while starting Claude Code or when Claude Code thinks it has completed the task.
• To provide Claude Code with the Specs of the solution you would like to build, fill out SPEC.md

This framework includes 12 specialized agents in .claude/agents/ for different development tasks:

The framework provides GitHub integration commands in .claude/commands/:

• Python 3.12+
• UV (recommended) or pip

# Clone the repository
git clone https://github.com/jfabend/claude_code_setup.git
cd claude_code_setup

# Install UV (if not already installed)
# On macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
# On Windows:
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Create virtual environment and install dependencies
uv sync --dev

# Install pre-commit hooks
uv run pre-commit install

# Run tests
uv run pytest

# Run tests with coverage
uv run pytest --cov

# Run linting
uv run ruff check .

# Run formatting
uv run ruff format .

# Run type checking
uv run mypy src

# Run all checks (like CI)
uv run tox

# Run only unit tests
uv run pytest -m unit

# Run only integration tests
uv run pytest -m integration

# Run only e2e tests
uv run pytest -m e2e

# Skip slow tests
uv run pytest -m "not slow"

claude_code_setup/
├── .claude/
│   ├── agents/               # 12 specialized AI agents
│   ├── commands/             # GitHub integration commands
│   └── skills/               # Project context maintenance
├── src/claude_code_setup/    # Source code
│   ├── core/                 # Core functionality
│   └── utils/                # Utility functions
├── tests/                    # Test suite
│   ├── unit/                 # Unit tests
│   ├── integration/          # Integration tests
│   └── e2e/                  # End-to-end tests
└── docs/                     # Documentation

See CONTRIBUTING.md for guidelines.

This project is licensed under the MIT License - see the LICENSE file for details.