tsift-cli 0.1.62

# tsift

`tsift` is a token-conscious code search and session digest CLI for coding agents.
It builds a local index, returns compact search and source-read envelopes, and
turns noisy logs, tests, diffs, and agent-doc session documents into bounded
evidence that smaller models can use without replaying an entire repository or
transcript.

## Install

Install the latest GitHub release:

```sh
curl -fsSL https://raw.githubusercontent.com/btakita/tsift/main/scripts/install.sh | sh
```

Install a specific version or directory:

```sh
TSIFT_VERSION=0.1.42 TSIFT_INSTALL_DIR="$HOME/bin" sh -c "$(curl -fsSL https://raw.githubusercontent.com/btakita/tsift/main/scripts/install.sh)"
```

The installer supports Linux x86_64 and macOS arm64 release assets. It verifies
the downloaded archive with the release SHA-256 file before installing `tsift`
into `$HOME/.local/bin` by default. macOS x86_64 users should install from
crates.io with `cargo install tsift`.

## Quick Start

```sh
tsift status --fix
tsift init --opencode
tsift --envelope search "route dispatch" --budget normal
tsift --envelope source-read src/main.rs --start 1 --lines 120 --budget normal
tsift diff-digest .
tsift --envelope session-review tasks/software/tsift.md --next-context --budget normal
tsift graph-db --path . refresh --json
tsift graph-db --path . status --json
tsift graph-db --path . compact --json
tsift graph-db --path . kind backlog --property ref_id=cvxa --limit 5 --json
tsift graph-db --path . evidence cvxa --depth 3 --limit 8 --json
tsift graph-db --path . related "realtime avatar memory" --kind all --json
tsift conflict-matrix --path tasks/software/tsift.md cvxa --json
tsift dependency-dag --path tasks/software/tsift.md cvxa --json
tsift graph-db --path . doctor --json
tsift graph-db --path . --json backend-eval --candidate kuzu
tsift graph-db --path . --json backend-eval | tsift metric-digest --baseline fixtures/graph-db-performance-history.json
tsift traverse --path . --format html > traversal.html
tsift semantic "graph navigation" --path . --kind concept --json
tsift convex-sync . --chunk-size 100 --json
```

For agent-doc projects, run `tsift status` from the repository root at session
start. If `status` recommends a fix, run `tsift status --fix` before depending
on search or digest output. OpenCode users can run `tsift init --opencode` to
install project-local `.opencode/commands/tsift-*.md` shortcuts for status,
session-review, context-pack, diff-digest, test-digest, log-digest, and
rewrite-run workflows; existing same-name command files without tsift ownership
markers are left untouched and reported as conflicts. The same command pack is
packaged as the `opencode-tsift` npm plugin; once it is published to npm,
OpenCode users can run `opencode plugin opencode-tsift` and get the marker-owned
shortcuts without cloning this repository.

Graph DB and Convex operator examples live under
`fixtures/graph-db-operator-examples`; the reusable Convex app-side schema,
mutations, and HTTP action for `tsift convex-sync --apply` live under
`examples/convex-graph`. Use `tsift graph-db refresh` to materialize
`.tsift/graph.db` explicitly, `tsift graph-db status` to inspect projection
version/hash/watermark and tombstone counts without refreshing, and
`tsift graph-db compact` to inspect or apply the guarded post-reconciliation
WAL checkpoint/VACUUM policy before pruning tombstones. Refresh reports include
node, edge, and materialized-property delta counts so unchanged property rows do
not hide write amplification. Use
`tsift graph-db evidence <backlog-id-or-job-handle>` for bounded
worker-context/source-handle/semantic handoff packets. Use `tsift graph-db
related <phrase>` to turn natural-language concept phrases into semantic
concept/entity seeds and expand incident/outgoing graph neighborhoods around
them for knowledge retrieval. Use `tsift
conflict-matrix` to rank candidate worker scopes, flag shared
file/symbol/test/config ownership, and emit first-class worker prompt packets
with worker-result feedback, closure ranking controls, expansion commands, token
budgets, and fail-closed ownership blocks before parallel dispatch. Use `tsift
dispatch-trace --format json|html` for a graph-backed operator review view
linking backlog, job packets, worker results, source handles, semantic rows,
evidence packet ids, worker-feedback closure summaries, and worker prompt
packets. Use `tsift dependency-dag` to extract a replayable agent-doc backlog
DAG with explicit dependency edges, shared ownership/semantic overlap edges,
worker-result follow-up edges, topological batches, and cycle diagnostics before
running DAG-shaped dispatch. Those orchestration surfaces include stable
contract versions, evidence packet ids, projection hashes, replay commands, and
repair commands so agent-doc can consume them as JSON rather than parsing prose.
Use `tsift graph-db backend-eval` to compare SQLite against experimental
read-only candidates, including DuckDB/DuckPGQ, FalkorDB, Ladybug, and the
dependency-free Vela-Engineering/kuzu row prototype, with adaptive
1/64/128/256/512-hop path probes that keep the default cap at 64 until real and
synthetic extended-hop gates pass, an opt-in `--full-projection` dataset, split
conflict-matrix preparation timings/cache keys that report skipped heavy phases
on cache hits, per-operation promotion gates, projection
load/concurrent-writer/install-portability notes, batched context-pack graph
writes for source/worker context rows, compressed full-projection cache footprint
metrics, and a `performance_gate`/`metric-digest` command for bounded regression
review. All read-only prototype backends remain held until a native production
adapter beats SQLite across the full-projection promotion gate without weakening
install or lock behavior.
Use `tsift graph-db doctor` to validate local `graph.db` and Convex snapshot
metadata before trusting operator handoffs. `tsift traverse --format html`
renders the selected GraphStore slice as
an offline SVG graph, and `tsift semantic` queries cached summary concepts and
entities from the same persisted graph rows without calling an API. The
operator acceptance pack under `fixtures/graph-db-operator-examples` is
regenerated by the compiled conformance suite from a real agent-doc queue
fixture, including refresh/status/doctor/evidence, stale Convex drift and
convex-sync repair planning, conflict-matrix, dispatch-trace, context-pack, and
session-review samples. The
`live_convex_graph_backend_acceptance_applies_and_matches_graph_db_queries` test
runs in the normal suite and is opt-in via `TSIFT_LIVE_CONVEX_ACCEPTANCE=1` plus
`TSIFT_LIVE_CONVEX_GRAPH_URL`; point it at a dedicated Convex deployment because
it applies and reconciles a temporary projection. Without those settings the
test exits as a documented no-op; with them configured, it becomes a remote
snapshot parity gate for graph-db node, kind, neighborhood, and path queries.

## Release Notes

GitHub release assets are built by the `Release` workflow for:

- `x86_64-unknown-linux-gnu`
- `aarch64-apple-darwin`
- `x86_64-pc-windows-msvc`

The crates.io package path lists every split Rust crate package during release
verification, then the tagged publish job runs `cargo publish --locked --dry-run`
immediately before each real publish in dependency order. The release workflow
uses the `TSIFT_ENABLE_CRATES_PUBLISH=true` repository variable and
`CARGO_REGISTRY_TOKEN` repository secret to turn on tagged crates.io publishes.
It skips crate versions that already exist on crates.io so interrupted releases
can resume, and retries crates.io rate limits.
The default lexical search adapter is maintained in-tree, so publishing no
longer depends on an upstream git-only `sift` crate.

The OpenCode command pack under `packages/opencode-tsift` is publishable to npm.
The release workflow dry-runs `npm publish --access public`; tagged npm
publishing is enabled with `TSIFT_ENABLE_NPM_PUBLISH=true` and an `NPM_TOKEN`
repository secret.