A ready-to-use .claude configuration for Python development projects with Claude Code. Includes curated agents, commands, skills, and MCP server templates.
Claude Code requires a Pro, Max, Teams, Enterprise, or Console account (the free Claude.ai plan does not include Claude Code access).
System requirements:
- macOS 13.0+ / Windows 10 1809+ / Ubuntu 20.04+ / Debian 10+
- 4 GB+ RAM
- Internet connection
- On Windows: Git for Windows is required
Installation:
# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash# Windows (PowerShell)
irm https://claude.ai/install.ps1 | iex# Windows (alternative: WinGet)
winget install Anthropic.ClaudeCodeAfter installation, navigate to your project directory and run claude to start. On first run, follow the browser prompts to authenticate.
Verify with:
claude --version
claude doctor # detailed checkFull documentation: code.claude.com/docs/en/setup
Some components require additional tools. Install only what you need:
| Dependency | Required by | Install |
|---|---|---|
| Node.js 18+ | context7, playwright MCP servers | nodejs.org |
| Python >= 3.10 + uv | postgres, docker MCP servers | docs.astral.sh/uv |
| Docker | docker MCP server | docker.com |
| PostgreSQL | postgres MCP server | Running instance (local or remote) |
| jq | hooks (enforce-uv, protect-main, auto-lint) | jqlang.github.io/jq |
| RTK | token optimization (recommended) | brew install rtk or install guide |
npxcomes with Node.js.uvxcomes with uv. No additional installs needed beyond the base tools.
Token savings tip: RTK (Rust Token Killer) is a CLI proxy that reduces token consumption by 60-90% on common dev commands (git, tests, build, lint). Run
rtk init -gto install a hook that automatically optimizes all shell commands in Claude Code sessions.
claude-code-python-setup/
├── .claude/
│ ├── agents/ # Specialized subagents
│ │ ├── architect.md
│ │ ├── code-architect.md
│ │ ├── code-explorer.md
│ │ ├── code-reviewer.md
│ │ ├── comment-analyzer.md
│ │ ├── database-reviewer.md
│ │ ├── planner.md
│ │ ├── pr-test-analyzer.md
│ │ ├── refactor-cleaner.md
│ │ ├── security-reviewer.md
│ │ ├── silent-failure-hunter.md
│ │ ├── tdd-guide.md
│ │ └── type-design-analyzer.md
│ ├── commands/ # Slash commands (/command-name)
│ │ ├── build-fix.md
│ │ ├── clean-gone.md
│ │ ├── code-review.md
│ │ ├── commit.md
│ │ ├── commit-push-pr.md
│ │ ├── feature-dev.md
│ │ ├── notebook-review.md
│ │ ├── orchestrate.md
│ │ ├── review-pr.md
│ │ ├── revise-claude-md.md
│ │ └── test-coverage.md
│ ├── hooks/ # Deterministic guardrails
│ │ ├── enforce-uv.sh # Block bare pip/python/pytest, suggest uv
│ │ ├── auto-lint.sh # Auto-format Python files with ruff after edits
│ │ └── protect-main.sh # Block force push, direct push to main, broad rm -rf
│ ├── rules/ # Modular coding standards
│ │ ├── api-patterns.md # FastAPI/Pydantic (path-scoped)
│ │ ├── architecture.md
│ │ ├── compaction.md
│ │ ├── documentation.md
│ │ ├── exception-handling.md
│ │ ├── git-workflow.md
│ │ ├── project-structure.md
│ │ ├── python-idioms.md
│ │ ├── security.md
│ │ └── testing.md
│ ├── settings.json # Project-level hooks, permissions, status line
│ ├── statusline.py # Status line script (Python, cross-platform)
│ └── skills/ # Reference docs and scripts
│ ├── api-design/
│ ├── claude-api/
│ ├── claude-automation-recommender/
│ ├── claude-md-improver/
│ ├── database-migrations/
│ ├── deployment-patterns/
│ ├── django-patterns/
│ ├── django-security/
│ ├── django-tdd/
│ ├── django-verification/
│ ├── doc-coauthoring/
│ ├── docker-patterns/
│ ├── docx/
│ ├── frontend-design/
│ ├── mcp-builder/
│ ├── pdf/
│ ├── playground/
│ ├── postgres-patterns/
│ ├── pptx/
│ ├── skill-creator/
│ ├── webapp-testing/
│ └── xlsx/
├── mcp_config/
│ ├── linux_mac.mcp.json # MCP server config (Linux/Mac)
│ └── windows.mcp.json # MCP server config (Windows)
├── .env.example # Environment variables template
├── .gitignore
├── .python-version # Python version pin for uv
├── CHANGELOG.md # Version history (Keep a Changelog format)
├── CLAUDE.md # Project instructions (< 200 lines, imports rules)
├── CODE_OF_CONDUCT.md # Contributor Covenant 2.1
├── CONTRIBUTING.md # How to contribute, setup, PR workflow
├── LICENSE # MIT License
├── pyproject.toml # Project metadata, ruff and pytest config
├── README.md
└── SECURITY.md # Vulnerability reporting policy
Copy the .claude/ directory and CLAUDE.md into the root of your project.
Then open CLAUDE.md and replace the <YOUR_OPERATIVE_SYSTEM> placeholder with your actual OS (e.g., Windows 11, macOS 15, Ubuntu 24.04).
Copy the appropriate MCP template to .mcp.json in your project root:
# Windows
cp mcp_config/windows.mcp.json .mcp.json
# Linux / Mac
cp mcp_config/linux_mac.mcp.json .mcp.json
.mcp.jsonis gitignored so each developer can use the template matching their OS.
Some components use environment variables for configuration. These must be system environment variables (Claude Code does not read .env files). See .env.example for all available variables and defaults.
# Linux / Mac — add to ~/.bashrc or ~/.zshrc
export POSTGRES_USER=myuser
export POSTGRES_PASSWORD=mypassword
export POSTGRES_HOST=localhost
export POSTGRES_PORT=5432
export POSTGRES_DB=mydb
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=85# Windows — via setx or System Properties > Environment Variables
setx POSTGRES_USER myuser
setx POSTGRES_PASSWORD mypassword
setx POSTGRES_HOST localhost
setx POSTGRES_PORT 5432
setx POSTGRES_DB mydb
setx CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 85| Variable | Used by | Default | Description |
|---|---|---|---|
POSTGRES_* |
postgres MCP server | see .env.example |
Database connection parameters |
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE |
Claude Code | 95 |
Context % threshold that triggers auto-compaction (lower = compacts earlier, reduces response time) |
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS |
Claude Code | 0 (disabled) |
Set to 1 to enable Agent Teams: multiple Claude instances working in parallel with inter-agent communication (docs) |
CLAUDE_CODE_NO_FLICKER |
Claude Code | 0 (disabled) |
Set to 1 to enable fullscreen rendering: flicker-free display, flat memory usage in long conversations, and mouse support. Research preview, requires v2.1.89+ (docs) |
Run /mcp inside Claude Code to check that all servers are connected.
CLAUDE.md is the project instructions file that Claude Code reads automatically at the start of every conversation. It defines the coding standards, conventions, and constraints that Claude must follow when working on your project.
Think of it as a persistent system prompt scoped to your codebase. It's always loaded — no manual invocation needed.
Key characteristics:
- Auto-loaded: Claude reads it at startup, before any user message
- Imports via
@path: use@.claude/rules/testing.mdto pull in modular rules without bloating the main file - Keep under 200 lines: long files waste context; extract details into rules
- Project-scoped: place in the project root for repo-wide instructions; nest in subdirectories for folder-specific overrides
This setup's CLAUDE.md contains project specs (OS, language, tools), naming conventions, file organization, common commands, and @import references to all rules.
Full documentation: code.claude.com/docs/en/memory
Rules are modular coding standards that extend CLAUDE.md without inflating it. Each rule is a standalone Markdown file focused on a single topic (testing, security, API patterns, etc.), imported into CLAUDE.md via @.claude/rules/<file>.md.
Rules are loaded into Claude's context at session start alongside CLAUDE.md, so they act as persistent instructions — not invoked on demand like skills or agents.
Key characteristics:
- Always in context: rules are loaded at startup and apply to every interaction
- Path-scoped (optional): add
pathsin YAML frontmatter to activate a rule only for matching file patterns (e.g.,api-patterns.mdonly forsrc/api/**/*.py) - One topic per file: keeps each rule focused and easy to update independently
- Referenced by agents: agents point to rules instead of duplicating standards (e.g., "see
.claude/rules/security.md")
Full documentation: code.claude.com/docs/en/memory
| Rule | Scope | Description |
|---|---|---|
| api-patterns | src/api/**/*.py |
FastAPI routers, Pydantic models, dependency injection |
| architecture | global | Layered architecture, modularity, dependency flow |
| compaction | global | What to preserve during context compaction |
| documentation | global | README, docstrings, type annotations, changelog |
| exception-handling | global | Custom exception hierarchy, catch-at-boundary pattern |
| git-workflow | global | Conventional Commits, branch naming, PR conventions |
| project-structure | global | src layout, module conventions, pydantic-settings config |
| python-idioms | global | Data structure selection, generators, match/case, explicit kwargs, unpacking |
| security | global | Secrets management, input validation, injection prevention |
| testing | global | pytest structure, coverage targets, fixtures, markers |
Hooks are deterministic guardrails that run automatically before or after Claude uses a tool. Unlike rules (which are advisory — Claude should follow them), hooks are enforced by the system — Claude cannot bypass them.
Each hook is a shell script triggered by a specific event. PreToolUse hooks can block an action before it happens; PostToolUse hooks run after a tool completes (e.g., to auto-format code). Hook configuration lives in .claude/settings.json.
Key characteristics:
- Deterministic: hooks always execute — they don't depend on Claude's interpretation
- Blocking:
PreToolUsehooks can return{"decision":"block","reason":"..."}to prevent an action - Composable: multiple hooks can run on the same event (e.g., enforce-uv + protect-main both run on Bash)
- Dependency: requires
jqfor JSON parsing of hook input
Full documentation: code.claude.com/docs/en/hooks
| Hook | Event | Description |
|---|---|---|
| enforce-uv | PreToolUse (Bash) |
Blocks bare pip, python, pytest, ruff, mypy, bandit — suggests uv run or uv add equivalents |
| auto-lint | PostToolUse (Edit|Write) |
Runs ruff check --fix and ruff format on Python files after every edit |
| protect-main | PreToolUse (Bash) |
Blocks git push --force, direct push to main/master, git reset --hard, broad rm -rf |
Pre-configured permission rules in .claude/settings.json control what Claude can and cannot access.
Allowed commands — auto-approved without prompting:
| Pattern | Description |
|---|---|
uv sync *, uv add *, uv remove * |
Dependency management |
uv run pytest *, uv run ruff *, uv run python * |
Test, lint, and run |
Denied reads — Claude is blocked from reading sensitive files:
| Pattern | Files protected |
|---|---|
.env, .env.{local,development,staging,production,test}, .envrc |
Environment variables (.env.example is allowed) |
secrets/** |
Secrets directory |
**/credentials*, **/secret* |
Credential and secret files |
**/*.pem, **/*.key, **/*.p12, **/*.pfx, **/*.jks |
Certificates and private keys |
**/*token* |
Token files |
~/.ssh/**, **/id_rsa*, **/id_ed25519*, **/id_ecdsa*, **/id_dsa* |
SSH keys |
These rules are enforced at the system level — Claude cannot bypass them regardless of the prompt. Customize by editing the permissions object in .claude/settings.json.
Full documentation: code.claude.com/docs/en/settings#excluding-sensitive-files
Agents are specialized AI subagents that run in their own context window with a custom system prompt, specific tool access, and independent permissions. When Claude encounters a task that matches an agent's description, it automatically delegates to that agent, which works independently and returns results.
Each agent is a Markdown file with YAML frontmatter (configuration) and a body (system prompt). Agents help preserve the main conversation context by isolating heavy tasks, and can enforce constraints like read-only access or specific tool sets.
Key characteristics:
- Automatic delegation: Claude uses the agent's
descriptionto decide when to delegate - Isolated context: each agent runs in its own context window, keeping verbose output out of the main conversation
- Configurable tools and model: agents can restrict tool access and use a different model (e.g., Haiku for speed)
- Cannot nest: subagents cannot spawn other subagents
Full documentation: code.claude.com/docs/en/sub-agents
| Agent | Description |
|---|---|
| architect | System design, ADRs, trade-off analysis, scalability planning |
| code-architect | Implementation blueprints: file plans, data flow, build sequence |
| code-explorer | Codebase tracing: execution paths, architecture mapping, dependency analysis |
| code-reviewer | Code quality, Python patterns, concurrency, FastAPI/Django/Flask checks |
| comment-analyzer | Code comment accuracy, completeness, and comment rot detection |
| database-reviewer | PostgreSQL schema, query optimization, and migration review |
| planner | Task decomposition and implementation planning |
| pr-test-analyzer | Test coverage quality: behavioral gaps, critical paths, edge cases |
| refactor-cleaner | Dead code detection, refactoring (vulture, ruff) |
| security-reviewer | Security audit (bandit, safety, pip-audit, OWASP Top 10) |
| silent-failure-hunter | Error handling audit: silent failures, catch blocks, fallback behavior |
| tdd-guide | Test-driven development with pytest |
| type-design-analyzer | Type design quality: encapsulation, invariants, enforcement ratings |
Skills extend what Claude can do. Each skill is a directory containing a SKILL.md file (with optional supporting files like templates, examples, or scripts). Claude loads skills automatically when relevant to the conversation, or you can invoke them directly with /skill-name.
Skills serve two purposes:
- Reference content: conventions, patterns, domain knowledge that Claude applies to your work (loaded inline)
- Task content: step-by-step workflows for specific actions like deployments or code generation
Key characteristics:
- Auto-discovery: Claude reads skill descriptions and loads them when relevant
- Invocation control:
disable-model-invocation: truemakes a skill user-only;user-invocable: falsemakes it Claude-only - Arguments: skills accept
$ARGUMENTSfrom the user (e.g.,/fix-issue 123) - Subagent execution: skills with
context: forkrun in an isolated subagent - Supporting files: a skill directory can include templates, examples, and scripts alongside
SKILL.md
Full documentation: code.claude.com/docs/en/skills
| Skill | Description |
|---|---|
| api-design | REST API design: resource naming, status codes, pagination, versioning |
| claude-api | Claude API and Anthropic SDK reference |
| claude-automation-recommender | Analyze codebases and recommend Claude Code automations (hooks, skills, MCP servers) |
| claude-md-improver | Audit and improve CLAUDE.md files: quality scoring, targeted updates |
| database-migrations | Safe zero-downtime migrations, reversible patterns (SQLAlchemy, Django, golang-migrate) |
| deployment-patterns | CI/CD pipelines, rolling/blue-green deployments, health checks, production readiness |
| django-patterns | Django architecture, DRF, ORM best practices, caching, signals, middleware |
| django-security | Django security: authentication, CSRF/XSS prevention, secure configuration |
| django-tdd | TDD with pytest-django, factory_boy, model/view/serializer testing |
| django-verification | Django pre-deployment verification: migrations, tests, security scans |
| doc-coauthoring | Structured documentation co-authoring workflow |
| docker-patterns | Docker/Compose: multi-container orchestration, networking, security hardening |
| docx | Word document creation and manipulation |
| frontend-design | Production-grade frontend interfaces (Django templates) |
| mcp-builder | Guide for creating MCP servers |
| PDF reading, merging, splitting, OCR | |
| playground | Interactive HTML playgrounds: visual controls, live preview, prompt output |
| postgres-patterns | PostgreSQL query optimization, schema design, indexing, RLS, connection pooling |
| pptx | PowerPoint presentation creation |
| skill-creator | Create and optimize new skills |
| webapp-testing | Web app testing with Playwright |
| xlsx | Spreadsheet creation and manipulation |
Commands are the legacy format for skills. A file at .claude/commands/review.md and a skill at .claude/skills/review/SKILL.md both create /review and work identically. Existing command files continue to work and support the same frontmatter as skills.
Skills are the recommended format because they support additional features (supporting files directory, auto-discovery by Claude). Commands are kept for simplicity when a single .md file is sufficient.
Full documentation: code.claude.com/docs/en/skills
| Command | Description |
|---|---|
/build-fix |
Incremental build/type error fixing with guardrails |
/clean-gone |
Clean up stale local branches marked as [gone] and their worktrees |
/code-review |
Multi-agent PR review with confidence scoring (0-100) and false positive filtering |
/commit |
Stage and create a git commit with contextual message |
/commit-push-pr |
One-command workflow: branch → commit → push → PR creation |
/feature-dev |
Guided 7-phase feature development with codebase exploration and architecture design |
/notebook-review |
Review Jupyter notebooks |
/orchestrate |
Multi-agent workflow: planner → tdd → code-review → security |
/review-pr |
Interactive PR review with formal GitHub decision (approve/request changes/comment) |
/revise-claude-md |
Capture session learnings and update CLAUDE.md |
/test-coverage |
Analyze coverage gaps, generate missing tests for 80%+ target |
MCP (Model Context Protocol) servers extend Claude Code with external tool integrations. They run as local processes that Claude communicates with via stdio, providing access to databases, browsers, APIs, and other services.
The .mcp.json file in the project root defines which servers are available. Each server declaration specifies a command to launch and its arguments. Environment variables are expanded at runtime using ${VAR:-default} syntax.
Full documentation: code.claude.com/docs/en/mcp
| Server | Description | Recommended |
|---|---|---|
| context7 | Up-to-date library documentation lookup | Always |
| playwright | Browser automation, testing, and web scraping | If testing web apps or scraping |
| postgres | PostgreSQL database interaction | If using PostgreSQL |
| docker | Docker container management | If using Docker |
context7 is recommended for all projects — it gives Claude access to current library docs, reducing hallucinated APIs and outdated patterns. The other servers are situational: keep or remove them from
.mcp.jsonbased on your project's stack.
A persistent status bar at the bottom of Claude Code that displays session info at a glance. It's pre-configured in .claude/settings.json and works automatically — no setup needed.
The status line shows three rows:
| Row | Content |
|---|---|
| 1 | Model name, current directory, git branch with staged/modified counts (color-coded) |
| 2 | Context window progress bar (green/yellow/red), context %, session cost, elapsed time |
| 3 | Rate limit usage bars for 5-hour and 7-day windows (Pro/Max only, hidden until first API response) |
The script is written in Python and works cross-platform: Windows, macOS, and Linux. Git operations are cached for 5 seconds to avoid lag on large repositories.
Full documentation: code.claude.com/docs/en/statusline
Contributions are welcome! If you have ideas for new agents, skills, rules, or improvements to the existing setup:
- Fork the repository
- Create a feature branch (
git checkout -b feature/your-idea) - Make your changes
- Submit a Pull Request with a clear description of what you added or changed
For bug reports or suggestions, open an issue.
This project builds on top of the official Claude Code documentation and tooling by Anthropic:
- Claude Code Documentation: setup guides, CLAUDE.md reference, skills, agents, MCP configuration
- Anthropic GitHub: official repositories and examples
- Model Context Protocol: open standard for LLM-tool integrations