Documentation

Git history as focused engineering context.

Everything needed to build a local index, run targeted coupling queries, consume stable JSON, and connect histui to Pi.

Quick start

Build histui from source, create a bounded local index, and ask which files changed repeatedly with a target.

Install$ go install github.com/Rounak-stha/histui/cmd/histui@latest

Index$ histui index . --max-commits 5000

Query$ histui query coupling . --file internal/git/cli_repo.go --format json

Local by design

The index contains paths and commit metadata, lives in your platform cache directory, and never leaves your machine unless you export it.

Indexing

Initial indexing streams a bounded Git history into an atomic SQLite transaction. Queries never silently create a missing index.

# Build or replace an index
histui index . --max-commits 5000

# Incrementally append fast-forward commits
histui index . --update

# Inspect freshness and policy
histui index status . --format json

# Keep a separate index for another ref
histui index . --branch release --index-path ~/.cache/histui/release.sqlite

Index options

--max-commitsMaximum commits indexed. Default: 5000.

--max-files-per-commitMark larger commits as bulk noise. Default: 200.

--branchIndex a specific branch or ref.

--include-mergesInclude merge commits; query policy must match.

--index-pathOverride the platform cache location.

Targeted coupling query

A query finds indexed commits containing the target, counts other files in those commits, and ranks them by historical coupling.

histui query coupling . \
  --file src/auth/session.go \
  --max-commits 1000 \
  --limit 20 \
  --min-co-changes 3 \
  --freshness cached \
  --format json

--fileRequired repository-relative target file.

--limitMaximum related files returned. Default: 20.

--min-co-changesMinimum evidence required. Default: 3.

--max-commitsBounded query window. Default: 1000.

--formathuman or stable json.

Ignore files and folders

Always quote shell glob patterns. Otherwise your shell expands them into positional arguments before histui starts.

histui --coupling \
  --ignore '**/i18n/**' \
  --ignore 'package.json' \
  --ignore '*.d.ts'

# Or as one quoted, comma-separated value
histui --coupling --ignore '**/i18n/**,package.json,*.d.ts'

*.mdmatching filename at any depth

vendorfolder and complete subtree

vendor/same recursive folder behavior

docs/*direct children only

docs/**all descendants

**/i18n/**matching folder at any depth

Why “accepts at most 1 arg” happens

Unquoted **/i18n or *.d.ts is expanded by Bash/Zsh into many filenames. Quote every pattern containing *, ?, or brackets.

Freshness policies

cached

Return immediately. Stale evidence is allowed and labeled.

refresh

Append a bounded fast-forward range; otherwise return stale evidence with a warning.

strict

Fail unless the index exactly represents the selected HEAD.

Diverged or rebased history must be rebuilt. An index built for another ref is rejected; use separate index paths for multiple refs.

Stable JSON output

JSON mode writes exactly one untruncated object to stdout. Diagnostics go to stderr and failures return a nonzero status.

{
  "schemaVersion": 1,
  "repository": { "ref": "main", "currentHead": "def456" },
  "query": { "type": "file-coupling", "file": "src/auth.go" },
  "index": { "status": "fresh", "analyzedCommits": 1000 },
  "results": [{
    "path": "src/session.go",
    "coChanges": 18,
    "targetChanges": 25,
    "relatedFileChanges": 21,
    "score": 0.857,
    "strength": "critical"
  }],
  "exclusions": { "bulkCommits": 4, "ignoredFiles": 82 },
  "warnings": ["Historical coupling is evidence, not proof..."]
}

Consumers should reject unsupported schema versions and ignore unknown fields. See the full schema contract.

Pi coding-agent integration

The package bundles a typed git_history tool and an Agent Skill. Install the CLI first, then the package.

# From a local checkout
pi install /absolute/path/to/histui

# From Git
pi install git:github.com/Rounak-stha/histui

# Build the index explicitly before agent queries
histui index . --max-commits 5000

git_history({
  "file": "internal/git/cli_repo.go",
  "maxCommits": 1000,
  "limit": 20,
  "freshness": "cached",
  "ignore": ["vendor", "generated/**", "*.md"]
})

No hidden expensive work

The extension applies cancellation and timeout, invokes the CLI without a shell, and never starts a missing full index automatically.

Interpret the evidence

The v1 coupling score is:

coChanges / min(targetChanges, relatedFileChanges)

High score with many co-changes is stronger evidence.
A high score from only three commits remains weak.
No result may mean isolation, recent code, ignored files, or an insufficient window.
Bulk commits are excluded because mass formatting and generated changes create noise.
Correlation does not prove a source-level, runtime, or architectural dependency.

Troubleshooting

History index not found

Run histui index . --max-commits 5000. Queries intentionally do not create indexes.

Index is stale or diverged

Use histui index . --update for fast-forward history. Rebuild without --update after a rebase or branch divergence.

Merge or bulk policy does not match

Query flags must match index policy. Use the requested flag value or rebuild with the desired settings.

No related files returned

Try a larger bounded window or lower --min-co-changes, then verify whether ignores or bulk commits removed evidence.

NextExplore the source