on this page

quick-claude

software

modular ai agent configuration system that eliminates repeated instructions and ensures consistent behavior across coding sessions

period: 2025-present
tech:
PythonBashAI AgentsDeveloper ExperienceConfiguration Management
GitHub

quick-claude is a configuration-as-code system for ai coding assistants that solves the “context problem” - having to repeatedly explain the same project conventions, tool preferences, and behavioral expectations every time you start a new ai session.

problem it solves

when working with ai coding assistants like claude code, cursor, or windsurf, developers face persistent frustrations:

  • repeated instructions - “use uv not pip”, “follow our naming conventions”, “write tests first” - said every session
  • inconsistent behavior - sometimes the ai is thorough, sometimes sloppy, with no way to control it
  • tool confusion - ai suggests outdated commands because it was trained on old documentation
  • api hallucination - ai invents methods that don’t exist in your actual installed packages
  • context loss - project-specific requirements forgotten between sessions

quick-claude fixes this by creating a persistent, modular instruction system that ai agents automatically read and follow.

how it works

the system uses a module architecture where instructions are organized into markdown files with yaml frontmatter:

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

these modules are compiled by cm.py into a single CLAUDE.md file that ai agents read on startup. modules are organized by category (context, tech, behavior, task) and apply based on priority.

key innovations

behavioral modes - switch between different operational styles:

  • flow-state - rapid progress with reasonable assumptions
  • strict-mode - comprehensive validation and testing
  • test-driven-development - tests first, always

automatic tool installation - bundles and configures modern python tooling:

project detection - automatically activates relevant modules based on files present (detects python, node, django, fastapi, etc)

module system

modules support:

  • priorities (0-100) - higher priority modules override lower ones
  • triggers - auto-activate based on file patterns or keywords
  • dependencies - require or conflict with other modules
  • categories - organized into context, tech, behavior, and task modules

example custom module:

---
id: api-conventions
name: API Design Standards
category: context
priority: 75
active: true
---

# API Conventions

- all endpoints return json with `request_id`
- use standard http status codes
- validate input with pydantic models

design philosophy

quick-claude embraces configuration as code for ai behavior. instead of ephemeral conversations, you build persistent, versioned, shareable ai configurations. this enables team consistency, iterative improvement, and knowledge sharing.

the one-line installer philosophy means developers can bootstrap a fully-configured ai-friendly environment in seconds, eliminating setup friction and ensuring everyone uses the same modern toolchain.

on this page