# https://github.com/adaline-ankit/oh-no-my-claudecode Project Manual

Generated at: 2026-06-27 13:58:52 UTC

## Table of Contents

- [Project Overview & Architecture](#page-1)
- [Autonomous Execution: Loop, Autopilot, Swarm & No-Mistakes Gate](#page-2)
- [Memory Layer & Code Intelligence](#page-3)
- [Integration, Observability & Operations](#page-4)

<a id='page-1'></a>

## Project Overview & Architecture

### Related Pages

Related topics: [Autonomous Execution: Loop, Autopilot, Swarm & No-Mistakes Gate](#page-2), [Memory Layer & Code Intelligence](#page-3), [Integration, Observability & Operations](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/README.md)
- [src/oh_no_my_claudecode/__init__.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/__init__.py)
- [src/oh_no_my_claudecode/api.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/api.py)
- [src/oh_no_my_claudecode/loop/engine.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/loop/engine.py)
- [src/oh_no_my_claudecode/ingest/pipeline.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/ingest/pipeline.py)
- [src/oh_no_my_claudecode/ingest/repo_tree.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/ingest/repo_tree.py)
- [src/oh_no_my_claudecode/ingest/docs.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/ingest/docs.py)
- [src/oh_no_my_claudecode/ingest/llm_extractor.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/ingest/llm_extractor.py)
- [src/oh_no_my_claudecode/models/brief.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/models/brief.py)
- [src/oh_no_my_claudecode/hooks/boot_digest.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/hooks/boot_digest.py)
- [src/oh_no_my_claudecode/llm/base.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/llm/base.py)
- [src/oh_no_my_claudecode/importers/markdown.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/importers/markdown.py)
</details>

# Project Overview & Architecture

## Purpose and Scope

**oh-no-my-claudecode** (importable as `onmc`) is a local-first memory and orchestration layer for AI coding agents. Its central promise is a portable "repo brain" — a persistent, queryable knowledge store that follows a project through git, grounds agent prompts in past decisions and dead-ends, and runs verifiable autonomous loops without depending on a hosted service.

The project is explicitly scoped around four roles, each mapped to a CLI surface in `README.md`:

| Role | Example commands |
|------|------------------|
| Capture & curate | `init`, `ingest`, `memory`, `brief`, `sync` |
| Recall & guard | `recall`, `guard`, `brief`, `codegraph`, `task` |
| Verify & replay | `eval`, `benchmark`, `replay`, `trace` |
| Integrate | `plug`, `hooks`, `serve --mcp`, `gh-aw`, `mcp` |

The Python API mirrors this surface via `onmc.init(...)` returning a repository handle that exposes `ingest()`, `brief()`, `memory.search()`, and `task.start()` (Source: [README.md](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/README.md)).

## High-Level Architecture

The codebase is organized around a **memory → brief → agent → loop** pipeline. Ingestion feeds a SQLite-backed store; the store powers boot digests, task briefs, and guard rules; the loop engine wraps an external agent with falsifiable iteration contracts.

```mermaid
flowchart LR
    A[Repo files<br/>git history<br/>docs / commits] --> B[Ingest Pipeline<br/>scan + classify]
    B --> C[SQLite Storage<br/>.onmc/]
    C --> D[MemoryEntry / Skill<br/>TaskRecord]
    D --> E[Boot Digest<br/>≤ 400 tokens]
    D --> F[Task Brief<br/>compact / caveman]
    D --> G[Guard / Recall]
    E --> H[Agent prompt]
    F --> H
    G --> H
    H --> I[Loop Engine<br/>RECALL → ACT → VERIFY]
    I -->|WIN| J[DECISION memory]
    I -->|LOSS| K[FAILED_APPROACH memory]
    J --> C
    K --> C
```

Each box corresponds to a concrete subsystem:

- **Ingest Pipeline** — `ingest/pipeline.py` orchestrates per-source extraction. It merges `repo_tree` scanning (`ingest/repo_tree.py`), doc parsing (`ingest/docs.py`), git-derived memories, and optional LLM-assisted extraction (`ingest/llm_extractor.py`) before persisting `MemoryEntry` rows.
- **Storage** — A local SQLite database under `.onmc/` holds memories, skills, tasks, repo files, and eval data. `.onmc/` is gitignored per the README; portable JSON under `.agent-memory/` is what teams commit.
- **Briefs** — `models/brief.py` renders briefs in multiple styles. The compact and caveman modes produce terse bullets (files, memory, risk, test, rule) intentionally capped at small token budgets.
- **Boot Digest** — `hooks/boot_digest.py` emits a ≤ ~400-token reminder on every session start (startup/resume/clear), drawing from invariants, hotspots, active tasks, and top skills.
- **Loop Engine** — `loop/engine.py` implements memory-grounded iteration with a six-step contract: RECALL → PROMPT → ACT → VERIFY → CONTRACT (WIN or LOSS) → ESCALATE/NO-PROGRESS.

## Memory Pipeline

The pipeline deliberately separates deterministic extraction from optional LLM enrichment. `_git_memories_for_paths` in `ingest/pipeline.py` resolves commit history against file buckets, while `ingest/llm_extractor.py` provides structured prompts that ask a provider to return JSON arrays of `{kind, title, summary, confidence}` items — gated by a `confidence >= 0.75` (or 0.7 for commits) threshold to suppress generic advice.

Document ingestion (`ingest/docs.py`) classifies each markdown section into a `MemoryKind` (decision, invariant, doc_fact, validation_rule), assigns a confidence, and discards non-English summaries by zeroing their score. Repository-tree ingestion (`ingest/repo_tree.py`) records `RepoFileRecord` rows, derives a primary source layout memory when source-like directories are observed, and skips paths inside `.onmc/` to avoid recursive self-ingestion.

## Loop Engine and Iteration Contracts

The loop engine is the system's most distinctive architectural choice. Each iteration follows a strict prediction-outcome contract documented at the top of `loop/engine.py`:

1. **RECALL** — `compile_guard` produces dead-ends (what NOT to try) and `compile_prompt_recall` produces relevant memories. Both calls are wrapped in `try/except` blocks so a recall failure never aborts the loop.
2. **PROMPT** — Goal plus the assembled brief is injected into the agent.
3. **ACT** — `agent_runner(prompt, escalation_level)` produces an `AgentRunResult` containing an action summary and prediction.
4. **VERIFY** — `verify_runner(command)` returns a `VerifyOutcome`.
5. **CONTRACT** — On WIN, a `DECISION` memory is recorded; on LOSS, a `FAILED_APPROACH` memory is recorded, which the guard will surface in subsequent iterations to block the same path.
6. **ESCALATE / NO-PROGRESS** — Consecutive losses beyond `escalation_threshold` raise `escalation_level`; identical `(files, verify_output)` signatures repeating within `no_progress_window` halt the loop.

The engine also supports durable checkpoint/resume (added in v0.47), a token-storm circuit breaker plus worktree isolation/rollback (v0.46), and a No-Mistakes PR gate (v0.48). v0.50 introduced a fix ensuring that agent auth/API errors can never be reported as "verified".

## Local-First Boundaries and Safety

The README states that core memory, brief, guard, audit, eval, replay, and benchmark paths work **without an LLM**. Optional providers (`llm/base.py`) are only consulted after explicit configuration; when used, `generate_structured` raises `LLMProviderError` on either unparseable JSON or JSON that fails Pydantic schema validation, so silent hallucinations cannot leak into memory.

The dashboard binds to `127.0.0.1` by default and makes no external asset requests. Autonomous loops edit real files, so the README recommends using a branch or worktree. The `.agent-memory/` directory contains portable JSON (memories, skills, receipts, latest brief) and should be reviewed before committing because receipts may reference repository details.

Recent releases (v0.49–v0.52) extend this foundation with accountable agent swarms, in-session subagent fan-out, and an "Agent Ops" batch covering codegraph, reuse detection, and conventions — all built on the same memory → brief → loop substrate described above.

## See Also

- [CLI Reference](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/docs/cli-reference.md)
- [Memory Model](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/docs/memory-model.md)
- [Architecture Details](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/docs/architecture.md)
- [Agent-Native Workflows](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/docs/agent-native-workflows.md)
- [AGENT-MEMORY-SPEC.md](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/AGENT-MEMORY-SPEC.md)

---

<a id='page-2'></a>

## Autonomous Execution: Loop, Autopilot, Swarm & No-Mistakes Gate

### Related Pages

Related topics: [Project Overview & Architecture](#page-1), [Memory Layer & Code Intelligence](#page-3), [Integration, Observability & Operations](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/oh_no_my_claudecode/loop/__init__.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/loop/__init__.py)
- [src/oh_no_my_claudecode/loop/engine.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/loop/engine.py)
- [src/oh_no_my_claudecode/loop/models.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/loop/models.py)
- [src/oh_no_my_claudecode/loop/adapters.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/loop/adapters.py)
- [src/oh_no_my_claudecode/loop/checkpoint.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/loop/checkpoint.py)
- [src/oh_no_my_claudecode/loop/receipt.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/loop/receipt.py)
- [src/oh_no_my_claudecode/loop/templates.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/loop/templates.py)
- [README.md](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/README.md)
</details>

# Autonomous Execution: Loop, Autopilot, Swarm & No-Mistakes Gate

## Overview & Command Surface

`oh-no-my-claudecode` (ONMC) provides four progressively-bounded entry points for letting an agent execute repository work end-to-end. All four share the same memory-grounded loop engine and write tamper-evident receipts on completion.

| Command | Role | Introduced |
|---|---|---|
| `onmc loop "<goal>"` | Accountable autonomous loop — real Claude/Codex/OpenCode execution with dead-end avoidance and verifier gates | v0.26 |
| `onmc autopilot "<goal>"` | Full KNOW→(PLAN)→ACT→PROVE→LEARN cycle, ends with a "your brain grew" summary | v0.40-era |
| `onmc swarm` | Parallel accountable agent swarm with hard abort (v0.49) and in-session token-free fan-out (v0.51) | v0.49 |
| `onmc nomistakes "<goal>"` | No-Mistakes PR gate: audit + eval + isolated autopilot + verifier + receipt verdict; exits nonzero unless approved | v0.48 |

`onmc autopilot` is implemented on top of the loop engine: it adds an optional planning step (split across expensive-plan / cheap-execute models via `--plan-with` / `--execute-with`, v0.45), then delegates the actual file-editing iterations to `run_loop`. `onmc nomistakes` wraps `autopilot` with additional audit/eval gates and requires a verified receipt before marking the run as mergeable. Source: [README.md](README.md).

`onmc loop` does not replace Claude Code, Codex, or OpenCode — it gives them durable repository knowledge, bounded execution, and evidence. All three adapters are real headless CLI shims wired into a single `AgentRunner` protocol.

## The Loop Engine: Per-Iteration Cycle

The heart of the system is `run_loop` in [`src/oh_no_my_claudecode/loop/engine.py`](src/oh_no_my_claudecode/loop/engine.py). Each iteration is a fixed seven-step cycle so that outcomes are falsifiable and dead-ends propagate into the next attempt.

```mermaid
flowchart TD
    A[1. RECALL<br/>compile_guard + prompt_recall] --> B[2. PROMPT<br/>inject brief into agent]
    B --> C[3. ACT<br/>agent_runner -> AgentRunResult]
    C --> D[4. VERIFY<br/>verify_runner -> VerifyOutcome]
    D --> E{verify_passed?}
    E -- yes --> F[5a. WIN -> DECISION memory]
    E -- no --> G[5b. LOSS -> FAILED_APPROACH memory]
    G --> H{consecutive_losses >= threshold?}
    H -- yes --> I[6. ESCALATE level++]
    H -- no --> J
    I --> J[7. NO-PROGRESS check<br/>same signature x window -> stop]
    F --> K[Emit iteration contract]
    J --> K
```

Step-by-step contract from the engine docstring (Source: [src/oh_no_my_claudecode/loop/engine.py:1-19](src/oh_no_my_claudecode/loop/engine.py)):

1. **RECALL** — `compile_guard` collects dead-ends; `compile_prompt_recall` collects relevant memories. Both feed the brief.
2. **PROMPT** — goal + brief is injected into the agent prompt.
3. **ACT** — the `AgentRunner` (chosen adapter) returns an `AgentRunResult` containing output text, tokens, cost, and `files_touched` derived from a real `git status --porcelain` diff.
4. **VERIFY** — `verify_runner(command)` runs the configured verifier (default `pytest`) and produces a `VerifyOutcome`.
5. **CONTRACT** — WIN writes a `DECISION` memory; LOSS writes a `FAILED_APPROACH` memory that the next iteration's `compile_guard` will surface so the agent cannot repeat it.
6. **ESCALATE** — when `consecutive_losses >= escalation_threshold`, `escalation_level` increments.
7. **NO-PROGRESS** — when the same `(files, verify_output)` signature repeats `no_progress_window` times, the loop stops.

The brief itself is composed in `_build_brief`: relevant memories, dead-ends (DON'T-REPEAT section), last-failure summary (truncated to 500 chars of verify output), and an escalation hint. Recall and guard are best-effort — they never fail the loop (Source: [src/oh_no_my_claudecode/loop/engine.py](src/oh_no_my_claudecode/loop/engine.py)).

## Configuration, Templates & Safety Limits

`LoopConfig` in [`src/oh_no_my_claudecode/loop/models.py`](src/oh_no_my_claudecode/loop/models.py) is the single source of truth for runtime caps:

| Field | Default | Purpose |
|---|---|---|
| `max_iterations` | `10` | Hard iteration cap |
| `budget_tokens` | `None` | Token budget |
| `verify_command` | `"pytest"` | Shell command used by the verifier |
| `escalation_threshold` | `3` | Consecutive losses before `escalation_level++` |
| `no_progress_window` | `3` | Repeated signature window that triggers stop |
| `max_cost_usd` | `None` | Stop before the next iteration when cumulative cost exceeds this value (v0.34) |
| `max_wall_seconds` | `None` | Stop when wall-clock elapsed seconds exceed this value (v0.34) |
| `duplicate_action_limit` | `0` | Suppress obviously duplicated actions |

These caps are what make the loop "accountable" rather than open-ended. v0.46 added the token-storm circuit breaker, and v0.48 added worktree isolation/rollback via `--isolate`. v0.47 added durable checkpoint/resume (`FileCheckpointStore` / `InMemoryCheckpointStore`, exposed via `--resume`) so an interrupted run can pick up from its last `CheckpointState`.

Built-in templates from [`src/oh_no_my_claudecode/loop/templates.py`](src/oh_no_my_claudecode/loop/templates.py) fill sensible defaults that explicit flags always override:

- **`ci-healer`** — fix failing CI without changing public behaviour; verify defaults to `pytest`; 15-iteration cap.
- **`pr-babysitter`** — keep a pull request green (rebase, fix conflicts, re-run checks); 8 iterations, less aggressive.
- **`issue-to-pr`** — implement the described issue as a PR-ready change with passing tests; 20 iterations, more exploration room.

Every loop run produces a tamper-evident `RunReceipt` (Source: [src/oh_no_my_claudecode/loop/receipt.py](src/oh_no_my_claudecode/loop/receipt.py)):

- SHA-256 hash chain across all iteration contracts: `h_i = sha256(h_{i-1} + sig_i + vp_i + files_i + tokens_i)`.
- Git tree SHA and diff SHA so external auditors can reproduce the exact repository state.
- Verifier command, final exit code, token/cost/wall-time accounting.
- Filename derived from the receipt content (not wall-clock time) so receipts are idempotent when replayed.
- Reproducibility envelope (model/tool/config hashes) added in v0.44.

A v0.50 patch ensures that agent authentication or API errors can never report `verified=True` — only an actual verifier pass counts.

## Agent Adapters & Cross-Tool Integration

The loop engine is agent-agnostic. [`src/oh_no_my_claudecode/loop/adapters.py`](src/oh_no_my_claudecode/loop/adapters.py) ships three real headless adapters, all reachable through `make_agent_runner(name, ...)`:

- **`ClaudeCliAdapter`** — shells out to `claude -p <prompt> --output-format json` and parses the structured response to extract text, tokens, and cost.
- **`CodexCliAdapter`** — shells out to `codex exec <prompt>` (headless mode); returns raw stdout as output (token usage not exposed by Codex CLI).
- **`OpenCodeCliAdapter`** — shells out to `opencode run --format json [--model provider/model] <prompt>` and parses the JSON event stream defensively for text and tokens. First-class support added in v0.43.

All three compute `files_touched` by snapshotting `git status --porcelain` before and after the agent call and diffing the two, so the list is always derived from the real working tree rather than fabricated. Each adapter accepts an injectable `CommandRunner` so tests can supply canned subprocess results without spawning a real agent process.

`onmc swarm` (v0.49) fans a single goal out to a parallel team of these adapters, with hard-abort semantics when one branch verifies. v0.51 added an in-session, token-free swarm mode that uses subagents within a single session rather than separate CLI invocations. `onmc nomistakes` layers the swarm/loop on top of an isolated worktree, requires audit + eval passes, and will refuse to mark a PR as mergeable without a verified receipt.

## See Also

- [Architecture](docs/architecture.md)
- [Memory model](docs/memory-model.md)
- [Shipped capabilities](docs/shipped-capabilities.md)
- [CLI reference](docs/cli-reference.md)
- [Agent-native workflows](docs/agent-native-workflows.md)

---

<a id='page-3'></a>

## Memory Layer & Code Intelligence

### Related Pages

Related topics: [Project Overview & Architecture](#page-1), [Autonomous Execution: Loop, Autopilot, Swarm & No-Mistakes Gate](#page-2), [Integration, Observability & Operations](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/oh_no_my_claudecode/ingest/llm_extractor.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/ingest/llm_extractor.py)
- [src/oh_no_my_claudecode/ingest/docs.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/ingest/docs.py)
- [src/oh_no_my_claudecode/ingest/repo_tree.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/ingest/repo_tree.py)
- [src/oh_no_my_claudecode/ingest/pipeline.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/ingest/pipeline.py)
- [src/oh_no_my_claudecode/importers/markdown.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/importers/markdown.py)
- [src/oh_no_my_claudecode/hooks/boot_digest.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/hooks/boot_digest.py)
- [src/oh_no_my_claudecode/hooks/prompt_recall.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/hooks/prompt_recall.py)
- [src/oh_no_my_claudecode/hooks/brief_compiler.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/hooks/brief_compiler.py)
- [src/oh_no_my_claudecode/loop/engine.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/loop/engine.py)
- [src/oh_no_my_claudecode/llm/base.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/llm/base.py)
</details>

# Memory Layer & Code Intelligence

## Overview and Purpose

The Memory Layer & Code Intelligence subsystem turns a repository into a queryable, "brain-like" substrate that agents can recall from at prompt time and reason with during autonomous loops. It is local-first: a SQLite store plus a JSON projection under `.agent-memory/` hold memories, skills, tasks, and receipts, while an LLM is invoked only for explicit extraction steps and is never on the hot recall path. The pipeline is the entry point for converting source code, documentation, repository layout, and git history into structured `MemoryEntry` records. At runtime, recall is assembled into a compact "boot digest" injected on session start and a "prompt recall" block injected on every `UserPromptSubmit`. The loop engine then combines relevant memories (signal) with guard-listed dead-ends (anti-signal) to drive a falsifiable prediction/outcome iteration.

## Ingestion: Building the Repo Brain

### LLM-based extraction

The extraction layer uses three specialised prompts that all share a common JSON-array schema with a `confidence` field and a `files_mentioned` list:

| Prompt | Source | Confidence floor | Output kinds |
|---|---|---|---|
| Commit prompt | Batched commit subjects + file lists | `0.7` | invariant, gotcha, decision, validation_rule |
| Source-file prompt | Files flagged by churn rank or signal scan (`TODO`, `FIXME`, `must`, `never`, `DO NOT`) | `0.75` | invariant, gotcha, validation_rule, decision |
| Doc prompt | Markdown documents from configured globs | `0.75` | decision, invariant, validation_rule |

Source: [src/oh_no_my_claudecode/ingest/llm_extractor.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/ingest/llm_extractor.py)

`should_run_source_extraction` guards the cost of source-file extraction: it only fires when fewer than eight memories were already mined from commits. `should_extract_file` then narrows the candidate set to (a) anything in `tests/`, `spec/`, or matching `test_*` / `*_test.py` patterns, (b) the top-20 churn candidates, or (c) files containing signal keywords such as `TODO`, `FIXME`, `WARNING`, `must`, `never`, `always`, `DO NOT`, `invariant`, or an `ALL_CAPS` constant. Everything below the confidence floor is dropped before it reaches storage.

### Documentation and repository-tree memories

Documentation ingestion scans the tree with a configurable list of globs and excludes `README` / `CHANGELOG` / `CONTRIBUTING` translations, common TOC headings, and output files such as `CLAUDE.md`, `AGENTS.md`, and `.cursorrules`. The resulting memories are tagged with `SourceType.DOC` and `MemoryKind.DOC_FACT` (or `DESIGN_CONFLICT` / `GOTCHA`) so they are distinguishable from code-derived facts at recall time.

Source: [src/oh_no_my_claudecode/ingest/docs.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/ingest/docs.py)

The repository-tree pass walks `os.walk` with a configurable `exclude_dirs` list, drops any path that lives under `.onmc/`, and emits a single low-confidence `MemoryKind.DOC_FACT` summary of source-like directories (for example, `["src", "tests"]`) tagged `["layout", "source"]`. This gives agents a navigation hint when no other facts are available yet.

Source: [src/oh_no_my_claudecode/ingest/repo_tree.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/ingest/repo_tree.py)

The git-memory step in the pipeline filters commit-derived memories by either an exact path match or a `path_bucket` overlap, so that a request for memories about `src/checkout/service.py` does not pull in memories tagged to unrelated modules.

Source: [src/oh_no_my_claudecode/ingest/pipeline.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/ingest/pipeline.py)

### Markdown import

Generic markdown can be ingested as either skills (one per file) or memories (one per `##` section), tagged with `imported:md`. The module reuses parsing helpers from the `hermes` and `omc` importers, so it has no DB dependency and can run in isolation.

Source: [src/oh_no_my_claudecode/importers/markdown.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/importers/markdown.py)

## Runtime: Recall Surfaces

### Boot digest

`compile_boot_digest` produces a compact, full-markdown reminder that is injected on every session start, resume, or clear. It targets ≤ 400 tokens, surfaces user preferences, derived profile items, the top three invariants, three hotspots, two active tasks, and the top two skills, then fires `recall_surfaced` and `profile_injected` events to the context-firewall side sink for observability.

Source: [src/oh_no_my_claudecode/hooks/boot_digest.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/hooks/boot_digest.py)

### Per-prompt recall

`compile_prompt_recall` is the hot path for the `UserPromptSubmit` hook. It is pure and testable: read from storage, produce markdown, never touch stdin/stdout directly. Stale / orphaned / unanchored memories receive a `0.35` weight multiplier so a brand-new repository without fresh signals still surfaces something, but old memories never dominate. When auto-inject skills match the prompt, a compact "Relevant skills" block is appended and each surfaced skill has its `use_count` bumped in a fire-and-forget context. `ONMC_VERBOSE=1` switches to full markdown; `ONMC_TERSE=1` forces terse outside hook context; `ONMC_FIREWALL=0` disables the side-sink emit.

Source: [src/oh_no_my_claudecode/hooks/prompt_recall.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/hooks/prompt_recall.py)

### Continuation brief

`compile_continuation_brief` is the post-compaction bridge. Given the latest `CompactionSnapshotRecord` plus a `TaskRecord` and the recent decisions, it assembles a four-section markdown brief ("Where we are", "What was just decided", "What was being attempted", "Next step") and trims each section so the total stays under 400 tokens.

Source: [src/oh_no_my_claudecode/hooks/brief_compiler.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/hooks/brief_compiler.py)

## Memory-Grounded Loops

The loop engine turns the recall surfaces into action. Each iteration runs six steps: RECALL (guard + prompt recall) → PROMPT (goal + brief) → ACT (agent runner) → VERIFY (verify runner) → CONTRACT (win → decision memory, loss → `FAILED_APPROACH` memory) → ESCALATE. A loss writes a `FAILED_APPROACH` entry into the guard compiler, which then becomes the "DON'T REPEAT" section of the next iteration's brief. If the same `(files, verify_output)` signature repeats more than `no_progress_window` times, the loop stops.

Source: [src/oh_no_my_claudecode/loop/engine.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/loop/engine.py)

```mermaid
flowchart LR
    A[Source / Docs / Git] --> B[Ingest Pipeline]
    B --> C[(SQLite + .agent-memory/)]
    C --> D[Boot Digest]
    C --> E[Prompt Recall]
    C --> F[Loop Brief]
    D --> G[Agent Session]
    E --> G
    F --> H[Loop Engine]
    H -->|WIN| I[DECISION memory]
    H -->|LOSS| J[FAILED_APPROACH]
    J --> F
    G --> K[LLM Provider]
    K -->|structured| B
```

The LLM provider layer returns typed structured output through `generate_structured`, wrapping `parse_llm_json` and pydantic validation. Failures (unparseable JSON, schema mismatch) raise `LLMProviderError` and never silently fall through, so ingest cannot quietly pollute the brain with malformed rows.

Source: [src/oh_no_my_claudecode/llm/base.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/llm/base.py)

## See Also

- [Architecture overview](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/docs/architecture.md)
- [Memory model](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/docs/memory-model.md)
- [CLI reference](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/docs/cli-reference.md)
- [Agent-native workflows](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/docs/agent-native-workflows.md)
- v0.52.0 release notes introduce the `codegraph` Agent Ops surface that reuses the same recall layer.

---

<a id='page-4'></a>

## Integration, Observability & Operations

### Related Pages

Related topics: [Project Overview & Architecture](#page-1), [Autonomous Execution: Loop, Autopilot, Swarm & No-Mistakes Gate](#page-2), [Memory Layer & Code Intelligence](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/README.md)
- [src/oh_no_my_claudecode/loop/engine.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/loop/engine.py)
- [src/oh_no_my_claudecode/loop/adapters.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/loop/adapters.py)
- [src/oh_no_my_claudecode/loop/models.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/loop/models.py)
- [src/oh_no_my_claudecode/llm/base.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/llm/base.py)
- [src/oh_no_my_claudecode/hooks/boot_digest.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/hooks/boot_digest.py)
- [src/oh_no_my_claudecode/ingest/llm_extractor.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/ingest/llm_extractor.py)
- [src/oh_no_my_claudecode/models/brief.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/models/brief.py)
- [src/oh_no_my_claudecode/ingest/docs.py](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/src/oh_no_my_claudecode/ingest/docs.py)
</details>

# Integration, Observability & Operations

ONMC ("oh-no-my-claudecode") ships an integration surface that lets a single memory brain drive multiple coding agents, an observability surface that records what every iteration actually did, and an operational surface that turns those signals into reproducible, accountable runs. This page covers the modules that wire those three layers together.

## Cross-Agent Integration Adapters

The loop engine is decoupled from any one agent CLI through an `AgentRunner` Protocol, with concrete adapters provided for the three supported executables. `ClaudeCliAdapter` shells out to `claude -p <prompt> --output-format json` and parses the structured response to recover text, tokens, and cost. `CodexCliAdapter` runs `codex exec <prompt>` in headless mode and returns raw stdout (token usage is not exposed by that CLI). `OpenCodeCliAdapter` calls `opencode run --format json [--model <provider/model>] <prompt>` and parses the JSON event stream defensively for both text and token accounting. All three compute `files_touched` by diffing `git status --porcelain` snapshots taken *before* and *after* the agent call, so the list is always derived from the real working tree rather than fabricated.
Source: [src/oh_no_my_claudecode/loop/adapters.py:1-30]()

A factory `make_agent_runner(name, repo_root=..., model=...)` returns the right adapter by string name, and every adapter accepts an injectable `CommandRunner` so tests can supply canned subprocess results without spawning a real agent. Per the v0.50 release notes, an accountability fix (PR #129) ensures that agent auth or API errors can never be reported as a verified pass — the verifier must observe an actual command exit before the iteration counts as a win. Source: [README.md:1-40](), [src/oh_no_my_claudecode/loop/adapters.py:1-30]()

MCP integration is exposed through `onmc serve --mcp`, which registers twelve MCP tools (`recall`, `search_memory`, `get_brief`, `guard_task`, `record_attempt`, `record_memory`, `get_coverage`, `get_digest`, `get_skills`, `get_profile`, `ask`, and related helpers). Codex registration is one line: `codex mcp add onmc -- onmc serve --mcp`. Claude Code users get a marketplace plugin (`/plugin install oh-no-my-claudecode@onmc`), while Cursor gets a generated `.cursor/rules/onmc.md`, and "OMC / OMX" receives an adapter guide over ONMC memory commands. Source: [README.md:1-60]()

## Observability: Boot Recall, Traces & Audit

Observability starts the moment a session begins. The boot digest builder in `hooks/boot_digest.py` assembles a compact markdown block from preferences, profile-derived mistakes, invariants, hotspots, active tasks, and top skills. It fires `_firewall_emit_boot_recall(repo_root, token_count)` and `_firewall_emit_profile_injected(repo_root, profile)` so external firewalls can correlate what was injected versus what was used. The block is capped at `_MAX_USER_PREFS`, `_MAX_INVARIANTS`, `_MAX_HOTSPOTS`, and `_MAX_ACTIVE_TASKS` to keep the boot payload bounded. Source: [src/oh_no_my_claudecode/hooks/boot_digest.py:1-40]()

```mermaid
flowchart LR
  A[Session start] --> B[boot_digest.py<br/>assemble profile + memories]
  B --> C[firewall events<br/>boot_recall, profile_injected]
  B --> D[loop engine<br/>RECALL → PROMPT → ACT → VERIFY]
  D --> E[iteration receipt<br/>prediction · verify_output · tokens]
  E --> F[(SQLite .onmc/<br/>traces, evals, receipts)]
  F --> G[onmc trace<br/>onmc ui / tui]
```

During ingestion, the LLM extractor prompts the provider to return structured engineering knowledge (invariants, gotchas, validation rules, decisions) with a confidence floor of 0.75. Items below the threshold are dropped, and the prompt explicitly forbids generic programming advice, so the memory store accumulates only codebase-specific signal. Source: [src/oh_no_my_claudecode/ingest/llm_extractor.py:1-40]()

Operators inspect signals through three viewports: a local web dashboard (`onmc ui`), a terminal browser (`onmc tui`), and an Obsidian-compatible knowledge graph (`onmc wiki`). The Trace Observatory (`onmc trace`) emits session events, memory hit rate, loop signals, and an estimated token ROI, and it can export OpenTelemetry-compatible JSON. Source: [README.md:1-60]()

## Operations: Loops, Templates, Receipts & Swarms

The autonomous loop is the operational heart. Each iteration runs the contract **RECALL → PROMPT → ACT → VERIFY → CONTRACT → ESCALATE → NO-PROGRESS**, and best-effort recall / guard compilation never fail the loop — they are wrapped in broad `except Exception: pass` clauses so a flaky memory lookup cannot crash a running iteration. Source: [src/oh_no_my_claudecode/loop/engine.py:1-40]()

Hard limits are first-class fields on `LoopConfig`: `max_iterations`, `budget_tokens`, `verify_command`, `escalation_threshold`, `no_progress_window`, `max_cost_usd`, `max_wall_seconds`, and `duplicate_action_limit`. v0.46 added a token-storm circuit breaker plus worktree isolation/rollback (PR #121). v0.47 added durable checkpoint/resume and ready-to-run templates such as `ci-healer`, `pr-babysitter`, and `issue-to-pr` (PR #123). v0.48 introduced the No-Mistakes PR gate (`onmc nomistakes`) that runs audit + optional eval + isolated autopilot + verifier and exits nonzero unless the result is approved. Source: [src/oh_no_my_claudecode/loop/models.py:1-30](), [README.md:1-60]()

Tamper-evident receipts (v0.44, PR #117) record the git tree hash, the git diff SHA, a hash chain, and a reproducibility envelope containing the model, tool, and configuration hashes that produced a given outcome. v0.49 introduced the accountable agent swarm with hard abort (PR #127), and v0.51 introduced an in-session subagent swarm with token-free parallel fan-out (PR #131). v0.52 (PR #133) layers Agent Ops batch 1 on top: codegraph, reuse detection, and conventions surfacing as a token-free swarm. Source: [README.md:1-60]()

## LLM Provider Boundary

Structured extraction goes through a single abstract base, `LLMClient.generate_structured`, which wraps a raw `generate` call with `json_only_request`, then attempts `parse_llm_json` and finally `response_model.model_validate`. Two distinct errors are emitted: `LLMProviderError("Provider response was not valid JSON for structured parsing.")` and `LLMProviderError("Provider response did not match the expected structured schema.")`. The raw response is logged truncated to 500 characters so failures are diagnosable without leaking the full prompt. Source: [src/oh_no_my_claudecode/llm/base.py:1-30]()

The same boundary protects the brief generator. `Brief._to_caveman_markdown` renders a fixed layout of task, repo, top five files to inspect, top three memories, top three risks, top three validation checks, and an explicit "no broad grep dump, no repeat failed path" rule — giving operators a deterministic, terse rendering they can diff between iterations. Source: [src/oh_no_my_claudecode/models/brief.py:1-20]()

## Common Failure Modes

- **Loop stalls without progress.** Triggered when the same `(files_touched, verify_output)` signature repeats `no_progress_window` times. Source: [src/oh_no_my_claudecode/loop/engine.py:1-40]()
- **Agent auth/API errors silently passing.** Mitigated by the v0.50 verifier fix — the verifier must observe an actual command exit before reporting verified.
- **LLM returns unparseable JSON.** Caught and re-raised as `LLMProviderError`; the raw text is logged truncated.
- **Memory queries blocking a loop.** Recall and guard compilation are wrapped in `except Exception: pass` so they degrade to "no extra context" rather than crashing the run.
- **Drift between local `.onmc/` and committed `.agent-memory/`.** Local state holds SQLite, traces, logs, and evals (gitignored); portable JSON in `.agent-memory/` plus a generated `CLAUDE.md` are what travel through git.

## See Also

- [Architecture](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/docs/architecture.md)
- [CLI reference](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/docs/cli-reference.md)
- [Dashboard](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/docs/ui-dashboard.md)
- [Agent-native workflows](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/docs/agent-native-workflows.md)
- [Integration guides](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/docs/integrations/README.md)
- [Memory model](https://github.com/adaline-ankit/oh-no-my-claudecode/blob/main/docs/memory-model.md)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: adaline-ankit/oh-no-my-claudecode

Summary: Found 17 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

## 1. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v0.48.0
- User impact: Upgrade or migration may change expected behavior: v0.48.0
- Evidence: failure_mode_cluster:github_release | https://github.com/adaline-ankit/oh-no-my-claudecode/releases/tag/v0.48.0

## 2. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.host_targets | https://github.com/adaline-ankit/oh-no-my-claudecode

## 3. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v0.42.0
- User impact: Upgrade or migration may change expected behavior: v0.42.0
- Evidence: failure_mode_cluster:github_release | https://github.com/adaline-ankit/oh-no-my-claudecode/releases/tag/v0.42.0

## 4. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v0.43.0
- User impact: Upgrade or migration may change expected behavior: v0.43.0
- Evidence: failure_mode_cluster:github_release | https://github.com/adaline-ankit/oh-no-my-claudecode/releases/tag/v0.43.0

## 5. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v0.44.0
- User impact: Upgrade or migration may change expected behavior: v0.44.0
- Evidence: failure_mode_cluster:github_release | https://github.com/adaline-ankit/oh-no-my-claudecode/releases/tag/v0.44.0

## 6. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v0.45.0
- User impact: Upgrade or migration may change expected behavior: v0.45.0
- Evidence: failure_mode_cluster:github_release | https://github.com/adaline-ankit/oh-no-my-claudecode/releases/tag/v0.45.0

## 7. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v0.46.0
- User impact: Upgrade or migration may change expected behavior: v0.46.0
- Evidence: failure_mode_cluster:github_release | https://github.com/adaline-ankit/oh-no-my-claudecode/releases/tag/v0.46.0

## 8. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v0.47.0
- User impact: Upgrade or migration may change expected behavior: v0.47.0
- Evidence: failure_mode_cluster:github_release | https://github.com/adaline-ankit/oh-no-my-claudecode/releases/tag/v0.47.0

## 9. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v0.49.0
- User impact: Upgrade or migration may change expected behavior: v0.49.0
- Evidence: failure_mode_cluster:github_release | https://github.com/adaline-ankit/oh-no-my-claudecode/releases/tag/v0.49.0

## 10. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v0.50.0
- User impact: Upgrade or migration may change expected behavior: v0.50.0
- Evidence: failure_mode_cluster:github_release | https://github.com/adaline-ankit/oh-no-my-claudecode/releases/tag/v0.50.0

## 11. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v0.51.0
- User impact: Upgrade or migration may change expected behavior: v0.51.0
- Evidence: failure_mode_cluster:github_release | https://github.com/adaline-ankit/oh-no-my-claudecode/releases/tag/v0.51.0

## 12. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/adaline-ankit/oh-no-my-claudecode

## 13. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/adaline-ankit/oh-no-my-claudecode

## 14. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/adaline-ankit/oh-no-my-claudecode

## 15. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/adaline-ankit/oh-no-my-claudecode

## 16. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/adaline-ankit/oh-no-my-claudecode

## 17. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/adaline-ankit/oh-no-my-claudecode

<!-- canonical_name: adaline-ankit/oh-no-my-claudecode; human_manual_source: deepwiki_human_wiki -->