holt
by Raed2180416
README.md
<div align="center">
<img src="docs/brand/holt-wordmark.png" alt="Holt, a product of Contrare Research" width="560">
# Holt
### See what your agents changed. Keep the work that matters.
**Find duplicate work, overlapping edits, dependencies, and changes that need preserving.
Built by a solo developer at Contrare Research.**
[](#license)
[](https://github.com/Raed2180416/holt/releases/latest)
[](https://github.com/Raed2180416/holt/actions/workflows/ci.yml)
[](https://raed2180416.github.io/holt/)
</div>
I built Holt after Claude Code duplicated work and deleted originals while I was working on a
large project. Keeping track of the agents had become its own job.
Holt brings their separate workspaces, called **Git worktrees**, into one local view. It helps you
see what changed, find repeated implementations and overlapping edits, review what depends on
what, and check what needs preserving before cleanup. You can use it from a terminal, inspect an
offline graph, or give your agents the same context through project integrations.
The useful question is what the agent should know **before its next action**. Is another
worktree already implementing the API it needs? Will a sibling change collide with this one?
Does a workspace still hold the only copy of a fix? Holt makes that cross-worktree state
inspectable and queryable, with separate evidence checks for preservation and cleanup.
This is a tool for the agent's workflow. The current release does not claim measured gains in
agent success rate, speed, or token use. Those need valid comparisons on real tasks.
## Try a read-only check
### See the result before using your own repository
[Run the disposable first-look fixture](https://github.com/Raed2180416/holt-first-look). It makes a
temporary Git repository with two sibling worktrees, then runs Holt in strict read-only mode. One
worktree has a reassuring name but holds modified, untracked, and ignored work; the other is empty.
Nothing in your own repository is changed, removed, or uploaded.
```bash
git clone https://github.com/Raed2180416/holt-first-look.git
cd holt-first-look
./try-holt.sh
```
### Check your own repository, read only
Open a terminal inside a repository with linked worktrees, then run:
```bash
npm exec --yes --loglevel=error --allow-remote=root --package=https://github.com/Raed2180416/holt/releases/latest/download/holt.tgz -- holt risk --strict-read-only --no-symbols --include-primary
```
Requires Node `^22.22.2 || ^24.15.0 || >=26.0.0` and Git 2.45 or newer. This downloads the official
release into npm's cache and runs the check without a global install. It does not change repository
files, hooks, or locks, and does not upload your code. `--allow-remote=root` permits this explicitly
requested URL package on npm 12 while keeping transitive URL dependencies blocked.
Look for **UNIQUE WORK**. Holt reports local work that needs attention across the main checkout
and its linked worktrees. This quick mode skips symbol analysis; committed comparisons can be
approximate, so it is a first look, not permission to delete anything. A repository with no linked
worktrees or no unsaved work may have little to show.
I'm Raed, the solo developer behind Holt at **Contrare Research**. I'm trying to find people this
actually helps. If you give it a try, [tell me how it went](https://github.com/Raed2180416/holt/issues/new?template=first_look.yml).
Honest opinions and criticism are welcome, including if it feels confusing or unnecessary.
[Website and demo](https://raed2180416.github.io/holt/) ·
[Disposable first look](https://github.com/Raed2180416/holt-first-look) ·
[Git worktree cleanup guide](https://raed2180416.github.io/holt/git-worktree-cleanup.html)
<!-- HOLT:SOCIAL-PROOF:BEGIN
Social proof stays commented out until the published 500-star gate is met and a reviewed change
enables it. scripts/milestone.mjs is report-only unless a maintainer deliberately runs --apply.
<div align="center">
[](https://github.com/raed2180416/holt/stargazers)
<a href="https://star-history.com/#raed2180416/holt&Date">
<img alt="Star history" width="600" src="https://api.star-history.com/svg?repos=raed2180416/holt&type=Date&theme=dark">
</a>
</div>
HOLT:SOCIAL-PROOF:END -->
> **Current status:** Get the latest published artifact and its checksums from
> [GitHub Releases](https://github.com/Raed2180416/holt/releases/latest). This source checkout
> may contain later, unreleased work; verify the version of the artifact you install.
> Team and Enterprise are not being sold or activated in this launch.
## The short version
Coding agents make parallel software work cheap. They also leave valuable state distributed
across commits, the index, unstaged edits, untracked files, ignored paths, branches, and linked
worktrees. Ordinary Git commands can inspect those pieces, but do not give one repository-wide
answer to the transaction question:
> **If this workspace is cleaned up or this change is landed now, what unique work could be lost or
> misintegrated, and what recovery path exists?**
Holt is the layer at that seam. It relates the real local state, separates exact evidence from
advisory intelligence, preserves work before a destructive action, re-checks the action boundary,
and emits a recovery receipt. It is complementary to Git, worktree managers, CI, editors, and
agent orchestrators; it is not a replacement for any of them.
The core loop is:
```text
observe → classify → protect → gate → act → verify/recover
```
[](docs/evidence/tui-graph/)
<sub>Actual <code>holt tui --snapshot</code> output from the real renderer against a controlled
real-Git fixture. The linked evidence packet contains the reproduction path and
checksum.</sub>
## Install for regular use
Holt currently requires Node `^22.22.2 || ^24.15.0 || >=26.0.0` and Git 2.45 or newer. Git 2.45
is the safety floor for the local-object checks Holt performs. The stable URL below installs the
latest version that has actually been published, which may differ from this checkout; verify
`holt --version`, the release notes, and the checksums for the exact artifact you install.
```bash
npm install -g https://github.com/Raed2180416/holt/releases/latest/download/holt.tgz --allow-remote=root
cd your-repository
holt --version
holt risk --strict-read-only --no-symbols --include-primary
```
After reviewing the first result, `holt setup` can configure supported project integrations and
`holt auto` can apply reversible protection. Those are optional next steps, not part of the first
read-only check. See [HOSTS.md](HOSTS.md) for the scope of each integration.
To replay the repository's smallest adversarial proof from source: one empty worktree with a
reassuring name beside a misleadingly named worktree holding modified, untracked, and ignored
content, run:
```bash
node scripts/run-preseed-demo.mjs --json
```
The demo creates an isolated temporary Git repository, exercises both `gate` exit-code contracts,
previews cleanup, applies quarantine only to the measured-empty worktree, inventories the recovery
copy, restores it, and independently checks its HEAD and byte digest. It removes its own restored
fixture after the proof; add `--keep` to inspect it.
`holt clean` is a dry run. `holt clean --apply` re-checks candidates immediately before moving
provably disposable worktrees into locked local quarantine; it does not delete files or branches
and returns the exact restore path. `holt purge` is a separately named, dry-run-first disk
reclamation action and requires an explicit apply step after review.
For a repository whose real landing branch is not the remote/default branch Holt detects, bind
that authority once in private Git-common state (not in a branch-controlled config file):
```bash
holt base # show the selected ref and why
holt base set origin/production # persist an explicit, resolvable integration ref
holt base unset # return to conservative detection
```
`holt discard` is also dry-run capable and now records a durable transaction before moving any
selected path. If a process interruption or concurrent writer leaves work in physical quarantine,
list and resume it without re-selecting mutable pathnames:
```bash
holt recover-discard
holt recover-discard <transaction-id>
```
## What is available today
The current free/core boundary is local, Git-native, and single-repository. It does not require an
account, hosted code upload, telemetry, or a managed control plane.
| Job | Current surface | What the result means |
|---|---|---|
| See the repository-wide state | `status`, `risk`, `context`, TUI, offline relationship graph | A measured view of workstreams, unique content, collisions, duplicates, dependencies, and bounds. |
| Decide whether work is disposable | `gate`, `clean`, `protect`, `auto` | Exact path/content/reachability evidence can hold or permit an action. Unknown or unmeasured state stays unknown. |
| Preserve before acting | `rescue`, `discard`, `recover-discard`, `clean --apply`, `quarantines`, `restore` | Capture or quarantine is verified before release; interrupted state remains local and resumable. |
| Coordinate parallel work | `collisions`, `hotspots`, `duplicates`, `impact`, `order`, `partition`, `branches`, `stash`, `plan` | Relationship findings guide review and landing. They are not silently promoted into destructive authority. |
| Connect agents | Project-scoped MCP, `brief`, `integrate`, and host-specific hooks | Capability is reported per host as advisory, contract-tested, or live-observed; configuration on disk is not proof of a live deny. |
| Review incidents and provenance | `journal`, `forensics`, `audit` | Local receipts and package/runtime checks can be inspected offline on customer-controlled storage. |
The most important product rule is the boundary between proof and advice:
- Exact path, operation, mode, object type, object identity, and verified recovery evidence can
influence destructive authority.
- Symbol overlap, clone similarity, dependency impact, family grouping, and landing order are
useful review signals. They do not prove semantic equivalence or permission to delete.
- A failed instrument, an exceeded bound, or an unmeasured path lowers confidence. It does not
become a clean-looking answer.
## A five-minute mental model
Imagine three agents working in linked Git worktrees:
```text
agent A: one local commit
agent B: staged edits plus an untracked migration
agent C: ignored generated output that is the only copy of a useful artifact
```
Branches alone do not describe that state. Holt builds a repository-wide evidence view, identifies
what is unique, and keeps a cleanup operation reversible:
```text
inspect → protect or rescue → re-check → quarantine → restore if needed
```
The same model applies before landing: show collisions, dependencies, and the evidence behind the
proposed order, then run the supplied combination test when a specific interaction needs empirical
verification. A clean supplied test means only that that test observed no combination-only failure;
it is not a universal compatibility certificate.
## Where Holt fits
| Existing tool or layer | Its job | Holt's boundary |
|---|---|---|
| Git and Git worktree | Version control and workspace primitives | Relate local state across worktrees before a lock, cleanup, or landing action. |
| Worktree managers | Create, move, and organize worktrees | Supply repository-wide content evidence and recovery-first disposition. |
| Agent orchestrators and editors | Dispatch and operate agents | Supply the transaction context and action seam; Holt does not choose the task or model. |
| CI and merge queues | Test and order committed changes | Protect valuable pre-PR state and investigate specific interactions before work is shared. |
| Hosted agent/cloud sandboxes | Run work away from a local machine | Local locks do not reach cloud or ephemeral agents by default; no cloud enforcement claim is made. |
**Holt is the local transaction and recoverability layer for parallel coding-agent work.**
## Integration coverage
`holt integrate` writes project-scoped files and preserves existing user configuration. Re-running it
repairs Holt-owned entries without duplicating them; `holt uninstall` removes only receipt-owned,
unchanged artifacts. Host configuration on disk is not evidence that a host loaded, trusted, or
enforced it.
- **MCP**: 18 tools in the executable schema, including live ownership and discard preview/recovery. The protocol
path is exercised over stdio as `initialize → 18 tools → tools/call`; MCP remains reactive
model-pull unless a host supplies a separate lifecycle context hook.
- **Implemented deterministic pre-tool blocking**: Claude Code, OpenCode, Cursor, Codex local clients, Qwen Code, Copilot CLI, Cline IDE, Goose, Devin CLI and Devin Desktop Cascade cover their documented local surfaces. Their current schemas are contract-tested, but none is currently claimed as a real-host enforcement run.
- **Hook-capable, not yet wired**: Gemini, Crush, Amp, Factory and Junie still receive MCP + advisory.
- **Cloud or ephemeral**: Codex cloud, Copilot cloud, Cursor cloud, Google Jules, Replit Agent do not receive local worktree enforcement by default.
### Structured local/MCP tools
A clean worktree can still belong to an agent that is thinking or preparing its next edit.
`holt ownership claim <id> --owner <session-id>` keeps that workspace out of cleanup and landing
plans until the session releases it. Renew with `heartbeat`, transfer with `handoff`, and finish
with `release`. [The ownership workflow](docs/LIVE-OWNERSHIP.md) explains expiry and recovery.
Codex project hooks use a broad `PreToolUse` matcher because MCP and other local functions are
part of the same host event stream. Holt never treats a convenient field such as `path` as proof
that a tool mutates the repository. Add exact contracts to `.holtrc.json` when a server's schema is
reviewed:
```json
{
"toolContracts": [
{
"host": "codex",
"tool": "mcp__filesystem__delete_file",
"pathField": "path",
"role": "delete",
"kind": "filesystem delete"
},
{
"host": "codex",
"tool": "mcp__filesystem__read_file",
"role": "ignore",
"kind": "filesystem read"
}
]
}
```
Tool names are exact (not regexes). `delete`, `overwrite`, and `move` feed Holt's existing
content-evidence gate; `ignore` is only for a reviewed read-only tool. An uncontracted Codex
structured tool is denied through Codex's fail-closed hook dialect by default. Repositories that
choose `"unknownToolPolicy": "audit"` explicitly accept an observable, journalled fail-open path;
that is an audit decision, not proof of mutation safety.
Holt describes nearly 30 distinct agent product surfaces, but support is deliberately split by
evidence grade. Current MCP/hook files for Cursor, Codex, Qwen Code, Copilot, Cline, Goose, Continue, Devin CLI, Cascade, Crush, Gemini CLI and VS Code are generated and parsed in schema fixtures. Gemini, Crush, Amp, Factory and Junie hooks are still unverified and unwired; their hosts remain MCP-capable rather than live-verified blockers. Run `holt providers`, `holt hosts`, and `holt doctor --json` for the machine-readable provider, configured-on-disk, trust, runtime, and live-proof boundaries.
## Evidence and limits
The repository contains deterministic unit, end-to-end, filesystem, Git, package, protocol, and
mutation checks for the shipped surface. It also records a CI matrix for the core safety and CLI
flows on Linux, macOS, and Windows. Read [the feature-proof matrix](docs/FEATURE-PROOF-MATRIX.md)
for the exact executable evidence, independent oracles, denominators, and remaining gaps.
No current test count or mutation score is published. A number becomes eligible only when the
complete, linked release and mutation evidence meets the repository's publication contract.
The full publication contract is in [BENCHMARKS.md](BENCHMARKS.md) and [eval/README.md](eval/README.md).
The security and data boundary is in [docs/SECURITY-QUESTIONNAIRE.md](docs/SECURITY-QUESTIONNAIRE.md);
`holt audit` provides an offline check of an installed package's declared capabilities and bytes.
### Important operational limits
- `rescue` and `discard` preserve captured bytes as ordinary unencrypted local Git objects under
`refs/holt/*`. Holt does not classify those bytes as secrets. Use approved encrypted storage or
whole-worktree quarantine when the Git object database is not an acceptable trust boundary.
- A local Git lock does not stop every filesystem path or every force override. Supported host
hooks extend coverage, and their scope and failure modes are listed in [HOSTS.md](HOSTS.md).
- Ignored paths are included in destructive analysis, but Holt does not claim semantic understanding
of ignored content. Unresolved ignored bytes keep a worktree out of the disposable set.
- Jujutsu is a different product boundary: auto-snapshots reduce the Git-specific “only uncommitted
copy” problem, while collision, duplicate, order, and review-load signals remain useful.
## Try it in your own workflow
The free single-repository core is the current public offer. If you already use several local
worktrees, try the first check and [tell me how it went](https://github.com/Raed2180416/holt/issues/new?template=first_look.yml).
A short account of what helped, what was confusing, or why you do not need it is useful.
Team and Enterprise are not being sold or activated in this launch.
Holt is a product of [Contrare Research](https://github.com/Raed2180416). Product and research queries:
[research.contrare@outlook.com](mailto:research.contrare@outlook.com).
## Built on proven open source
Holt assembles mature instruments rather than asking teams to replace their stack:
[universal-ctags](https://github.com/universal-ctags/ctags) for measured symbols,
[enry](https://github.com/go-enry/go-enry) for content-based language resolution,
[jscpd](https://github.com/kucherenko/jscpd) for optional token-level clone detection,
`git merge-tree` for committed-delta evidence, and [jj](https://jj-vcs.dev/) as a first-class
backend. Optional backends have explicit degradation paths; absence never becomes deletion
authority.
## License
- The complete single-repository product is covered by **[FSL-1.1-MIT](LICENSE.md)**: free for
every defined Permitted Purpose, including internal commercial use that is not a Competing Use.
- Each FSL-covered release converts to MIT on its own second anniversary.
- Team and Enterprise implementations under `src/team/` are source-available under their
[commercial license](src/team/LICENSE). They are not part of the public free/core offer above.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessUnresponsive