Metadata-Version: 2.4
Name: oh-no-my-claudecode
Version: 0.99.0
Summary: Memory-grounded autonomous coding loops for Claude Code and Codex.
Author: ONMC Contributors
License: MIT License
        
        Copyright (c) 2026 ONMC Contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
License-File: LICENSE
Keywords: agent-memory,agent-orchestration,autonomous-agents,claude-code,codex,coding-agents,developer-tools,mcp,verified-execution
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic<3.0,>=2.8
Requires-Dist: pyyaml<7.0,>=6.0
Requires-Dist: questionary>=2.0.0
Requires-Dist: rich<16.0,>=13.7
Requires-Dist: typer<1.0,>=0.12
Requires-Dist: watchdog>=3.0.0
Provides-Extra: autogen
Requires-Dist: pyautogen>=0.2; extra == 'autogen'
Provides-Extra: crewai
Requires-Dist: crewai>=0.80; extra == 'crewai'
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == 'dev'
Requires-Dist: mypy<3.0,>=1.11; extra == 'dev'
Requires-Dist: pre-commit<5.0,>=3.8; extra == 'dev'
Requires-Dist: pytest-cov<8.0,>=6.0; extra == 'dev'
Requires-Dist: pytest<10.0,>=8.3; extra == 'dev'
Requires-Dist: ruff<1.0,>=0.15; extra == 'dev'
Requires-Dist: twine<7.0,>=5.1; extra == 'dev'
Provides-Extra: fastembed
Requires-Dist: fastembed>=0.3; extra == 'fastembed'
Provides-Extra: langchain
Requires-Dist: langchain-community>=0.3; extra == 'langchain'
Requires-Dist: langchain-text-splitters>=0.3; extra == 'langchain'
Provides-Extra: litellm
Requires-Dist: litellm>=1.0; extra == 'litellm'
Provides-Extra: mem0
Requires-Dist: mem0ai>=0.1; extra == 'mem0'
Provides-Extra: sqlitevec
Requires-Dist: sqlite-vec>=0.1.0; extra == 'sqlitevec'
Provides-Extra: supermemory
Requires-Dist: supermemory>=0.1; extra == 'supermemory'
Provides-Extra: treesitter
Requires-Dist: tree-sitter-language-pack>=0.7; extra == 'treesitter'
Requires-Dist: tree-sitter<1.0,>=0.23; extra == 'treesitter'
Description-Content-Type: text/markdown

# oh-no-my-claudecode (`onmc`)

[![CI](https://github.com/adaline-ankit/oh-no-my-claudecode/actions/workflows/ci.yml/badge.svg)](https://github.com/adaline-ankit/oh-no-my-claudecode/actions)
[![Latest release](https://img.shields.io/github/v/release/adaline-ankit/oh-no-my-claudecode)](https://github.com/adaline-ankit/oh-no-my-claudecode/releases/latest)
[![PyPI version](https://badge.fury.io/py/oh-no-my-claudecode.svg)](https://pypi.org/project/oh-no-my-claudecode/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**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.

## Install (one line)

```bash
curl -fsSL https://raw.githubusercontent.com/adaline-ankit/oh-no-my-claudecode/main/install.sh | bash
```

The installer detects `uv` → `pipx` → `pip`, installs `oh-no-my-claudecode`, then runs
`onmc setup` to wire up hooks and MCP integration. Safe to re-run (idempotent). Never uses `sudo`.

### Alternative: manual install

```bash
# uv (recommended — isolated, fast)
uv tool install oh-no-my-claudecode
cd your-repo && onmc setup

# pipx
pipx install oh-no-my-claudecode
cd your-repo && onmc setup

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

## 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

```bash
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

```bash
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:

```bash
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:

```bash
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:

```bash
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.

```bash
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:

```text
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:

```text
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](CHANGELOG.md) for exact release notes.

## Real workflows

### Never retry yesterday's failed fix

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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:

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

Codex MCP registration:

```bash
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](docs/integrations/README.md).

## Memory travels with git

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

Fresh clone:

```bash
onmc init
onmc sync --restore
```

```text
.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](AGENT-MEMORY-SPEC.md). Any tool can implement a
reader or writer. Validate an export with `onmc spec validate`.

## Proof, without hiding methodology

```bash
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](docs/cli-reference.md).

## Python API

```python
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](docs/demo.md)
- [Shipped capabilities](docs/shipped-capabilities.md)
- [CLI reference](docs/cli-reference.md)
- [Architecture](docs/architecture.md)
- [Memory model](docs/memory-model.md)
- [Dashboard](docs/ui-dashboard.md)
- [Agent-native workflows](docs/agent-native-workflows.md)
- [Launch kit](docs/launch/README.md)

## Development

```bash
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](CONTRIBUTING.md), then look for
[`good first issue`](https://github.com/adaline-ankit/oh-no-my-claudecode/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).

## License

MIT. See [LICENSE](LICENSE).
