cmdop-claude 0.1.8

Self-maintaining .claude/ runtime — LLM-powered doc review, project map, task queue, auto-fix, and project init

cmdop-claude

Self-maintaining .claude/ runtime. Turns a static config folder into living project memory — LLM-powered documentation review, project map generation, task queue, auto-fix, and project initialization.

$0.001 per full cycle (scan → review → fix → map) using DeepSeek V3.2 via SDKRouter.

How it works

┌─────────────────────────────────────────────────────────────────┐
│                    Claude Code Session                          │
│                                                                 │
│  UserPromptSubmit ──► inject-tasks                              │
│                        ├─ auto-scan (if >24h since last review) │
│                        │   ├─ LLM review of .claude/ docs+plans │
│                        │   └─ convert issues → tasks            │
│                        └─ print top 3 pending tasks             │
│                                                                 │
│  PostToolUse (Write|Edit) ──► map-update                        │
│                                ├─ debounce (skip if <60s)       │
│                                └─ incremental project map       │
│                                    └─ SHA256 cache (skip LLM    │
│                                       for unchanged dirs)       │
│                                                                 │
│  MCP Tools ──► sidecar_scan    → manual review trigger          │
│            ──► sidecar_fix     → apply fix to a task            │
│            ──► sidecar_init    → bootstrap bare project         │
│            ──► sidecar_map     → force map regeneration         │
│            ──► sidecar_tasks   → view/manage task queue         │
│            ──► sidecar_activity → view action log               │
└─────────────────────────────────────────────────────────────────┘

The full automation chain:

1. On every prompt (UserPromptSubmit hook):

   • Check if last review was >24h ago → auto-run LLM review
   • Review finds stale docs, contradictions, gaps, abandoned plans → creates tasks
   • Top 3 pending tasks injected into context

2. On every file edit (PostToolUse hook):

   • Debounced map update (skip if <60s since last)
   • LLM annotates new/changed directories
   • Unchanged dirs served from SHA256 cache (0 tokens)

3. On demand (MCP tools / CLI):

   • sidecar_fix → LLM generates targeted fix for a task
   • sidecar_init → bootstraps CLAUDE.md + rules for bare projects
   • sidecar_acknowledge → suppress noisy items for N days

4. Everything is logged to activity.jsonl with token counts

Install

pip install cmdop-claude

# With Streamlit dashboard
pip install cmdop-claude[ui]

# Dev
pip install -e ".[dev]"

Quick Start

MCP Server (12 tools for Claude Code)

pip install cmdop-claude
python -m cmdop_claude.sidecar.hook register    # MCP → ~/.claude.json + hooks → .claude/settings.json

One command does everything:

• Registers MCP server globally in ~/.claude.json
• Sets up project hooks in .claude/settings.json (map-update on Write/Edit, inject-tasks+auto-scan on prompt)

To set up hooks in another project (MCP already registered):

python -m cmdop_claude.sidecar.hook setup        # project hooks only

To unregister:

python -m cmdop_claude.sidecar.hook unregister

Tool	LLM?	Description
sidecar_scan	yes	Run documentation review
sidecar_review	no	Read current review
sidecar_status	no	Last run, pending items, token usage
sidecar_acknowledge	no	Suppress item for N days
sidecar_map	yes	Generate/update project map
sidecar_map_view	no	Read current map
sidecar_tasks	no	List tasks by status
sidecar_task_update	no	Update task status
sidecar_task_create	no	Create manual task
sidecar_fix	yes	Generate fix for a task (dry-run or apply)
sidecar_init	yes	Bootstrap .claude/ for bare projects
sidecar_activity	no	View recent action log (init, review, fix, map)

CLI

python -m cmdop_claude.sidecar.hook register             # MCP + project hooks
python -m cmdop_claude.sidecar.hook setup                # project hooks only
python -m cmdop_claude.sidecar.hook unregister           # remove MCP from ~/.claude.json
python -m cmdop_claude.sidecar.hook scan                 # manual review
python -m cmdop_claude.sidecar.hook status               # status JSON
python -m cmdop_claude.sidecar.hook map-update           # debounced map
python -m cmdop_claude.sidecar.hook inject-tasks         # auto-scan + pending tasks
python -m cmdop_claude.sidecar.hook fix <task_id> [--apply]
python -m cmdop_claude.sidecar.hook init                 # bootstrap .claude/
python -m cmdop_claude.sidecar.hook acknowledge <id> [days]
python -m cmdop_claude.sidecar.hook activity [limit]

Hooks (auto-configured by register/setup)

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "command": "python -m cmdop_claude.sidecar.hook map-update"
    }],
    "UserPromptSubmit": [{
      "command": "python -m cmdop_claude.sidecar.hook inject-tasks"
    }]
  }
}

Python API

from cmdop_claude import Client

client = Client()

# Review → find issues
result = client.sidecar.generate_review()

# Fix a specific task
fix = client.sidecar.fix_task("T-001", apply=True)

# Init bare project
init = client.sidecar.init_project()

# Generate project map
project_map = client.sidecar.generate_map()

Streamlit Dashboard

make run   # http://localhost:8501

Configuration

Variable	Default	Description
CMDOP_CLAUDE_DIR_PATH	.claude	Path to .claude directory
SDKROUTER_API_KEY	—	API key for SDKRouter
CLAUDE_CP_SIDECAR_MODEL	deepseek/deepseek-v3.2	LLM model for review/fix/map
CMDOP_DEBUG_MODE	false	Debug logging

Init uses Model.balanced(json=True) from SDKRouter (auto-selects best model for structured output). Review, fix, and map use DeepSeek V3.2 (cheap, fast, good for short responses).

File Layout

.claude/
├── CLAUDE.md                # project instructions
├── project-map.md           # auto-generated structure map
├── settings.json            # hooks config (auto-created by register/setup)
├── rules/*.md               # coding rules
└── .sidecar/                # runtime state (git-ignored)
    ├── review.md            # latest review
    ├── history/*.md         # past reviews
    ├── tasks/T-001.md       # task queue (YAML frontmatter + md)
    ├── map_cache.json       # annotation cache (SHA256)
    ├── activity.jsonl       # action log (auto-rotates at 1000 lines)
    ├── usage.json           # daily token tracking
    └── suppressed.json      # acknowledged items

Architecture

src/cmdop_claude/
├── _config.py                  # Pydantic Settings
├── models/
│   ├── sidecar.py              # Review, Fix, Init, ActivityEntry models
│   ├── project_map.py          # Map models
│   └── task.py                 # Task models
├── services/
│   └── sidecar_service/        # Decomposed into domain mixins
│       ├── _base.py            # State, lock, scan, usage, activity
│       ├── _review.py          # LLM review + review.md
│       ├── _fix.py             # LLM fix for tasks
│       ├── _init.py            # LLM project init (balanced model + fallback)
│       ├── _tasks.py           # Task CRUD
│       ├── _mcp.py             # MCP registration + project hooks
│       └── _status.py          # Status + map access
├── sidecar/
│   ├── server.py               # FastMCP server (12 tools)
│   ├── hook.py                 # CLI (11 commands, auto-scan logic)
│   ├── scanner.py              # .claude/ filesystem scanner
│   ├── mapper.py               # Project map generator
│   ├── exclusions.py           # Junk filter + .gitignore
│   ├── activity.py             # Activity logger (JSONL, auto-rotate)
│   ├── cache.py                # SHA256 annotation cache
│   ├── tasks.py                # Task queue manager
│   └── prompts.py              # LLM prompt templates
└── ui/app.py                   # Streamlit dashboard

Cost

Operation	Tokens	Cost
Documentation review	~1800	~$0.0005
Fix a task	~500	~$0.0001
Project init (balanced)	~5000	~$0.001
Map generation (45 dirs)	~5000	~$0.001
Map incremental (cached)	0	$0.00
Auto-scan (1x/day)	~1800	~$0.0005
Tasks / status / read	0	$0.00

Full cycle: ~$0.003. Daily estimate: ~$0.003/day (auto-scan + occasional map updates).

Testing

make test   # 288 tests

Development

make patch          # 0.1.0 → 0.1.1
make minor          # 0.1.0 → 0.2.0
make build          # sdist + wheel
make publish        # upload to PyPI
make publish-test   # upload to TestPyPI
make install-global # pip install -e . (local dev)

License

MIT