oh-no-my-claudecode 0.87.0

Memory-grounded autonomous coding loops for Claude Code and Codex.

oh-no-my-claudecode (onmc)

Autonomous coding loops that remember what your repo learned and prove when work is done.

ONMC runs Claude Code, Codex, or OpenCode against a goal, injects relevant repository memory on every iteration, warns about known dead-ends, executes your real verifier, enforces time/cost/token limits, and writes a tamper-evident run receipt.

Use the execution loop, the memory layer, or both. ONMC is local-first, cross-agent, and works without a hosted account.

pip install oh-no-my-claudecode
cd your-repo
onmc setup

Prefer isolated CLI installs? Use uv tool install oh-no-my-claudecode.

Why ONMC

Coding agents are capable. Their surrounding workflow still has four expensive gaps:

Gap	ONMC answer
Every session starts cold	Repo memory compiled from git, docs, code, PRs, and transcripts
Autonomous loops repeat failed ideas	guard injects recorded dead-ends before each attempt
"Done" can mean the model stopped talking	loop and autopilot require convergence plus your verifier to mark a run verified
Agent work is hard to inspect or reproduce	Tamper-evident receipts with git tree hash, model/tool hashes, iteration chain, and reproducibility envelope
No proof of agent improvement over time	evolution compares cost and iterations across runs; receipt-backed trend showing cheaper and faster loops
Expensive models do all the work	Cost-split execution: --plan-with <expensive> --execute-with <cheap> runs precise planning once, cheap execution per iteration
PRs need a hard "do not merge unless proven" gate	nomistakes runs audit/eval/autopilot and approves only with a verified receipt

ONMC does not replace Claude Code, Codex, or OpenCode. It gives them durable repository knowledge, bounded execution, and evidence.

Five-minute first win

1. Build the repo brain

onmc setup

Setup scans the repository, builds structured memory, generates agent context, installs supported hooks/MCP configuration, shows the first useful recall, and offers the local dashboard.

No provider required. Use onmc setup --no-llm for a fully deterministic first run.

2. Ask what the repo already knows

onmc brief --task "fix checkout coupon failures"
onmc guard --task "fix checkout coupon failures"
onmc why src/checkout/service.py
onmc ui

3. Run the full loop

The simplest way — one command runs the complete KNOW→PLAN(opt)→ACT→PROVE→LEARN cycle:

onmc autopilot "fix checkout coupon failures" \
  --verify "pytest -q" \
  --max-cost-usd 2.00

This compiles the brief, injects dead-ends, runs Claude Code in a loop, verifies success, records a receipt, and captures what the repo learned.

Prefer --plan-with + --execute-with to split cost: expensive model plans once, cheap model executes:

onmc autopilot "fix the cache invalidation bug" \
  --plan-with claude-opus-4-5 \
  --execute-with claude-haiku-4-5 \
  --verify "pytest -q" \
  --max-cost-usd 2.00

Or use the lower-level onmc loop for more control:

onmc loop \
  --goal "fix checkout coupon failures" \
  --agent claude \
  --verify "pytest -q" \
  --max-iterations 6 \
  --max-cost-usd 2.00 \
  --max-wall-seconds 900

Use --agent codex or --agent opencode to swap agents. Use --isolate to run in an isolated git worktree so failed attempts don't pollute your working tree. Use --resume to pick up from the last checkpoint.

4. Gate a PR with No-Mistakes mode

nomistakes is the merge gate: it runs deterministic preflight, lets the agent act inside an isolated worktree, verifies with your command, and approves only when ONMC writes a verified receipt.

onmc nomistakes "fix failing checkout CI" \
  --agent claude \
  --verify "pytest -q" \
  --eval-fail-under 80 \
  --max-cost-usd 3.00

Autonomy levels are explicit:

• L0 observe only
• L1 advise only
• L2 act, verify, learn, and produce a receipt
• L3 extended autonomous gate with the same receipt requirement
• L4 reserved for future human-approved merge automation

The full cycle: KNOW → (PLAN) → ACT → PROVE → LEARN

onmc autopilot orchestrates one command:

KNOW   → compile repo brief + recall guard (dead-ends) + user profile (preferences)
PLAN   → [optional] expensive model produces a precise implementation plan
ACT    → memory-grounded autonomous loop (avoids recorded dead-ends, stops at limits)
PROVE  → receipt + verified/not-verified verdict + cost (receipt is tamper-evident)
LEARN  → capture session memory + skill_promote + consolidate brain
         → "Your brain grew: +N memories · +N skills · N dead-ends known"

Loop iteration details:

Each ACT iteration:
  -> inject known failed approaches
  -> run Claude Code, Codex, or OpenCode
  -> run your verifier
  -> record prediction, outcome, files, tokens/cost when available
  -> decide: win, loss, or unknown
  -> continue, converge, or stop at a hard limit

A run is verified only when the loop converged and the final verifier exited successfully. Model claims alone never produce verified status.

Receipts (written to .agent-memory/receipts/) bind goal, agent, model, verifier result, git tree hash, diff SHA, loop spec, output digest, limits, and iteration chain with SHA-256. Receipts include a reproducibility envelope (model IDs, tool/prompt hashes, runtime) so runs can be reproduced. They are tamper-evident (not cryptographically signed).

What ships in v0.48

Capability	Command	What it gives you
No-Mistakes PR gate	onmc nomistakes "<goal>"	Audit + optional eval + isolated autopilot + verifier + receipt verdict; exits nonzero unless approved
Full autopilot cycle	onmc autopilot "<goal>"	One-verb KNOW→(PLAN)→ACT→PROVE→LEARN; ends with "your brain grew" summary. Use --plan-with <model> --execute-with <model> for cost-split
Compounding proof	onmc evolution	Shows agent getting cheaper/fewer-iterations across runs, receipt-backed trend
Accountable autonomous loop	onmc loop	Real Claude/Codex/OpenCode execution, dead-end avoidance, verifier gates, hard limits
Loop isolation & resume	onmc loop --isolate --resume	Run in fresh git worktree; roll back on failure. Resume interrupted runs from last checkpoint
Loop templates	onmc loop --template ci-healer	Ready-to-run templates: ci-healer, pr-babysitter, issue-to-pr
Tamper-evident receipts	loop/autopilot receipts	Git tree/diff SHA, hash chain, reproducibility envelope (model/tool/config hashes) for reproducibility
Portable repo brain	onmc sync --commit	Human-readable .agent-memory/ JSON that travels through git
Failure recall	onmc recall, onmc guard	Past incidents, fixes, and approaches not to repeat
Task context	onmc brief, onmc codegraph	Compact, task-specific context instead of broad file dumping
Replay Lab	onmc replay run ... --compare	Re-run memory decisions over a recorded trace, offline
Memory evals	onmc eval run, onmc eval compare	CI-gate recall quality and measure memory contribution
Trace Observatory	onmc trace	Session events, memory hit rate, loop signals, estimated token ROI
Skill export	onmc skill export	Export learned skills as Agent Skills SKILL.md (agentskills.io standard, 16+ tools supported)
Agent config audit	onmc audit	CI-gateable scan for permissions, secrets, hooks, MCP, prompt-injection risks
MCP trust policy	onmc mcp	Classify recorded/stdin MCP calls as allow, block, or approval required
GitHub workflow pack	onmc gh-aw init	Issue context, PR preflight, merged-PR learning, weekly memory audit
Visual inspection	onmc ui, onmc tui, onmc wiki	Local dashboard, terminal browser, Mission Control live view, and Obsidian knowledge graph
Cross-agent integration	onmc plug	Claude Code, Codex, Cursor, OpenCode adapters for headless loop/autopilot

Release progression

• v0.48: No-Mistakes PR gate and autopilot --isolate
• v0.47: durable loop checkpoint/resume and ready-to-run loop templates
• v0.36: guided setup and first-run dashboard welcome
• v0.35: deterministic session replay with memory-vs-cold comparison
• v0.34: tamper-evident receipts, cost limits, wall-time limits, proof-based completion
• v0.33: MCP trust policy and call classification
• v0.32: real headless Claude Code and Codex loop adapters
• v0.31: memory-aware GitHub Agentic Workflow scaffolding
• v0.30: deterministic memory eval suite and CI regression gates
• v0.29: agent-configuration security audit
• v0.28: measured repo-brain benchmarks plus labelled deterministic simulation
• v0.27: session trace observatory and OpenTelemetry JSON export
• v0.26: memory-grounded autonomous loop engine
• v0.24-v0.25: knowledge-gap actions, user profile MCP, memory federation, and natural-language MCP queries

See CHANGELOG.md for exact release notes.

Real workflows

Never retry yesterday's failed fix

onmc recall "InvalidSignatureError"
onmc guard --task "repair Firebase JWT middleware"

When an attempt fails, ONMC stores the approach and evidence. Future briefs and loop iterations surface it as a dead-end instead of rediscovering it.

Prove the brain contributes

onmc eval create \
  --query "fix cache invalidation" \
  --expect-file src/cache.py \
  --expect-deadend "per-worker cache"

onmc eval compare --baseline 10
onmc eval run --fail-under 80

Both commands are deterministic and exit nonzero below the requested threshold, so they can gate CI.

Replay a recorded session

onmc trace start --label "checkout repair"
# Work normally with ONMC-enabled agent hooks and commands.
onmc trace stop
onmc trace report

onmc replay run <trace-id> --compare

Replay re-runs recall and guard decisions against the current brain. It makes memory changes testable without calling an LLM.

Add repo-aware GitHub automation

onmc gh-aw init --dry-run
onmc gh-aw init

This writes four workflows: issue context, PR preflight, merged-PR learning, and weekly memory audit. Generated workflows use constrained permissions, pinned actions, and comment-only safe outputs.

Audit agent configuration and MCP calls

onmc audit . --fail-on high
onmc mcp policy init
onmc mcp check tool-calls.jsonl --fail-on approval_required

onmc audit is static. onmc mcp check classifies JSONL records or stdin against local policy; it is designed for hooks and CI pipelines, not as a transparent network proxy.

Works with your coding agent

onmc plug claude-code
onmc plug codex
onmc plug cursor
onmc plug omc
onmc plug omx
onmc plug all

Agent	Integration
Claude Code	Project hooks, .mcp.json, CLAUDE.md, slash commands, plugin marketplace
Codex	AGENTS.md, compact briefs, MCP registration, headless loop adapter
Cursor	.cursor/rules/onmc.md
OMC / OMX	Generated adapter guide over ONMC memory commands
Cloud agents	Restore committed .agent-memory/ in ephemeral environments

Claude Code marketplace install:

/plugin marketplace add adaline-ankit/oh-no-my-claudecode
/plugin install oh-no-my-claudecode@onmc
/reload-plugins

Codex MCP registration:

codex mcp add onmc -- onmc serve --mcp

ONMC exposes 12 MCP tools, including recall, search_memory, get_brief, guard_task, record_attempt, record_memory, get_coverage, get_digest, get_skills, get_profile, and ask.

See integration guides.

Memory travels with git

onmc sync --commit
git add .agent-memory/ CLAUDE.md
git commit -m "chore: sync agent memory"

Fresh clone:

onmc init
onmc sync --restore

.onmc/            local SQLite, traces, logs, evals; gitignored
.agent-memory/    portable JSON, skills, receipts, latest brief; commit selectively
CLAUDE.md         generated project context; commit if your team uses it

The format is documented in AGENT-MEMORY-SPEC.md. Any tool can implement a reader or writer. Validate an export with onmc spec validate.

Proof, without hiding methodology

onmc benchmark
onmc bench

onmc benchmark labels every result:

• MEASURED: recall latency, hits per query, brain composition, terse-vs-verbose reduction, TOON-vs-JSON reduction
• SIM: repeated-failure, wasted-attempt, and context-token deltas from the deterministic harness

The built-in five-task simulation currently reports repeated-failure rate 100% -> 0%, nine fewer wasted attempts, and -97% context-token proxy usage. These are synthetic harness results, not a claim about every production repository. Run onmc benchmark against your own brain for measured repo-specific numbers.

Local-first and safety boundaries

• Core memory, brief, guard, audit, eval, replay, benchmark, and sync paths work without an LLM.
• Optional providers are used only after explicit configuration; secrets stay in environment variables.
• Dashboard binds to 127.0.0.1 by default and makes no external asset requests.
• .onmc/ remains local. Review .agent-memory/ before committing because memories and receipts may contain repository details.
• Autonomous loops edit real files. Use a branch/worktree, a narrow verifier, and explicit budgets.
• MCP policy classification helps enforce a pipeline policy but is not a process sandbox.

Command map

Need	Commands
Start	setup, doctor, status, ui, tui
Understand	brief, why, blame, codegraph, ask, onboard, digest
Remember	ingest, mine, capture, memory, consolidate, sync, pull
Execute	autopilot, loop, solve, review, teach
Verify	check, guard, recall, audit, eval, replay, benchmark
Measure	evolution, savings
Observe	trace, report, hud, statusline
Integrate	plug, hooks, serve --mcp, gh-aw, mcp
Share	wiki --format obsidian, ui --export, .agent-memory/, skill export

Full generated options: docs/cli-reference.md.

Python API

import onmc

repo = onmc.init(".")
repo.ingest()
brief = repo.brief(task="fix checkout coupon failures", style="compact", max_tokens=500)
memories = repo.memory.search(files=["src/checkout/service.py"])
task = repo.task.start(title="Fix checkout coupon failures")
repo.sync.commit()

Documentation

• Demo: two agents, one brain
• Shipped capabilities
• CLI reference
• Architecture
• Memory model
• Dashboard
• Agent-native workflows
• Launch kit

Development

git clone https://github.com/adaline-ankit/oh-no-my-claudecode
cd oh-no-my-claudecode
pip install -e ".[dev]"
ruff check .
mypy src
pytest --cov=oh_no_my_claudecode --cov-report=term-missing
python scripts/generate-cli-reference.py --check
python -m build
python -m twine check dist/*

Contributing

Issues and pull requests welcome. Start with CONTRIBUTING.md, then look for good first issue.

License

MIT. See LICENSE.