research-git: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

research-git (rgit) is a memory system for agentic coding experiments: it captures code ideas as "Feature Capsules" in a graph beside the repo (.rgit/), and later regenerates a chosen idea onto today's codebase. Published to PyPI as research-git, console entry point rgit (rgit.cli:main, also python -m rgit).

Commands

uv pip install -e ".[dev]"          # install for development (pip is blocked in this sandbox; use uv)
python -m pytest -q                 # run all tests (local: .venv/bin/python -m pytest -q)
python -m pytest tests/test_recall.py -q          # one file
python -m pytest tests/test_cli.py -k capture -q  # one test by keyword

pytest is configured in pyproject.toml with pythonpath = ["src"], so tests run from the repo root without installing. There is no linter or formatter configured.

CI (.github/workflows/ci.yml) runs the suite on ubuntu/windows/macos with Python 3.11 via uv pip install --system -e ".[dev]". uv.lock is gitignored — CI uses uv pip, not uv sync. Keep code 3.11-compatible and Windows-safe even though the local venv may be newer.

Architecture

The core design split is two planes:

• Engine (deterministic, free) — all Python in src/rgit/: the graph store, content-addressed snapshots, diff→symbol mapping, ranking, composing briefs. Never calls an LLM API.
• Intelligence (delegated) — a Claude Code plugin shipped inside the wheel at src/rgit/_plugin/: three subagents (capsule-segmenter, capsule-regenerator, edge-judge) and two skills (rgit-capture, rgit-recall). The host agent dispatches these on the user's existing subscription. .claude-plugin/marketplace.json points at src/rgit/_plugin; the plugin files are wheel package-data, so installer changes must keep pyproject.toml's package-data globs in sync.

Anywhere the engine needs intelligence it exposes an interface instead: e.g. segmenter.py defines a Segmenter Protocol, tests inject MockSegmenter, and the real segmentation happens when the plugin's subagent fills that role. Tests never dispatch real agents.