Metadata-Version: 2.4
Name: oh-no-my-claudecode
Version: 0.1.0
Summary: Repo-native memory and context compiler for coding agents.
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: cli,coding-agents,context,developer-tools,memory
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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: pydantic<3.0,>=2.8
Requires-Dist: pyyaml<7.0,>=6.0
Requires-Dist: rich<15.0,>=13.7
Requires-Dist: typer<1.0,>=0.12
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == 'dev'
Requires-Dist: mypy<2.0,>=1.11; extra == 'dev'
Requires-Dist: pre-commit<5.0,>=3.8; extra == 'dev'
Requires-Dist: pytest<9.0,>=8.3; extra == 'dev'
Requires-Dist: ruff<1.0,>=0.15; extra == 'dev'
Description-Content-Type: text/markdown

# oh-no-my-claudecode

`oh-no-my-claudecode` helps coding agents and engineers recover the high-signal, repo-specific context that static instructions and raw transcripts miss.

It is a memory-first, provenance-driven CLI that scans a local git repository, stores structured repo memory in `.onmc/`, and compiles compact task briefs for coding agents such as Claude Code, Codex, or similar tools.

P0 is intentionally conservative:

- no hosted service
- no vector database
- no mandatory LLM dependency
- no autonomous coding claims

The goal is better repo context recovery, not magic.

## Problem

Coding agents repeatedly lose repo-specific context:

- they forget documented decisions and invariants
- they revisit already-known hotspots
- they miss repo-specific validation patterns
- they overfit to static instructions that are too broad or stale

`onmc` addresses that by building a local memory layer from repo docs, git history, and file structure, then using it to compile a task-specific brief before an agent starts editing.

## Product Thesis

`oh-no-my-claudecode` is a repo-native memory and context compiler.

It:

- scans a local git repository
- extracts typed structured memory with provenance
- stores that memory locally in `.onmc/memory.db`
- stores durable task lifecycle records for active engineering work
- stores task-scoped attempt logs, including failed or partial approaches
- stores task-derived memory artifacts that preserve what worked, what did not, and what conflicted with design constraints
- compiles concise task briefs for coding agents
- stays useful without paid model access

## Features

- `onmc init` bootstraps `.onmc/` state for the current repository.
- `onmc ingest` indexes repo docs, file tree metadata, git history, hotspots, and validation hints.
- `onmc task ...` tracks task-scoped engineering memory with status, branch, labels, and final summaries.
- `onmc attempt ...` records what was tried during a task, including evidence and touched files.
- `onmc memory add ...` captures durable task-derived artifacts such as fixes, failed approaches, and design conflicts.
- `onmc memory list` and `onmc memory show` inspect stored memory with provenance.
- `onmc brief --task "..."` produces a compact markdown brief and pretty terminal output.
- `onmc status` reports repo root, ingest state, storage location, and config summary.

### Supported P0 Memory Kinds

- `doc_fact`
- `decision`
- `invariant`
- `hotspot`
- `git_pattern`
- `validation_rule`

## Installation

Python 3.11+ is required.

```bash
pip install oh-no-my-claudecode
```

For local development:

```bash
git clone <your-fork-or-repo-url>
cd oh-no-my-claudecode
pip install -e ".[dev]"
```

## Quickstart

Inside any git repository:

```bash
onmc init
onmc ingest
onmc task start --title "Fix flaky Redis cache invalidation bug" --description "Investigate test churn around cache invalidation" --label bug
onmc attempt add task-abc123def4 --summary "Try a narrower cache fix first" --kind fix_attempt --status tried --file src/cache.py
onmc memory add task-abc123def4 --type did_not_work --title "Cache-only patch missed the worker path" --summary "Tried a narrower change in src/cache.py only"
onmc brief --task "fix flaky Redis cache invalidation bug"
```

This creates local state under:

```text
.onmc/
├── compiled/
├── config.yaml
├── logs/
└── memory.db
```

## Command Examples

```bash
onmc --help
onmc init
onmc ingest
onmc task start --title "Fix flaky Redis cache invalidation bug" --description "Investigate cache invalidation flow"
onmc task list
onmc task show task-abc123def4
onmc attempt add task-abc123def4 --summary "Try a cache-only fix" --kind fix_attempt --status tried
onmc attempt list task-abc123def4
onmc attempt show attempt-abc123def4
onmc attempt update attempt-abc123def4 --status rejected --evidence-against "Did not address the failing path"
onmc task status task-abc123def4 --status blocked
onmc task end task-abc123def4 --status solved --summary "Fixed cache churn and updated tests"
onmc brief --task "fix flaky Redis cache invalidation bug"
onmc memory list
onmc memory add task-abc123def4 --type fix --title "Route worker refresh through the cache boundary" --summary "The shared cache boundary fixed the flaky path"
onmc memory list --type did_not_work
onmc memory list --kind hotspot
onmc memory show artifact-123abc
onmc memory show hotspot-123abc
onmc status
```

## Example Brief Output

See [examples/brief-example.md](examples/brief-example.md) for a representative artifact written by `onmc brief`.

## How It Works

### Ingest

P0 ingests:

- git commit history
- repository file tree metadata
- markdown docs such as `README*`, `docs/**/*.md`, `AGENTS.md`, `CLAUDE.md`, and architecture docs

Heuristics are deterministic and lightweight:

- docs are split into markdown sections and classified conservatively
- git history is used for hotspots, co-change patterns, and test-coupling hints
- repo shape is used to infer likely validation commands and source/test layout

### Brief Compilation

Given a task string, `onmc brief` ranks:

- relevant memory entries
- likely impacted files
- hotspot areas
- likely validation steps
- next files to inspect

The output is written to `.onmc/compiled/<timestamp>-brief.md`.

## Architecture Overview

High-level modules:

- `models/`: typed config, memory, ingest, and brief models
- `storage/`: local SQLite-backed state
- `task lifecycle`: durable task records stored alongside repo memory
- `attempt logging`: task-linked records of tried, rejected, partial, or successful approaches
- `memory artifacts`: durable task-derived findings that preserve fixes, failures, conflicts, gotchas, invariants, and validation guidance
- `ingest/`: doc parsing, git parsing, repo scanning, and heuristic extraction
- `brief/`: task-to-context compilation and ranking
- `core/`: repo discovery and service orchestration
- `rendering/`: Rich terminal presentation

More detail:

- [docs/architecture.md](docs/architecture.md)
- [docs/memory-model.md](docs/memory-model.md)
- [docs/task-lifecycle.md](docs/task-lifecycle.md)
- [docs/roadmap.md](docs/roadmap.md)

## Limitations

- P0 does not capture chat transcripts or editor state.
- Memory extraction is heuristic and intentionally conservative.
- Task lifecycle is local-only and intentionally lightweight.
- Attempt logging is structured but intentionally manual in P0.
- Task-derived memory artifacts are manually authored in P0 rather than auto-summarized.
- Brief ranking is token-based, not embedding-based.
- Git-derived patterns are suggestions, not guarantees.
- Optional LLM enhancement hooks are not implemented in P0.

## Roadmap

Short-term roadmap items live in [docs/roadmap.md](docs/roadmap.md). Near-term extensions include:

- manual memory authoring and curation
- incremental ingest and richer stale-memory handling
- optional LLM summarization behind a disabled-by-default interface
- deeper diff-aware briefing for active branches
- richer task-memory capture tied to briefs and outcomes
- linking briefs and outcomes back to recorded attempts
- artifact-assisted brief compilation that can surface prior failed approaches before a task starts

## Development

Install dev dependencies and run the full local check suite:

```bash
pip install -e ".[dev]"
ruff check .
mypy src
pytest
```

Optional pre-commit hooks:

```bash
pre-commit install
```

## Publishing

The repo includes:

- build metadata in `pyproject.toml`
- GitHub Actions CI
- a PyPI trusted-publishing workflow scaffold

Publishing still requires:

- a real GitHub repository
- PyPI project setup
- trusted publishing configured on the PyPI side for the GitHub `pypi` environment used by the release workflow

## Contributing

Contributions are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT. See [LICENSE](LICENSE).
