quick-claude: ai agent configuration system

overview

quick-claude is an ai agent configuration system that solves the “context problem” - the need to repeatedly explain project conventions, tool preferences, and behavioral expectations to ai coding assistants every session.

instead of typing “use uv not pip” and “follow our naming conventions” every time you start claude code, quick-claude creates a persistent, modular instruction system that ai agents automatically read and follow.

the problem it solves

every time you start a new ai coding session, you face the same issues:

1. tool confusion - ai suggests pip install when you use uv
2. api hallucination - ai invents methods that don’t exist in your installed packages
3. inconsistent behavior - sometimes thorough, sometimes sloppy, no consistency
4. repeated instructions - explaining the same project conventions over and over
5. context loss - ai forgets project-specific requirements between sessions

quick-claude fixes this by creating a persistent context layer that travels with your project.

how it works

architecture

your-project/
├── CLAUDE.md          # compiled instructions (ai reads this)
├── cm.py              # module manager
├── .claude/
│   ├── config.yaml    # system configuration
│   └── modules/       # modular instructions
│       ├── context/   # base instructions, project structure
│       ├── tech/      # language-specific (python, node, etc)
│       ├── behavior/  # modes (flow-state, strict, tdd)
│       └── task/      # task management integration

module system

modules are markdown files with yaml frontmatter that define specific behaviors or contexts:

---
id: flow-state
name: Flow State Mode
category: behavior
priority: 20
active: false
---

# Flow State Mode

When activated, prioritize uninterrupted progress.
Make reasonable assumptions, batch operations, defer questions.

the cm.py manager compiles active modules into CLAUDE.md based on priority (higher = more important).

core components

1. module categories

context modules - foundational instructions

• base-instructions - core ai principles
• project-structure - file organization rules
• production-mindset - treat as real code for real users

tech modules - language and framework specific

• python-modern - use uv, ruff, modern python practices
• node-typescript - node.js and typescript configuration
• custom modules for your stack

behavior modules - operational modes

• flow-state - uninterrupted progress, reasonable assumptions
• strict-mode - extra validation, comprehensive testing
• test-driven-development - write tests first

task modules - workflow integration

• todo-management - integrates with claude’s todowrite tool
• proactive-todo-usage - ensures task tracking

2. bundled tools

quick-claude installs and configures:

• uv - lightning-fast python package/version management
• claude-interceptors - teaches ai to use modern tools
• pyenvsearch - prevents api hallucination

3. behavioral modes

flow state

activated with: python cm.py activate flow-state

ai will:

• batch related operations without pausing
• make reasonable assumptions based on context
• defer clarifications to natural break points
• use concise progress indicators

perfect for: rapid prototyping, implementing well-defined features

strict mode

activated with: python cm.py activate strict-mode

ai will:

• validate all assumptions
• write comprehensive tests
• check edge cases
• document decisions

perfect for: production code, critical systems

usage examples

basic workflow

# 1. install quick-claude
curl -sSL https://raw.githubusercontent.com/mjbommar/quick-claude/master/install.sh | bash

# 2. initialize module system
python cm.py init

# 3. activate modules for your project
python cm.py activate python-modern flow-state

# 4. compile instructions
python cm.py compile

# claude now knows to use uv, work in flow state, and follow your conventions

managing modules

# list all available modules
python cm.py list

# check current status
python cm.py status

# activate specific behavior
python cm.py activate test-driven-development

# deactivate module
python cm.py deactivate strict-mode

# compile changes
python cm.py compile

creating custom modules

create .claude/modules/context/my-conventions.md:

---
id: my-conventions
name: Project Conventions
category: context
priority: 75
active: true
---

# Project Conventions

## naming

- use snake_case for python files
- use kebab-case for directories
- prefix test files with test\_

## api design

- all endpoints return json
- use standard http status codes
- include request_id in responses

then compile:

python cm.py compile

module priorities

modules apply in priority order (0-100, higher = more important):

• 90-100: critical context (base instructions, production mindset)
• 70-89: technology stack (python, node, frameworks)
• 50-69: project-specific conventions
• 30-49: behavioral modes (flow-state, strict)
• 10-29: optional enhancements
• 0-9: experimental features

practical configurations

fast prototyping

python cm.py activate python-modern flow-state

ai moves fast, makes assumptions, focuses on implementation

production development

python cm.py activate python-modern strict-mode test-driven-development production-mindset

ai writes tests first, validates thoroughly, considers security

data science

python cm.py activate python-modern jupyter-support scientific-computing

ai uses notebooks effectively, handles data properly

troubleshooting

modules not compiling

check yaml frontmatter syntax in module files - must be valid yaml between --- markers

ai not following instructions

verify CLAUDE.md exists and contains compiled modules. check module priorities - higher priority modules override lower ones.

command not found: cm.py

ensure you’re in project directory with quick-claude installed. run install script if missing.

integration with ai agents

claude code

reads CLAUDE.md automatically on session start. modules persist across sessions.

cursor / windsurf

place CLAUDE.md in project root. agent will read and follow instructions.

github copilot

less effective but can reference CLAUDE.md in prompts.

philosophy

quick-claude embraces configuration as code for ai behavior. instead of ephemeral conversations, you build persistent, versioned, shareable ai configurations.

this enables:

• consistency - same behavior across team members
• evolution - refine modules based on experience
• sharing - export module sets for specific workflows
• learning - ai improves by following structured guidance

comparison with alternatives

advanced features

auto-activation triggers

modules can activate based on file patterns:

triggers:
  file_patterns:
    - '*.py'
    - 'pyproject.toml'
  keywords:
    - 'fastapi'
    - 'django'

module dependencies

modules can require or conflict with others:

dependencies:
  requires: [python-modern]
  conflicts: [node-typescript]

environment-specific modules

activate different modules per environment:

# development
python cm.py preset dev

# production
python cm.py preset prod

best practices

1. start minimal - activate only essential modules initially
2. document patterns - create modules for repeated instructions
3. version modules - commit .claude/ directory to git
4. share configurations - export module sets for common workflows
5. iterate based on experience - refine modules as you learn what works

further reading

• claude-interceptors - command interception system
• pyenvsearch - package exploration for ai
• modern python setup - python environment configuration
• uv package manager - fast python package management

external resources

• quick-claude on github
• module examples repository
• troubleshooting guide