Claude Code Python Setup

A ready-to-use .claude configuration for Python development projects with Claude Code. Includes curated agents, commands, skills, and MCP server templates.

Prerequisites

Claude Code

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.ClaudeCode

After 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 check

Full documentation: code.claude.com/docs/en/setup

Optional Dependencies

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)	install guide

npx comes with Node.js. uvx comes 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 -g to install a hook that automatically optimizes all shell commands in Claude Code sessions.

Project Structure

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

Setup

1. Copy the .claude folder

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).

2. Configure MCP servers

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.json is gitignored so each developer can use the template matching their OS.

3. Set environment variables (optional)

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)

4. Verify MCP servers

Run /mcp inside Claude Code to check that all servers are connected.

Components

CLAUDE.md (project root)

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.md to 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 (.claude/rules/)

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 paths in YAML frontmatter to activate a rule only for matching file patterns (e.g., api-patterns.md only for src/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 (.claude/hooks/)

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: PreToolUse hooks 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 jq for 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

Permissions (.claude/settings.json)

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 (.claude/agents/)

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 description to 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 (.claude/skills/)

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: true makes a skill user-only; user-invocable: false makes it Claude-only
• Arguments: skills accept $ARGUMENTS from the user (e.g., /fix-issue 123)
• Subagent execution: skills with context: fork run 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	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 (.claude/commands/)

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 Servers (.mcp.json)

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.json based on your project's stack.

Status Line (.claude/statusline.py)

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

Contributing

Contributions are welcome! If you have ideas for new agents, skills, rules, or improvements to the existing setup:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-idea)
3. Make your changes
4. Submit a Pull Request with a clear description of what you added or changed

For bug reports or suggestions, open an issue.

References

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