---

Installation

``bash
npx ctx-cc
`

That's it. CTX installs itself to your Claude Code environment.

`bash


Options


npx ctx-cc --global # Install to ~/.claude (default)
npx ctx-cc --project # Install to .claude in current directory
npx ctx-cc --force # Overwrite existing installation
`

---

Quick Start

Just talk to CTX. No commands to memorize:

`
"I want to build a todo app" → CTX sets up your project
"Fix the login bug" → CTX starts debugging
"Is my app accessible?" → CTX runs accessibility QA
"What should I do next?" → CTX shows status + recommendation
`

Or use commands directly:
`
1. /ctx init Gather requirements + credentials + design context
2. /ctx map Build repository map (existing codebases)
3. /ctx Autonomous execution with minimal interruption
`

The Flow:
`
Tell CTX what you want → CTX figures out the rest → Delivered!
`

---

New in 3.3

$3

No commands to memorize. CTX understands natural language from your first prompt:

| You Say | CTX Does |
|---------|----------|
| "I want to build a todo app" | Sets up project, researches best practices, creates plan |
| "Fix the login bug" | Analyzes codebase, starts debugging |
| "Is my app accessible?" | Runs WCAG 2.1 AA accessibility audit |
| "Test everything" | Crawls every page, clicks every button |
| "What's next?" | Shows status and recommended action |
| "Ship it" | Runs verification, then deploys |

New user? CTX welcomes you and guides setup:
`
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Welcome to CTX!
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

I understood: "build a todo app with React"

You want to build something new. Let's set it up!

I'll now:
1. Create your project structure
2. Research best practices for React todo apps
3. Create a plan with clear milestones
`

Commands still work as shortcuts for power users.

$3

Crawl every page, click every button, find all issues:

`bash
/ctx qa # Full system QA (WCAG 2.1 AA)
/ctx qa --a11y-only # Accessibility audit only
/ctx qa --visual-only # Visual regression (3 viewports)
/ctx qa --resume # Resume interrupted session
`

Features:
- WCAG 2.1 AA compliance - Touch targets, alt text, labels, contrast, keyboard
- Multi-viewport testing - Mobile (375px), Tablet (768px), Desktop (1280px)
- Performance monitoring - Slow requests, large assets
- Trace capture - Screenshots and logs for every failed interaction
- Fix tasks - Issues organized by section, ready for execution

$3

CTX learns from your codebase and preferences:

`
[LEARNER] Applying 3 learned preferences

1. Using Zod for validation
→ Based on pattern P001 (95% confidence, 12 observations)

2. Functional components only
→ Based on decision D005 (explicit preference)

3. Avoiding moment.js, using date-fns
→ Based on failure F001 (bundle size)
`

Memory stored in .ctx/memory/:
- patterns.json - Code patterns you prefer
- decisions.json - Past architectural decisions
- failures.json - What didn't work
- preferences.json - Communication style
- conventions.json - Naming and structure

Commands:
`bash
/ctx learn # Show what CTX has learned
/ctx learn patterns # Show code patterns
/ctx learn decisions # Show architectural decisions
/ctx learn forget [id] # Remove a learned pattern
`

$3

AI suggests what to build next based on patterns:

`
[PREDICT] Feature Suggestions for MyApp

Based on your e-commerce app at MVP stage:

1. Cart Abandonment Recovery
├─ ROI: 9/10
├─ Effort: Medium (2-3 days)
└─ Impact: +15-25% recovered revenue

2. Product Reviews & Ratings
├─ ROI: 9/10
├─ Effort: Low (1-2 days)
└─ Impact: +18% conversion rate

3. Discount Codes System
├─ ROI: 7/10
└─ Effort: Low (1 day)

[1] Create story [A] Create all [R] Research more
`

Commands:
`bash
/ctx predict # Full prediction analysis
/ctx predict --quick # Quick wins only (< 1 day)
/ctx predict --create [id] # Create story from suggestion
`

$3

Monitor production errors and auto-fix:

`bash
/ctx monitor connect sentry # Connect Sentry
/ctx monitor errors # List recent errors
/ctx monitor auto-fix [id] # Auto-fix with PR
/ctx monitor --watch # Continuous monitoring
`

Auto-fix workflow:
`
1. Sentry reports: "TypeError in checkout.ts:45"
2. CTX analyzes error pattern
3. If safe pattern (null check, import, etc.):
→ Auto-generates fix
→ Runs tests
→ Creates PR
→ Notifies team
4. If complex pattern:
→ Creates fix story
→ Assigns priority
→ Provides context
`

Supports: Sentry, LogRocket, Bugsnag, Datadog

$3

Speak your requirements instead of typing:

`bash
/ctx voice # Start voice input
/ctx voice --continuous # Always listening
/ctx voice --dictate # Long-form input
`

`
[VOICE] 🎤 Listening...

User: "Create a story for user authentication
with email login and forgot password"

[VOICE] Story created:

Title: User Authentication
Criteria:
✓ User can login with email/password
✓ Forgot password sends reset email
✓ Session persists across browser

Add to PRD? [Y/n/edit]
`

Supports: macOS Speech, Whisper (local), Google Speech, Azure

---

From 3.2

$3


Full release management with audit, archive, and git tagging:
`bash
/ctx milestone # Show current milestone status
/ctx milestone list # List all milestones
/ctx milestone audit # Verify milestone complete
/ctx milestone complete # Archive and create git tag
/ctx milestone new v2.0 # Start next version
/ctx milestone gaps # Generate fix phases for failures
`

Features:
- Archive phases to .ctx/archive/v{version}/
- Auto-create git tags on complete
- Gap analysis for incomplete milestones
- Integration with Linear/Jira/GitHub

$3


Multiple developers working with CTX on same repo:
`
[TEAM] Current Activity

Active:
alice: T001 - User authentication (10m)
bob: T003 - API endpoints (waiting for T001)

Available:
charlie: idle
`

Features:
- File locking - Prevent conflicts during execution
- Lock expiry - Auto-release after 1 hour
- Conflict detection - Fail fast on overlaps
- Team notifications - Slack/Discord on phase complete
- Branch strategy - Auto-create feature branches

$3


Complete traceability for enterprise:
`bash
/ctx audit # Show today's summary
/ctx audit week # Weekly summary
/ctx audit export # Generate compliance report
`

Every action logged:
`json
{
"timestamp": "2024-01-20T09:30:00Z",
"action": "execute",
"story": "S001",
"agent": "ctx-executor",
"model": "claude-sonnet-4",
"tokens": {"input": 5000, "output": 2000},
"filesModified": ["src/auth/login.ts"],
"decisions": ["Use JWT for auth"],
"commit": "abc1234"
}
`

Compliance features:
- Access logging (who read what)
- Decision tracking (with rationale)
- Change log (all modifications)
- Retention policies (90d daily, 1y weekly)
- SOC2, HIPAA, GDPR modes

$3


Understand AI productivity impact:
`bash
/ctx metrics # Overview dashboard
/ctx metrics cost # Cost analysis
/ctx metrics export # Export HTML dashboard
`

`
╔══════════════════════════════════════════════════════════╗
║ CTX METRICS - Week 3 ║
╠══════════════════════════════════════════════════════════╣
║ Stories/Week: 8 (+2) Total Cost: $4.87 ║
║ Time/Story: 1h 45m Per Story: $0.61 ║
║ Debug Loops: 12 Success Rate: 92% ║
║ ║
║ ROI: 30x (24 hours saved, $145 net savings) ║
╚══════════════════════════════════════════════════════════╝
`

Metrics tracked:
- Stories completed per day/week
- Average time per story
- Token usage by phase/model
- Cost analysis with ROI
- Debug loop frequency
- Verification success rate
- Human intervention rate

---

From 3.1

$3


Tasks without dependencies run simultaneously:
`
Wave 1: [T001, T003] → Parallel (no deps)
Wave 2: [T002] → After T001
Wave 3: [T004] → After T002

Result: 40% faster execution
`

$3

Catches errors BEFORE they're committed:
- Type errors (TypeScript, Python, Go)
- Unresolved imports
- Circular dependencies
- Security vulnerabilities
- Empty catch blocks, console.logs

`
[CTX] Pre-Commit Review
✅ Types: Pass
✅ Imports: Pass
⚠️ Medium: 2 console.log statements
❌ Critical: SQL injection risk at line 45

Status: BLOCKED - Fix critical issue
`

$3


AI suggests comprehensive criteria:
`
Story: "Add user authentication"

Suggested Criteria:
✓ User can register with email/password
✓ Invalid credentials show error
✓ Passwords hashed with bcrypt
✓ Session expires after 24h
✓ Brute force protection enabled

[A] Accept all [B] See more [C] Edit
`

$3

Seamless transitions at context limits:

| Threshold | Action |
|-----------|--------|
| 40% | Prepare handoff notes |
| 50% | Write HANDOFF.md, warn |
| 60% | Spawn fresh agent |

Zero information loss. Work continues automatically.

$3

Sync with Linear, Jira, or GitHub Issues:
`bash
/ctx integrate linear # Setup Linear
/ctx integrate jira # Setup Jira
/ctx integrate github # Setup GitHub Issues
/ctx integrate --sync # Force sync all stories
`

Features:
- Bidirectional story sync
- Status mapping (CTX → tracker)
- Auto-close on verify pass
- Comment on verify fail

---

From 3.0

$3

`bash
/ctx map # Build token-optimized codebase map
/ctx map --expand # Include call graph (8k tokens)
/ctx map --refresh # Force full rebuild
`

Creates REPO-MAP.md with symbols, dependencies, and navigation hints.

$3


`bash
/ctx discuss S001 # Capture decisions BEFORE planning
/ctx discuss --review # Review locked decisions
`

Prevents mid-implementation questions by locking decisions in CONTEXT.md.

$3


`bash
/ctx profile # Show current profile
/ctx profile quality # Best models (Opus everywhere)
/ctx profile balanced # Smart mix (default)
/ctx profile budget # Fast models (60% savings)
`

| Profile | Research | Execute | Verify | Cost |
|---------|----------|---------|--------|------|
| quality | Opus | Opus | Sonnet | 3x |
| balanced | Opus | Sonnet | Haiku | 1x |
| budget | Sonnet | Sonnet | Haiku | 0.4x |

$3

Every completed task auto-commits:
`
[CTX] Implement user login endpoint

Story: S001 - User Authentication
Criteria: User can log in with credentials
Files: src/auth/login.ts, src/routes/auth.ts

Co-Authored-By: Claude
`

Configure in .ctx/config.json:
`json
{
"git": {
"autoCommit": true,
"commitPerTask": true
}
}
`

$3

Scientific debugging with persistent state across sessions:

`bash
/ctx debug "login fails" # Start debugging
/ctx debug --resume # Resume after context reset
/ctx debug --list # See all sessions
`

How it works:
`
1. OBSERVE → Capture exact error, context, state
2. RESEARCH → Search codebase and web for similar issues
3. HYPOTHESIZE → Form testable theory with confidence level
4. TEST → Apply minimal fix
5. VERIFY → Build + Tests + Lint + Browser
6. ITERATE → Refine hypothesis, max 10 attempts
`

Key features:
- Sessions survive context resets and days between attempts
- Browser verification with stored credentials
- Screenshots saved for each attempt
- Escalation report if max attempts reached

State stored in .ctx/debug/sessions/:
- STATE.json - Machine-readable progress
- TRACE.md - Human-readable log
- hypotheses.json - All theories tested
- screenshots/ - Visual evidence

$3


`bash
/ctx map-codebase # Full analysis with 4 parallel agents
`

Spawns 4 agents simultaneously:
| Agent | Output | Analyzes |
|-------|--------|----------|
| TECH | TECH.md | Languages, frameworks, dependencies |
| ARCH | ARCH.md | Patterns, data flow, modules |
| QUALITY | QUALITY.md | Test coverage, lint, type safety |
| CONCERNS | CONCERNS.md | Security, tech debt, performance |

Results synthesized into SUMMARY.md.

---

Why CTX?

| Feature | Aider | GSD | CTX 3.0 |
|---------|-------|-----|---------|
| Repository Map | Yes | No | Yes |
| Discussion Phase | No | Yes | Yes |
| Model Profiles | Yes | Partial | Yes |
| Git-Native Commits | Yes | No | Yes |
| Persistent Debug | No | Partial | Yes |
| Parallel Analysis | No | Yes | Yes |
| PRD-Driven | No | Yes | Yes |
| Design System | No | No | Yes |
| Browser Verification | No | No | Yes |

CTX 3.0 combines the best of Aider and GSD.

---

Commands

$3


| Command | Purpose |
|---------|---------|
| /ctx | Smart router - reads STATE.md, does the right thing |
| /ctx init | Initialize project with STATE.md + PRD.json |

$3

| Command | Purpose |
|---------|---------|
| /ctx map | Build repository map (REPO-MAP.md) |
| /ctx map-codebase | Deep analysis (4 parallel agents) |

$3

| Command | Purpose |
|---------|---------|
| /ctx discuss [story] | Capture decisions before planning |

$3

| Command | Purpose |
|---------|---------|
| /ctx profile [name] | Switch model profile (quality/balanced/budget) |

$3

| Command | Purpose |
|---------|---------|
| /ctx status | See current state without triggering action |

$3

| Command | Purpose |
|---------|---------|
| /ctx plan [goal] | Force research + planning |
| /ctx verify | Force three-level verification |
| /ctx quick "task" | Quick task bypass |

$3

| Command | Purpose |
|---------|---------|
| /ctx debug | Start debugging current issue |
| /ctx debug "issue" | Debug specific problem |
| /ctx debug --resume | Resume last debug session |
| /ctx debug --list | List all debug sessions |
| /ctx debug --status | Show current session status |

$3

| Command | Purpose |
|---------|---------|
| /ctx qa | Full system QA - WCAG 2.1 AA, every page, every button |
| /ctx qa --section "auth" | QA specific section only |
| /ctx qa --a11y-only | Accessibility audit only |
| /ctx qa --visual-only | Visual regression (mobile/tablet/desktop) |
| /ctx qa --resume | Resume interrupted QA session |
| /ctx qa --report | Show last QA report |

$3

| Command | Purpose |
|---------|---------|
| /ctx pause | Checkpoint for session resume |

$3

| Command | Purpose |
|---------|---------|
| /ctx phase list | Show all phases |
| /ctx phase add "goal" | Add new phase |
| /ctx phase next | Complete current, move to next |

$3

| Command | Purpose |
|---------|---------|
| /ctx integrate | Show integration status |
| /ctx integrate linear | Setup Linear |
| /ctx integrate jira | Setup Jira |
| /ctx integrate github | Setup GitHub Issues |
| /ctx integrate --sync | Sync all stories |

$3

| Command | Purpose |
|---------|---------|
| /ctx milestone | Show current milestone |
| /ctx milestone list | List all milestones |
| /ctx milestone audit | Verify completion |
| /ctx milestone complete | Archive and tag |
| /ctx milestone new [name] | Start next version |
| /ctx milestone gaps | Generate fix phases |

$3

| Command | Purpose |
|---------|---------|
| /ctx metrics | Show productivity dashboard |
| /ctx metrics cost | Cost analysis |
| /ctx metrics export | Export HTML dashboard |
| /ctx audit | Show audit summary |
| /ctx audit export | Generate compliance report |

$3

| Command | Purpose |
|---------|---------|
| /ctx learn | Show what CTX has learned |
| /ctx learn patterns | Show code patterns |
| /ctx learn decisions | Show architectural decisions |
| /ctx learn forget [id] | Remove a learned pattern |
| /ctx predict | Get feature suggestions |
| /ctx predict --quick | Quick wins only |
| /ctx predict --create [id] | Create story from suggestion |

$3

| Command | Purpose |
|---------|---------|
| /ctx monitor | Show monitoring status |
| /ctx monitor connect sentry | Connect Sentry |
| /ctx monitor errors | List recent errors |
| /ctx monitor auto-fix [id] | Auto-fix with PR |
| /ctx monitor --watch | Continuous monitoring |
| /ctx voice | Start voice input |
| /ctx voice --continuous | Always listening mode |
| /ctx voice --dictate | Long-form dictation |

---

State Machine

`
initializing → discussing → executing → verifying → COMPLETE
↑ ↓
└── debugging ──┘
`

| State | What happens |
|-------|--------------|
| initializing | Research + Map + Plan |
| discussing | Capture decisions in CONTEXT.md |
| executing | Execute with git-native commits |
| debugging | Persistent debug loop (max 10 attempts) |
| verifying | Three-level verification |
| paused | Resume from checkpoint |

---

Context Management

CTX actively manages context budget:

| Usage | Quality | Action |
|-------|---------|--------|
| 0-30% | Peak | Continue |
| 30-40% | Good | Continue |
| 40-50% | Good | Prepare handoff notes |
| 50-60% | Degrading | Auto-checkpoint |
| 60-70% | Degrading | Create HANDOFF.md |
| 70%+ | Poor | Force checkpoint |

Smart handoff creates HANDOFF.md with:
- Completed tasks with commit hashes
- Current task progress
- Key decisions made
- Files modified
- Next steps

---

21 Specialized Agents

| Agent | Spawned when | Model (balanced) |
|-------|--------------|------------------|
| ctx-mapper | /ctx map | haiku |
| ctx-tech-mapper | /ctx map-codebase | haiku |
| ctx-arch-mapper | /ctx map-codebase | haiku |
| ctx-quality-mapper | /ctx map-codebase | haiku |
| ctx-concerns-mapper | /ctx map-codebase | haiku |
| ctx-discusser | status = discussing | sonnet |
| ctx-researcher | status = initializing | opus |
| ctx-planner | after research | opus |
| ctx-executor | status = executing | sonnet |
| ctx-designer | design stories | sonnet |
| ctx-debugger | status = debugging | sonnet |
| ctx-verifier | status = verifying | haiku |
| ctx-parallelizer | before execution | haiku |
| ctx-reviewer | before commit | sonnet |
| ctx-criteria-suggester | during init/discuss | sonnet |
| ctx-handoff | at context thresholds | haiku |
| ctx-team-coordinator | team mode | sonnet |
| ctx-auditor | always (background) | haiku |
| ctx-learner | observing patterns | haiku |
| ctx-predictor | after milestone/on demand | sonnet |
| ctx-qa | /ctx qa (full system test) | sonnet |

---

Directory Structure

`
.ctx/
├── config.json # Model profiles, git settings
├── STATE.md # Living digest - execution state
├── PRD.json # Requirements contract
├── REPO-MAP.md # Token-optimized codebase map
├── REPO-MAP.json # Structured map data
├── .env # Test credentials (GITIGNORED)
├── codebase/ # Deep analysis results
│ ├── TECH.md
│ ├── ARCH.md
│ ├── QUALITY.md
│ ├── CONCERNS.md
│ └── SUMMARY.md
├── phases/{story_id}/
│ ├── CONTEXT.md # Locked decisions (discussion phase)
│ ├── RESEARCH.md # ArguSeek results
│ ├── PLAN.md # Tasks mapped to criteria
│ └── VERIFY.md # Verification report
├── debug/
│ ├── sessions/ # Persistent debug state
│ └── screenshots/ # Visual proof
├── checkpoints/ # Auto-checkpoints
└── memory/ # Decision memory
`

---

Configuration

.ctx/config.json:
`json
{
"activeProfile": "balanced",
"models": {
"architect": { "id": "claude-opus-4", "costTier": "high" },
"default": { "id": "claude-sonnet-4", "costTier": "medium" },
"fast": { "id": "claude-haiku-4", "costTier": "low" }
},
"profiles": {
"quality": {
"research": "architect",
"discussion": "architect",
"planning": "architect",
"execution": "architect"
},
"balanced": {
"research": "architect",
"discussion": "default",
"planning": "architect",
"execution": "default"
},
"budget": {
"research": "default",
"planning": "default",
"execution": "default"
}
},
"git": {
"autoCommit": true,
"commitPerTask": true
}
}
`

---

Integrations

$3

Auto-runs during planning for best practices, security, and patterns.

$3

Auto-runs during planning for semantic search and pattern detection.
`bash
uv tool install chunkhound
`

$3

Auto-runs during debugging and verification for visual proof.

$3

Auto-runs during design stories for tokens and component metadata.

$3

Auto-runs during design stories for mockups and UI code.

---

Key Principles

$3

| Trigger | Action |
|---------|--------|
| Bug in existing code | Auto-fix, document in commit |
| Missing validation | Auto-add, document |
| Blocking issue | Auto-fix, document |
| Architecture decision | Ask user |

$3

| Level | Question | Check |
|-------|----------|-------|
| Exists | File on disk? | Glob |
| Substantive | Real code, not stub? | No TODOs, no placeholders |
| Wired | Imported and used? | Trace imports |

$3

Plans limited to 2-3 tasks to prevent context degradation.

---

Updating

`bash
npx ctx-cc --force
``

---

License

MIT

---