Skip to content

Home

Jump to bottom
sunjiajunsunjiajun edited this page Jul 25, 2026 · 3 revisions

research-git Command-Line Guide

This page documents the complete research-git command-line interface. It is based on the current CLI parser and runtime behavior.

research-git stores four main kinds of data:

  • Capsule: an approved experiment or feature decision, including its intent, relevant code, knobs, assumptions, and regeneration guidance.
  • Proposal: one or more Capsule candidates waiting for review.
  • Run: one command execution, including the exact code snapshot, base commit, exit status, and metrics.
  • Edge: a relationship between Capsules, Runs, or touched modules.

Most commands require an initialized .rgit/ store in the current Git repository:

rgit init

Command index

Area Commands
Setup and maintenance init, install, update, install-hooks, doctor
Capture and review capture, watch, pending, review, resegment, features
Experiments and analysis run, compare, ablation, provenance, metric-dir
History digestion digest scan, digest status, digest next, digest accept, digest skip, digest clear
Graph and sharing edges, graph, mcp

Use rgit --help, rgit <command> --help, or rgit <command> <subcommand> --help for generated command help. -h and --help are equivalent.

Notation

  • [VALUE] means the value is optional.
  • A | B means choose one of the alternatives.
  • VALUE... means one or more values.
  • A..B is a Git revision range.
  • REV is a Git revision such as HEAD, a commit ID, branch, or tag.
  • Everything after -- in rgit run is the experiment command.

Setup and maintenance

rgit init

Initialize .rgit/ at the Git repository root. This creates the local database and content-addressed object store. It does not install Git hooks.

rgit init
Form What it does
rgit init Initialize the store and, on an interactive terminal, offer to digest existing history.
rgit init --no-digest Initialize without offering history digestion.
rgit init --digest [MODE] Initialize and immediately create a history-digestion plan. The default mode is layered.
rgit init --digest [MODE] --range A..B Digest an explicit revision range.
rgit init --digest [MODE] --all Digest the whole visible mainline history.

--range and --all require --digest. --no-digest conflicts with --digest.

rgit install

Install research-git skills and managed guidance for an agent client. Claude Code also receives MCP configuration automatically; other clients print the MCP configuration to add manually.

rgit install
rgit install codex
rgit install claude-code
Form or option What it does
rgit install [PLATFORM] Install for one platform, or auto-detect installed clients when PLATFORM is omitted.
rgit install --list List supported platforms.
rgit install PLATFORM --uninstall Remove the integration for a platform.
--guidance default|manual-only|none Select the managed agent-guidance mode non-interactively.
--scope user|project|local Select the Claude Code installation scope. Other clients currently use their standard user-level skill location. Default: user.
--dry-run Preview installation changes without writing them.
--json Emit a machine-readable installation result.
--from-update Internal flag used by rgit update to refresh detected clients without interactive prompts. Customized or removed managed guidance is preserved.

The last five options are advanced automation surfaces and are hidden from the default help output. Restart the agent client after installation.

rgit update

Upgrade research-git using the tool that installed it, then refresh every detected supported agent client.

Form What it does
rgit update Upgrade the package and refresh detected supported clients.
rgit update --off Disable release notices permanently.
rgit update --on Re-enable release notices.

rgit install-hooks

Install the optional Git post-commit capture hook. It stages the committed diff as a Proposal but never approves a Capsule.

Form What it does
rgit install-hooks Install the hook without replacing an existing hook.
rgit install-hooks --dry-run Preview the hook operation.
rgit install-hooks --uninstall Remove the research-git hook.

rgit doctor

Check the store, database, objects, Run artifacts, and graph consistency.

rgit doctor
rgit doctor --json

The command returns a non-zero exit status when the report contains errors.

Capture and review

rgit capture

Capture a worktree diff, one commit, or a revision range as a Proposal.

Form What it does
rgit capture Capture the worktree when it has changes; otherwise capture the latest commit.
rgit capture REV Capture one commit or Git revision, such as HEAD or a commit ID.
rgit capture A..B Capture a Git revision range.
rgit capture --init Initialize a missing store before capturing; never installs hooks.
rgit capture --trigger TYPE Record the trigger label on the Proposal. Default: manual.

The following legacy source forms remain supported for deployed hooks and older guidance, but the positional form above is preferred:

rgit capture --commit [REF]
rgit capture --range A..B
rgit capture --worktree

A Proposal can contain multiple Capsule candidates. Candidates are not approved Capsules until the review step.

rgit watch

Watch the worktree and stage intermediate changes as Proposals after an idle period.

rgit watch
rgit watch --interval 5 --idle 5
rgit watch --once
Option What it does
--interval SEC Set the requested polling interval. Default: 5.0.
--idle SEC Set the requested idle delay. Default: 5.0.
--once Take one snapshot/tick instead of running the loop.

The loop waits max(interval, idle) between snapshots and stages a Proposal after it observes an unchanged snapshot.

rgit pending

List open, non-backfill Proposals.

rgit pending
rgit pending --json

The JSON form includes the Proposal ID, trigger, source commit, full diff, and Capsule candidates. It is the main input to the rgit-capture skill.

rgit review

List or resolve live Proposals.

Form What it does
rgit review List open, non-backfill Proposals and their candidates.
rgit review --approve [PROPOSAL_ID] Approve one candidate. When the ID is omitted, use the sole open Proposal.
--index N With --approve, select a candidate by zero-based index. Default: 0.
--name NAME With --approve, select an existing candidate by its exact name.
rgit review --decide [PROPOSAL_ID] --keep NAME[,NAME...] Approve the named Capsule candidates and discard every other candidate in the Proposal. --keep may be repeated.
rgit review --dismiss [PROPOSAL_ID] Dismiss the entire Proposal without creating Capsules.

--approve, --decide, and --dismiss are mutually exclusive. Approving a candidate materializes an approved Capsule and creates any applicable touches, produced, and variant_of edges.

rgit resegment

Replace a Proposal's candidates with validated JSON, normally produced by the Capsule segmenter.

rgit resegment prop_ab12 --from-json candidates.json
echo '<capsules-json-array>' | rgit resegment prop_ab12 --from-json -

--from-json - reads UTF-8 JSON from standard input.

rgit features

List approved Capsules:

rgit features

The output includes each Capsule ID, name, intent, and a [backfill] marker where applicable.

Run experiments

How rgit run works

rgit run is an experiment runner and recorder. It does not recall or regenerate a Capsule by itself.

rgit run -- python eval.py

It:

  1. records the current base commit;
  2. executes the command after --;
  3. freezes the repository's tracked and non-ignored untracked files after the command finishes, excluding .git/, .rgit/, and symlinks that resolve outside the repository;
  4. parses metrics;
  5. records a Run with the command, snapshot, metrics, exit status, and explicit environment overlay;
  6. captures the current worktree diff as a Proposal when a diff exists.

Standard output and standard error are not persisted. Standard output is used for metric parsing. Successful command output is not replayed by the CLI; failed commands show short output excerpts.

Metrics can be supplied in either form. Create rgit_metrics.json containing:

{
  "accuracy": 0.92,
  "latency": 37.4
}

or as numeric output:

accuracy=0.92
latency: 37.4
RGIT_METRIC loss=0.31

rgit_metrics.json takes precedence over stdout parsing.

rgit run forms

Form What it does
rgit run -- COMMAND... Run and record an experiment.
rgit run --init -- COMMAND... Initialize a missing store, then run the experiment.
rgit run --from CAPSULE_ID -- COMMAND... Declare that the current implementation was regenerated from a source Capsule. Repeatable. This does not execute recall and currently does not validate the source ID.
rgit run --with CAPSULE[,CAPSULE...] -- COMMAND... Declare approved Capsules active in this Run. Repeatable and/or comma-separated. Names and IDs are resolved and validated.
rgit run --from ID --refresh-guide-file PATH -- COMMAND... After the Run, replace the source Capsule's resurrection_guide with the file contents.

Example after an agent has already regenerated a Capsule onto today's code:

rgit run --from feat_ab12 -- python eval.py

--from is a lineage declaration. If this Run creates a new Proposal and a candidate is approved, the resulting Capsule receives:

new Capsule --variant_of--> source Capsule
new Capsule --produced--> Run

No variant_of edge is created when there is no worktree diff. If an identical open Proposal is reused, the new Run and --from lineage are not added to that existing Proposal.

--with instead records:

Run --active--> approved Capsule

This supports combination-based ablation analysis. Run metrics belong to the whole frozen code snapshot; they do not automatically prove the contribution of each individual Capsule.

rgit compare

Rank Capsules in a variant cluster, or Capsules touching a target symbol, by a single metric.

rgit compare rerank
rgit compare rerank --metric accuracy --higher
rgit compare rerank --metric latency --lower
Option What it does
--metric NAME Select the metric. Otherwise use the most common metric in the cluster's Runs.
--higher Treat larger values as better for this invocation.
--lower Treat smaller values as better for this invocation.

The output shows the selected value and delta from the earliest measured baseline. It also identifies a winner when a direction is supplied with --higher or --lower, or stored with rgit metric-dir. Each Capsule is represented by its best Run for the selected metric and direction.

rgit ablation

Compare exact Capsule subsets recorded on Runs. The command uses active edges created by rgit run --with; when a Run has none, it falls back to Capsules connected through produced edges.

rgit ablation capsule_a capsule_b
rgit ablation capsule_a capsule_b --metric accuracy

Runs containing an active Capsule outside the requested sweep are excluded.

rgit provenance

Compare a Run's frozen implementation with the clean code slices stored in its produced or active Capsules.

rgit provenance run_ab12

The output shows per-feature, per-symbol clean versus Agent-adapted diffs.

rgit metric-dir

Manage metric winner directions.

Form What it does
rgit metric-dir set METRIC higher|lower Persist the winner direction for a metric.
rgit metric-dir list List configured directions.
rgit metric-dir suggest Suggest directions from metric names found in stored Runs. It does not apply them.

Digest Git history

History digestion backfills an existing repository into origin=backfill Capsules. rgit digest scan creates a resumable plan, while the rgit-digest skill processes it in batches.

rgit digest scan

rgit digest scan
rgit digest scan main..HEAD
rgit digest scan --mode layered --window 200
rgit digest scan --all
rgit digest scan --json
Argument or option What it does
[A..B] Scan an explicit history range. Omit it for the recent-window default.
--mode MODE Select a digestion mode.
--window N Limit the default mainline scan to a recent window.
--all Scan the whole visible mainline and ignore window limiting.
--json Emit the plan as JSON.

Other digest commands

Command What it does
rgit digest status [--json] Show mode, unit statuses, pending work, dead-history count, and estimated remaining batches.
rgit digest next [--batch N] [--json] Stage the next batch as backfill Proposals. Default batch size: 10.
rgit digest accept PROPOSAL_ID Non-interactively materialize validated candidates as backfill Capsules, or skip a unit with no genuine feature.
rgit digest skip UNIT_ID Mark one unit skipped.
rgit digest clear Delete all backfill Capsules, reset done and staged units to pending, and dismiss open Proposals belonging to staged units. Live Capsules and deliberately skipped units remain.

Graph and analysis

rgit edges

Infer or write Capsule relationships.

Form What it does
rgit edges --apply Deterministically write code-overlap edges and output overlap pairs plus potential dependency candidates for the edge judge.
rgit edges --candidates Output potential dependency candidates without applying them.
rgit edges --add TYPE SRC DST Directly add one edge. The caller is responsible for type and direction correctness.
--scope ID[,ID...] Restrict apply/candidate work to pairs touching the named or identified Capsules. Repeatable.
--limit N Cap dependency candidates at the N strongest.

--apply, --candidates, and --add are not parser-level mutually exclusive; dispatch gives --add precedence, then --apply, then --candidates.

rgit graph

Render the Capsule graph:

rgit graph
rgit graph --dot
rgit graph --text
rgit graph --runs
Option What it does
--mermaid Emit Mermaid. This is the default.
--dot Emit Graphviz DOT.
--text Emit a plain-text variant-cluster tree.
--runs Include Run nodes and produced / active edges.

--mermaid, --dot, and --text are mutually exclusive.

rgit mcp

Start the read-only MCP query and sharing surface:

rgit mcp

The server resolves the current repository lazily for each tool call. It can start without opening a local store and does not create or approve Capsules.

Update checks

Except for mcp and update, interactive non-JSON commands may start a throttled background check for a newer PyPI release. Once an update is known, the CLI prints a one-line notice after qualifying commands until the package is updated or notices are disabled.

Disable this per environment with:

RGIT_UPDATE_CHECK=0

Or disable it persistently with:

rgit update --off

This Wiki describes the current implementation. For any command, use rgit <command> --help to confirm the syntax supported by your installed research-git version.

Clone this wiki locally