CLI Reference

The Topos CLI is for manual inspections and terminal workflows when you want structural quality verdicts without an editor integration. Most agent workflows use the MCP server instead — it currently covers more ground than the CLI (preference-ranked relaxation walks and structured agent guidance). The CLI is a fresh, from-scratch Rust implementation built directly on topos-engine, not a line-for-line port of the pre-v0.4.0 Python CLI — some Python-CLI features haven’t been ported yet; each command below says explicitly what’s missing.

Hint

evaluate automatically resolves GitNexus for COMPOSABLE scoring and supports JSON, priority, and preference inputs. MCP remains the richer agent surface: it returns the full preference walk, refactor targets, findings, and structured contracts.

Quick reference

topos install
topos status
topos evaluate . -r
topos config
topos inspect module.py
topos compare before.py after.py
topos coverage src/logic.py --tests tests/test_logic.py
topos depgraph generate
topos cache status
topos cache clean --pr 123 --dry-run
topos mcp

Run topos mcp as a smoke check, then stop it with Ctrl-C.

Classify files, drill into metrics, measure AST drift, score structural test overlap, and recap a pull request.

🏅 Quality commands

evaluate · inspect · compare · coverage · pr-recap

Agent registration, project settings, and the MCP server.

⚙️ Other commands

install · status · uninstall · update · config · depgraph · cache · mcp

Quality commands

evaluate

Evaluate code quality for one or more files or directories. This is the primary command for Code Quality Medals across the four pillars (see Measures).

topos evaluate [PATHS]... [OPTIONS]

Option

Description

-r, --recursive

Recursively evaluate directories.

--language [python|rust|javascript|typescript|cpp|go]

Optional discovery filter. Omit it and every supported language is discovered, each file parsed with its inferred language — the same multi-language default as MCP project evaluate. A named path that misses the filter, or does not exist, errors with the real cause.

-v, --verbose

Print every file’s full classification and raw metrics.

--json

Emit a machine-readable document without terminal progress. Each result carries its own language, and COMPOSABLE problems surface in a top-level warnings array.

--info

Select one of the five weakest files in a TTY and show its top three line-level refactor targets. When piped, inspect the weakest file without prompting. Combine with --failures to inspect only files failing that pillar. Cannot be combined with --json.

--failures [simple|composable|secure]

List every file whose policy gates fail the selected pillar, ordered by that pillar’s diagnostic score. Cannot be combined with --json.

--priority PILLAR|RANKING

Either a single pillar (simple, composable, secure, navigable) as the run’s primary guidance pillar, or a full comma-separated ranking of all four, most important first. This does not change fixed pass/fail gates.

--no-composable

Skip GitNexus and score SIMPLE/SECURE only.

--gitnexus-dir PATH

Use a non-default .gitnexus directory.

Example

topos evaluate . -r                          # every supported language
topos evaluate . -r --failures simple
topos evaluate . -r --info
topos evaluate . -r --failures simple --info
topos evaluate . -r --language rust          # narrow to one language

For a directory, terminal output is a cumulative pillar table with status, average and minimum diagnostic scores, failure counts, quality rails, and the directory lattice floor. When a pillar fails, a short hint points to --failures PILLAR for the exact files; --info adds a bounded Weak spots list ranked by each file’s average diagnostic score. Opening a row reveals the weakest pillar, ranked metrics, exact source spans, and recommended operations. Combining --failures PILLAR --info applies the same browser to the five lowest-scoring files that actually fail that pillar. A low score alone does not put a file in the list: failure status always comes from policy gates. Progress is drawn on stderr only while work is active. Press Enter to open a file, Escape to return to the selector, and Escape again (or q) to close it. Single-file runs use the same compact summary without redundant aggregate columns and point to topos inspect for the full file-level analysis. Use --verbose only when a script or debugging session needs the legacy inline raw-metric stream.

Representative directory output. The second line names the language when every discovered file agrees and N languages when they do not:

◇  Evaluated 20 files
│  3 languages · priority simple · COMPOSABLE enabled
│
│  PILLAR        STATUS    AVG    MIN   FAILURES   SCORE
│  SIMPLE        X FAIL    51%     0%     3 / 20    ━━━━━━━◆───────
│  COMPOSABLE    X FAIL    60%     0%     8 / 20    ━━━━━━━━◆──────
│  SECURE        ✓ PASS   100%   100%     0 / 20    ━━━━━━━━━━━━━━◆
│
│  Status reflects policy gates; scores are diagnostic — use them to guide refactoring.
└  ✓ 🥈 SILVER · SIMPLE_SECURE · 70% average.

Tip: add --failures simple to list its 3 failing files; --info shows overall weak spots.

When COMPOSABLE cannot be scored, the reason appears on the finished card rather than as mid-run noise, and recoverable cases point at the fix:

◇  Evaluated 20 files
│  3 languages · priority simple · COMPOSABLE not measured
│  ↻ GitNexus generation failed (Not inside a git repository.) — COMPOSABLE not scored

Note

Pillar status comes from the raw policy gates. Normalized quality scores are diagnostic and therefore can be below the visual midpoint even when a pillar passes. --failures filters on those gates rather than scores. --info exposes the same ranked refactor-target evidence used by MCP without expanding every project row or rerunning the project.

inspect

Inspect one file without losing the project context. Human output starts with the same pillar summary as evaluate, then shows ranked recommendations, function complexity with line spans, and every raw metric. Policy metrics keep their interpretations; supporting diagnostics remain available in a quieter section.

topos inspect PATH [OPTIONS]

Option

Description

--json

Output the inspection as a single JSON object (a subset of the pre-v0.4.0 Python CLI’s --json fields — no suggestions/ security_findings/suppression rendering yet). Mainly intended for machine comparison, not primary human reading.

--no-composable

Skip GitNexus and inspect SIMPLE/SECURE only.

--gitnexus-dir PATH

Use a non-default .gitnexus directory.

Example

topos inspect src/main.py
topos inspect src/main.py --json

The nearest .topos.toml supplies the inspection priority and preferences, so file-level guidance stays aligned with the project. JSON field names and values are unchanged by the human-output redesign.

compare

Compare structural (AST) distance between two programs — topological drift via UAST edit distance, not line-level diff.

topos compare SOURCE TARGET [OPTIONS]

Option

Description

-v, --verbose

Show insertions, deletions, and substitutions.

Example

topos compare old_version.py new_version.py -v

coverage

Measure how much of the program-under-test (PUT) structure is represented in test code.

Declaration-level bipartite matching and k-gram path recall. No test execution required. See Measures for the underlying algorithm.

topos coverage SOURCE_PATHS... --tests TEST_PATH [OPTIONS]

Option

Description

--tests PATH (required, repeatable)

Test file or directory; repeat for multiple test paths.

-r, --recursive

Recursively discover files when source or test paths are directories.

--language [python|rust|javascript|typescript|cpp|go]

Language for parsing. Inferred when all discovered files use one language; required for mixed-language inputs.

--k INTEGER

DFS kind n-gram length for path recall (default: 3).

--coverage-threshold FLOAT

Minimum best-match recall to count a PUT declaration as covered (default: 0.5).

--include-unknown

Include Unknown UAST kinds in histograms and k-grams.

Example

topos coverage src/logic.py --tests tests/test_logic.py --k 3

Directories use the same ignored-path discovery rules as evaluate:

topos coverage src/ --tests tests/ -r --language python

The headline reports mean declaration coverage. The following line reports the percentage of individual source declarations meeting the configured threshold. Topos rejects inputs with no measurable source or test declarations instead of treating an empty corpus as covered.

Note

--json is not yet ported to this CLI — plain-text output only. The same computation is exposed with structured JSON via the topos_calculate_coverage MCP tool.

pr-recap

Structural before/after for a git range or a pull request, judged by the project’s PR gates: READY, NEEDS ATTENTION, or BLOCKED, and the one finding that decided it. Deterministic and reproducible from --json (and exposed to MCP agents via topos_pr_recap); there is no LLM in the loop.

topos pr-recap
topos pr-recap 5
topos pr-recap --base main --head HEAD
topos pr-recap 5 --head :worktree
topos pr-recap 5 --verbose
topos pr-recap 5 --info
topos pr-recap 5 --strict
topos pr-recap 5 --preset relaxed
topos pr-recap 5 --json
topos pr-recap 5 --format github
topos pr-recap 5 --no-coupling
topos pr-recap 5 --priority composable

Option

Description

PR

Review this pull request against the branch it merges into. Mutually exclusive with --base/--head.

--base COMMIT

Git commit the change starts from.

--head COMMIT

Git commit the change ends at. Defaults to HEAD. Use --head :worktree to include uncommitted edits and untracked files.

--repo PATH

Repository to read. Defaults to the current directory.

--json

Emit topos.pr_recap.v3 instead of the review card: the readiness, the exit code, every finding with its gate and severity, and the gate settings that produced them.

--max-files N

Do not score more than this many added or modified files (default 0, which scores everything). The most-changed files (lines added plus removed) are kept; the recap is then marked incomplete and the rest are listed as skipped. What that costs the verdict is the incomplete gate’s call (info by default). Past 100 files to score, the command warns on stderr.

--verbose

Add the Changed files table, every split child, and the per-function move ledger inside the card.

--info

Append the recommended change for each blocking or warning finding after the card, in inspect’s grammar.

--strict

Fail the check on NEEDS ATTENTION too (fail_on = "warn").

--advisory

Never fail the check (fail_on = "never"); exit 0 even when BLOCKED.

--fail-on [block|warn|never]

Which findings fail the check (exit 1). Mutually exclusive with --strict and --advisory.

--preset PRESET

Gate with a built-in preset (relaxed, recommended, strict) for this run, ignoring the project’s [pr_recap], its waivers included.

--format [card|github|markdown]

Which card to print. card is the default, on a terminal and in a pipe alike; piped output drops the color. github renders the Markdown sticky-comment format; markdown renders the same Markdown without the hidden sticky marker, for embedding in another comment.

--no-marker

Omit the hidden sticky marker from --format github output.

--no-coupling

Skip coupling-store preparation; COMPOSABLE is reported as not measured.

--priority VALUE

Pillar to prioritize when classifying, as for evaluate. Defaults to the priority in .topos.toml, or secure when none is configured. The card’s meta line names the priority used.

The separate compact layout is retired: the default card already fits a CI log. --compact and --format compact remain as hidden aliases for the default card so existing scripts keep working.

Range

  • The before side is the merge-base of the base and the head, like git diff base...head: commits that landed on the base branch after the fork are not charged to the change.

  • With no arguments, pr-recap reviews the uncommitted edits in the working tree (--base HEAD --head :worktree), including untracked files.

Gates

Each gate in [pr_recap] (set with topos config, see config) turns what happened into a finding with a severity: off, info, warn or block. Under the recommended preset, a lost pillar, a new file that fails SECURE or is SLOP, and a split that gained SECURE findings block; a score drop past [pr_recap.score_drop] (10 points, in a file with at least 20 changed lines), a score that moved while the structure did not, and a function that grew as a split moved it need attention; a pillar that already failed and got worse, a new file failing another pillar, a bloated split, and skipped files are info. topos config show lists every gate and its severity.

Moving code is not charged as a regression. When a file loses a pillar only because code moved into it from another file in the same range (the function arrived unchanged, the file received moved code and little new logic, or the dependency graph traced the move), the finding is reported under the moved_pillar gate instead of pillar_lost, naming the file the code came from; moved_pillar is info under the relaxed and recommended presets and warn under strict. A score drop the same move explains is info. A moved function that grew on the way is still pillar_lost, and a SECURE loss is never excused when the range as a whole gained SECURE findings.

Three gates read the file dependency graphs at base and head, so they run only when COMPOSABLE was measured (not with --no-coupling), and they see every changed source file, not only the --max-files that were scored:

  • import_cycle: an import cycle at head that did not exist at base. The finding walks the cycle from an import this change added and suggests breaking it there. Its severity comes from [pr_recap.import_cycle], one row per language (rust, typescript, javascript, python); a cycle takes the strictest row among its files, and a file in another language falls back to the import_cycle gate. Under the recommended preset a Python cycle needs attention and the others are info.

  • fan_in_growth: a changed file that fails SIMPLE and gained dependents. It fires when the new dependents (tests and a split’s own children aside) clear both [pr_recap.fan_in_growth] thresholds, min_new_dependents (2) and min_growth_percent (25). Warn under recommended and strict.

  • blast_radius: how many files outside the change depend on it directly and transitively, named through the changed file with the widest reach. Info under recommended and strict, off under relaxed.

In --json these findings carry a related list: the cycle’s files, the new dependents, or the most depended-on files the change reaches.

Waivers

A known finding can be set aside with a [[pr_recap.waive]] entry:

[[pr_recap.waive]]
gate = "pillar_lost"
path = "src/legacy/**"
reason = "vendored parser, replaced in #412"
expires = "2026-12-31"

gate is a gate key, path a glob over the finding’s file, and reason is required; expires is optional and the waiver applies through that date (UTC). A waived finding keeps its severity and stays in the document, marked waived in --json, but no longer counts toward the readiness or the exit code. The card counts waived sites and unused or expired waivers on a dim line (1 waived · 1 unused waiver); --verbose lists each waived site with its reason, and the GitHub comment adds a Waived section. A site is one place, gate and waiver: a function that lost two pillars under one waiver is one line naming both (pillar_lost SIMPLE, NAVIGABLE), while --json keeps one finding per pillar. An entry missing a field, naming an unknown gate or carrying a malformed date is dropped with a warning. Waivers are not gate settings: they do not make the preset custom, and topos config set --pr-preset keeps them.

The policy comes from the flags, else the nearest .topos.toml, else the recommended preset. Every card ends with a dim gate line that names it, so a reader knows which rules produced the verdict: gate: recommended, gate: strict, or gate: custom · 2 changes · ./.topos.toml. When the change needs attention under a policy that fails only on blocks, the line adds · warnings don't fail the check.

Sample card

◇  Reviewed #359  fix/ts-parser-cpg-precision → main
│  3 files · +174/-1 · priority navigable · COMPOSABLE not measured (--no-coupling)
│
│  X BLOCKED   dispatch.rs lost SIMPLE and NAVIGABLE (GOLD → BRONZE)
│
│  PILLAR        STATUS   BEFORE   AFTER   FAILING   SCORE
│  SIMPLE        X FAIL      62%     42%     1 / 3   ━━━━◆───── ↓
│  SECURE        ✓ PASS     100%    100%     0 / 3   ━━━━━━━━━◆
│  NAVIGABLE     X FAIL      98%     67%     1 / 3   ━━━━━━◆─── ↓
│
│  1. X topos/engine/src/graphs/ast/dispatch.rs · sanitize_typescript_type_imports:62
│       SIMPLE 32 > 10 · NAVIGABLE 21.4 > 10 · lift the deepest nested block into a named function
│       1 smaller dip
│
│  gate: recommended
└  X 🥇 GOLD → 🥉 BRONZE · SECURE · 87% → 70% average.

Tip: add --verbose for every file, or run topos inspect topos/engine/src/graphs/ast/dispatch.rs.

--verbose adds the Changed files table between the findings and the gate line:

│  CHANGED FILES  topos/engine/src/graphs/
│  FILE                        MEDAL            CHANGE
│  X ast/dispatch.rs           GOLD → BRONZE    X SIMPLE lost · X NAVIGABLE lost
│    uast/mapper_javascript.rs GOLD             ↓ SIMPLE 69 → 64
│  1 file kept its medal

How to read it

  • The verdict line states the single most important finding. X marks a block, ! a warning; info findings carry no mark and are only counted.

  • The project table is evaluate’s, over the existing files the change touched: whether each pillar passes at head, the mean score before and after, and how many files fail it. Added files are rolled up on their own, so they cannot lift or sink the average.

  • The numbered list shows the blocking findings, then the warnings, most important first, at most max_hotspots of them (3 by default). Findings at the same function merge into one item. A dim line counts the rest: N more, smaller dips, and notes. Score dips under one point are hidden.

  • In Changed files, the mark is the file’s worst finding, MEDAL shows BEFORE → AFTER when the tier moved, and CHANGE says what happened pillar by pillar: X SIMPLE lost, ✓ NAVIGABLE gained, ↓ SIMPLE 69 → 64 (a score move of at least a point that crossed no gate), new, and cosmetic (scores moved while the syntax tree barely changed). Losing a pillar is a loss even when another was gained: X SIMPLE lost · ✓ NAVIGABLE gained is a trade and still blocks.

  • The splits table shows a parent file whose code moved into new children; --verbose lists every child and the per-function move ledger. It passes (✓) when the split stayed lean, warns (!) when decisions grew more than 10% or a child landed SLOP, and fails (X) when a moved function came out more complex or the split carries more SECURE findings than the parent had. What each costs the verdict is the split_* gates’ call.

  • The footer carries the readiness mark and the project medal, so the last line summarizes the run on its own.

GitHub comment

--format github renders the same document as Markdown for a sticky pull request comment, headed ### X Blocked · Topos structural review of #359. It lists Blocking and Needs attention items, collapses info findings in <details>, shows the changed files with the same MEDAL and CHANGE columns, and puts the gate line in the footer. A hidden marker on the first line lets a later run edit the comment instead of adding another; pass --format markdown or --format github --no-marker to omit the marker when embedding the section inside another comment.

Exit codes

  • 0 — READY, NEEDS ATTENTION under fail_on = "block" (the recommended and relaxed presets), or any verdict under fail_on = "never" (--advisory or --fail-on never).

  • 1 — BLOCKED (unless fail_on = "never"), or NEEDS ATTENTION under fail_on = "warn" (--strict, --fail-on warn, or the strict preset).

  • 2 — pr-recap could not produce a verdict (bad range, repository not found, gh failure, etc.).

The direction field in --json (IMPROVEMENT, SCORE DOWN, LATERAL, …) says which way the structure moved and never changes the exit code.

In --json, project.decisions_before and project.decisions_after sum cfg.cyclomatic across the scored existing files at base and head; added.decisions sums it across scored added files at head. Each total is null if any file in that population lacks a measurement on that side (for example, because it did not parse), rather than reporting a partial sum as a complete total. Files excluded by --max-files are listed as skipped and the recap is marked incomplete.

Note

Structural direction is not proof that tests or behavior still pass. pr-recap is a deterministic structural debt ledger and pre-review coaching aid, not a semantic correctness check or a binary AI-slop classifier. Its 16 gates and three presets (relaxed, recommended, strict) are calibrated on 1,609 pull requests across 10 open-source repositories so recommended stays within a \(\le 5\%\) warning/block false-positive rate on merged first-time contributors; see the PR Recap calibration report and full lab notes.

Other commands

install / uninstall / status

Register the Topos MCP server in your agent harnesses, and take it back out. One entry per harness, with an absolute command path; no skill files, no instruction blocks. See For Agents for the harness table and state model.

topos install [HARNESSES]... [OPTIONS]
topos uninstall [HARNESSES]... [OPTIONS]
topos status [--json]

Harness ids: claude, claude-desktop, codex, gemini, copilot, cursor, vscode, antigravity, pi, opencode.

Flag

Behavior

--all

Target every supported harness. Required in a non-interactive shell when no ids are given (install errors without it).

--dry-run

Print the plan and write nothing.

-y, --yes

uninstall only — skip the confirmation prompt.

--purge-backups

uninstall only — also delete the .topos.backup files earlier installs left behind.

--json

status only — machine-readable output for agents.

With no ids in a terminal, both commands open a multi-select checklist. topos uninstall always previews what it will remove and asks first; topos install status is an alias for topos status.

Uninstall removes harness installation state only. It keeps the shared cache inventory under state_dir()/cache-index and reports it as retained, and it never enters a repository’s Git common directory, so cache leases, locks, and worktree registrations stay with that repository. Use topos cache clean or topos cache prune when generated data should be removed.

Example

topos install --all --dry-run   # see what would change
topos install claude codex      # just those two
topos status --json             # for scripts and agents

update

Check for a newer release and offer to install it. Topos works out which distribution channel each topos binary came from, shows the exact command that upgrades it, and runs that command once you confirm.

topos update
topos update --check
topos update --json

Flag

Behavior

--check

Report what is installed and published without being offered anything.

-y, --yes

Apply without prompting. Applies every supported outdated install without prompting. Binary installs use verified downloads; Homebrew uses its upgrade command.

--json

Machine-readable survey: current and latest version, platform, and every install with its path, version, channel and upgrade command.

Nothing is applied without a confirmation, and a non-interactive run without –yes reports and exits without changing anything — an agent or CI job has nobody to answer the prompt. See Installation for the channel table and the upgrade paths.

Example

topos update --check      # what would change
topos update              # offer it
topos update --json       # for scripts and agents

config

View or update project settings in the nearest .topos.toml: the evaluation priority and the PR gate preset topos pr-recap checks against. Running bare topos config opens a two-step wizard on a TTY (priority, then PR gate) that writes once at the end, and falls back to show when input is non-interactive.

topos config
topos config show
topos config set --priority secure
topos config set --priority composable,secure,simple
topos config set --pr-preset strict

--pr-preset takes relaxed, recommended (the default), strict, or custom. A named preset is stored alone under [pr_recap], so the project picks up improved defaults; custom writes every gate setting, with its default and meaning in a comment, for you to edit in the file. config show lists every PR gate setting and marks the ones that differ from the preset, then any [[pr_recap.waive]] entries. Besides [pr_recap.gates], a custom policy can tune [pr_recap.score_drop], [pr_recap.import_cycle] (a severity per language; an unknown language is ignored with a warning) and [pr_recap.fan_in_growth].

--priority accepts either form: a single pillar sets the emphasis and reorders the existing ranking around it; a full comma-separated ranking replaces it outright. Explicit evaluate flags override project settings. A full ranking is the stronger statement of intent, so its first pillar becomes the effective priority.

On disk, [evaluation].priority is a single key: a pillar string (priority = "secure") or a full ranking array (priority = ["composable", "secure", "simple"]). config set always writes the array form. A legacy preferences array is still read when present, then dropped on the next write.

depgraph

Build or refresh the GitNexus store used by COMPOSABLE scoring. Generation no-ops when the existing graph is current unless --force is supplied.

topos depgraph generate [PATH] [OPTIONS]

Option

Description

PATH

Project directory to analyze (default: current directory).

--force

Regenerate even when the graph is current.

--json

Output the generation result as a single JSON object.

Requires GitNexus on PATH. evaluate and inspect normally manage the same store automatically; this command is useful for explicit refreshes after dependency changes. If a graph reported as current appears stale, rerun with --force. When evaluate cannot measure COMPOSABLE, its terminal summary points back to this command.

cache

Inspect the cross-repository inventory of generated data, discover existing PR stores and graph directories under explicit paths, and clean up managed PR stores. Status is read-only; discovery registers what it finds unless --dry-run is passed. Neither adopts a legacy store or authorizes deletion, and every cleanup target is revalidated on disk before anything is removed.

topos cache status [--global] [--sizes] [--json]
topos cache discover PATH... [--dry-run] [--json]
topos cache clean (--pr N | --all-prs) [--global] [--dry-run] [--json] [--yes]
topos cache prune --older-than DURATION [--global] [--dry-run] [--json] [--yes]

Option

Behavior

--global

Include every known location, not only the current repository. For clean and prune, also consider stores recorded in the shared inventory. This is a known-location view, not an exhaustive crawl.

--sizes (status)

Recursively estimate bytes in managed directories. Hardlinks, copy-on-write storage, and Git’s shared object database mean these are estimates, not guaranteed reclaimable disk space.

--pr N / --all-prs (clean)

Required, mutually exclusive. Clean one pull request’s managed store, or every managed PR store in scope.

--older-than DURATION (prune)

Required. Remove managed stores older than this threshold, for example 24h, 7d, or 4w. Shorter values are raised to the 24-hour minimum grace.

--dry-run (discover)

Report what would be registered without writing inventory. Discovery never creates ownership markers.

--dry-run (clean / prune)

Report what would be removed without changing anything.

--yes

Skip the confirmation prompt. --json cannot prompt, so an applying run needs --yes; otherwise preview with --dry-run.

--json

Emit the stable topos.cache.v1 document.

PR stores live beside a repository’s shared Git directory as topos-pr-<N>/{base,head}. Linked worktrees share those PR stores but can have separate per-worktree .gitnexus graphs; those graphs are reported as distinct locations. Status labels a marker-free store legacy-ambiguous and does not adopt it. clean may adopt such a store only after full validation of its layout, commit record, worktree registrations, and contents, and never as part of a read-only command; prune never adopts one.

clean is targeted, lease-protected, and idempotent. It refuses a store that a concurrent worker holds and reports it as busy, revalidates ownership markers, worktree registrations, and contents, and leaves a partial failure retryable: rerun the same command after resolving the reported condition. prune is explicit age-based cleanup with a 24-hour minimum grace; no command runs cleanup in the background, and there is no garbage-collection daemon. Neither command deletes agent snapshots, GitNexus snapshots or registry entries, or an ordinary project .gitnexus graph; those belong to their owners, and GitNexus invalidates its own graphs. Only managed PR stores are in scope. Graph generation, evaluation, and inspection that target a managed PR side hold the same per-PR lease, so cleanup reports the store as busy rather than removing it mid-run. Tracked content under .gitnexus/, or a regular file or symlink named .gitnexus, is treated as user content and blocks cleanup; only generated untracked graph data is disposable.

The inventory lives under state_dir()/cache-index and can be redirected with TOPOS_CACHE_INDEX_DIR. That override affects bookkeeping only; the operational leases and worktree registrations stay with the repository. topos uninstall preserves the inventory, and every other repository-scoped lease or lock, because neither is harness installation state.

mcp

Start the Topos Model Context Protocol server on stdio. AI coding agents connect to this instead of shelling out to evaluate.

topos mcp

Tip

Verify the binary before wiring it into an editor (see For Agents):

topos mcp

The command waits on standard input. Press Ctrl-C to exit.

Next steps

  • Installation — install the binary or build from source

  • For Agents — wire Topos into Claude Code, Cursor, Gemini CLI, and other MCP clients

  • Measures — what each pillar measures and how thresholds map to medals

  • Concepts — lattice and characteristic-morphism background