GitTriage
Workspace truth and preflight safety for coding agents.
GitTriage builds a deterministic picture of your local git workspace: which checkout is canonical, which paths are unsafe for automation, and how duplicates and nested repos relate — without touching your working trees. Optional gh ingest augments local remotes; clustering and scores stay rule-based.
Before: agents and humans edit the wrong clone, or guess which folder is “the” repo.
After: preflight, resolve, check-path, and verdict give stable JSON (and a read-only HTTP API) you can hand to tooling before any read or write. Verdicts include machine-readable reason codes and remediation hints so agents can branch without scraping text.
Who it's for: anyone running coding agents or scripts over messy local trees who needs which repo is real, when automation must stop, and what a human should review first.
Optional:
explain --aiandai-summaryadd narrative on top of deterministic output — they are not required for the core workflow.Not for: hosted PR review bots, code search platforms, or compliance-first catalog products.
cargo build --release -p gittriage # → target/release/gittriage
cp gittriage.toml.example gittriage.toml # edit db_path / default_roots / github_owner
gittriage scan ~/Projects --github-owner your-login
gittriage scan ~/Projects --fail-on-ingest-error --fail-on-enrich-error # CI/agent strict mode
gittriage preflight my-repo --format json # agent manifest (canonical path + verdict + warnings)
gittriage summary --agent ~/Projects --format json # compact rollups (duplicates, unsafe, dirty, nested)
gittriage plan --write plan.json
gittriage report --format md
gittriage tui # interactive terminal browser (automation column + canonical path)
gittriage score --profile security # optional scoring profile overridePrebuilt binaries: GitHub Releases (Linux musl x86_64, macOS arm64/x86_64, Windows x86_64) with .sha256 checksum files.
From source (needs Rust stable ≥ 1.82 and a C toolchain for rusqlite: macOS Xcode CLT, Linux build-essential, Windows MSVC build tools):
cargo install --locked --path crates/gittriage
# or
cargo build --release -p gittriagePackage managers & wrappers: Homebrew formula, Scoop, Chocolatey, @bmmaral/gittriage on GitHub Packages (npm), AUR PKGBUILD, and Nix are documented in docs/DISTRIBUTION.md.
| Channel | Notes |
|---|---|
| GitHub Releases | Prebuilt gittriage binaries (see link above) |
cargo install --path / cargo build |
From this repo; needs Rust ≥ 1.82 + C toolchain for SQLite |
| Homebrew / Scoop | Formulas in packaging/ |
npm (@bmmaral/gittriage) |
Wrapper around the published binary; install matrix in docs/DISTRIBUTION.md |
gitonPATH- Optional:
ghforscan --github-owner
| Command | What it does |
|---|---|
preflight <TARGET> |
Compact manifest: canonical path, alternates, warnings, automation verdict (label / path / URL) |
resolve <QUERY> |
Resolve label / path / URL → canonical path, cluster, alternates, verdict |
verdict <TARGET> |
Deterministic safe_to_* flags and unsafe_for_automation |
check-path <PATH> |
Wrong-clone check: canonical vs alternate disposition |
summary --agent <WORKSPACE>… |
Token-light workspace rollup (duplicates, unsafe, dirty canon, nested) |
| Command | What it does |
|---|---|
scan |
Discover repos into SQLite; default git_only mode inventories real .git roots (best for agents); strict flags can fail on ingest/enrichment errors; project_roots is broader — see docs/CLI.md |
score |
Compute scores + evidence from inventory (--profile to override) |
plan |
Resolve clusters → score → actions → write JSON plan (--profile) |
report |
Markdown or JSON from a fresh plan (--profile; agent-first sections when unscoped) |
doctor |
Environment and DB sanity checks |
tools |
Which optional scanners are on PATH |
export |
JSON inventory (optional embedded plan via --with-plan) |
import |
Restore inventory from export JSON (--force required) |
explain |
Per-cluster deep dive: scores, evidence, actions (optional --ai narrative) |
ai-doctor |
Show AI config / key presence; optional --probe-network checks {api_base}/models |
| Command | What it does |
|---|---|
tui |
Interactive terminal table — sort, filter, inspect, pin, export; automation verdict column |
| Command | What it does |
|---|---|
ai-summary |
Optional AI-generated narrative over the full plan (not deterministic) |
apply --dry-run |
Count proposed actions (read-only preview) |
serve |
Read-only JSON API: /v1/* inventory/plan + /v2/agent/* preflight-style operations |
See docs/CLI.md for flags, examples, and TUI keybindings.
┌──────────────────────────────────────────────┐
│ gittriage │
│ clap commands · tokio runtime │
└──┬────┬────┬────┬────┬────┬────┬────┬────┬───┘
│ │ │ │ │ │ │ │ │
scan│ git│ gh │plan│ db │ rpt│ tui│ ai │ api│
▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼
┌──────────────────────────────────────────────┐
│ gittriage-core │
│ CloneRecord · ClusterRecord · PlanDoc │
└──────────────────────────────────────────────┘
│
┌───────┴───────┐
│ SQLite (db) │
└───────────────┘
14 crates, one workspace:
| Crate | Role |
|---|---|
gittriage-core |
Domain types (CloneRecord, ClusterRecord, PlanDocument, etc.) |
gittriage-config |
Config loading (gittriage.toml) |
gittriage-db |
SQLite persistence (WAL mode, schema versioning) |
gittriage-scan |
Filesystem walking, SPDX sniffing, project cue detection |
gittriage-git |
Git metadata extraction, including upstream drift, detached HEAD, shallow clone, sparse checkout, and worktree signals |
gittriage-github |
gh CLI ingest (5000-repo pagination) |
gittriage-plan |
Clustering, scoring engine, action generation |
gittriage-agent |
Resolve, verdict, preflight, path check, agent summary, structured agent errors, reason codes, and remediation hints (deterministic) |
gittriage-report |
Markdown / JSON report rendering |
gittriage-adapters |
Optional external tool hooks (gitleaks, semgrep, syft, jscpd) |
gittriage-tui |
Ratatui interactive terminal browser |
gittriage-ai |
Optional AI explanations (OpenAI-compatible) |
gittriage-api |
Axum API for serve (experimental, loopback default, structured JSON errors) |
gittriage |
CLI crate and gittriage binary |
| Tool | Support | What it adds |
|---|---|---|
gitleaks |
Official | Secret leak detection evidence |
semgrep |
Official | Static analysis findings |
syft |
Official | SBOM / dependency inventory |
jscpd |
Best effort | Copy/paste duplication evidence |
Missing adapter tools are silently skipped — they never break the pipeline. For scan, use --fail-on-ingest-error and --fail-on-enrich-error when incomplete GitHub or local-git metadata should fail CI/agent runs. See docs/EXTERNAL_TOOLS.md.
- No web dashboard; no automatic delete/move/archive of repos.
- Scoring and clustering are heuristics — review
planandreportfor high-stakes decisions. serveis experimental (loopback-only by default)./v2/agent/*is the versioned agent contract; field additions are expected; breaking changes will be noted in release notes.- GitHub ingest caps at 5000 repos per owner; warns on truncation.
- The npm wrapper verifies release checksums and fails closed when integrity cannot be established.
- Core usefulness does not depend on AI.
| Doc | Purpose |
|---|---|
CLI.md |
Full command reference, flags, TUI keybindings |
SCORING.md |
Scoring model, evidence kinds, failure modes |
SCORING_PROFILES.md |
Optional scoring profiles |
PLAN_SCHEMA.md |
Plan JSON schema |
CONFIG.md |
gittriage.toml configuration |
ARCHITECTURE.md |
Crate layout and data flow |
PRODUCT_STRATEGY.md |
Positioning and roadmap |
EXTERNAL_TOOLS.md |
Optional scanner adapters |
DISTRIBUTION.md |
Homebrew, Scoop, Chocolatey, npm, AUR, Nix |
EXAMPLES.md |
Copy-paste scenarios |
FAQ.md |
Common questions |
DECISIONS.md |
Architecture decision records |
LEGACY_V1.md |
Python/TS prototype migration notes |
Python/TypeScript prototypes are not on main. Preserved on branch legacy/v1-python-ts and tag legacy-py-mvp. Details: docs/LEGACY_V1.md.
MIT — see LICENSE.