# Hop

Hop is an experimental prompt-native version-control kernel for coding agents.

Every instruction becomes an immutable state before project effects. Agent work produces checkpoint and proposal states beneath it. Landing a proposal creates a new accepted state without moving the user’s Git branch or checkout. Controller integrations may capture the stronger pre-delivery boundary as well.

```text
A0 accepted
├─ P1 prompt
│  └─ C1 checkpoint
│     └─ R1 proposal
└─ P2 prompt
   └─ R2 proposal

A0 + R1 → A1 accepted
```

Git provides source-tree storage, diffs, worktrees, and interoperability. Hop’s prompt-state graph, evidence, and acceptance history live separately in `.hop/hop.db`.

## Current status

This repository contains the first local alpha kernel. It supports:

- Existing and unborn Git repositories
- Codex Desktop first-action prompt capture and session-aware follow-ups
- Controller-grade pre-delivery prompt capture
- Isolated detached worktrees per attempt
- Immutable checkpoints and proposals
- Checks bound to exact source trees
- Conservative path-level conflict detection
- Three-tree composition of disjoint proposals
- Optional validation on the final integrated tree
- Compare-and-swap acceptance
- Forward-only undo of the latest accepted transition
- Git-compatible accepted commits under `refs/hop/accepted`
- SQLite WAL state graph and machine-readable JSON output
- Pre-persistence credential redaction across prompts, summaries, and check evidence
- Embedded, installable vendor-neutral agent skill with implicit invocation enabled

It does not yet include a trusted raw-prompt hook, project knowledge, claims, remote synchronization, a GUI, or semantic merging.

See [the product blueprint](docs/product-blueprint.md) for the complete model,
design principles, and phased roadmap.

## How the pieces fit

```text
Prompt in Codex Desktop
  │
  ▼
Hop skill's first action ──> hop begin ──> prompt state + workspace
                                                │
                                                ▼
                                      edit → check → propose
                                                │
                                                ▼
Human                                  review → land → accepted state
```

The user continues typing into Codex Desktop normally. The skill invokes `hop begin` before inspecting or changing the project. `hop begin` initializes Hop when needed, uses `CODEX_THREAD_ID` to recognize follow-ups, checkpoints prior effects, and returns the isolated workspace. The skill then confines work to that workspace. This is a pre-project-effect boundary: the prompt is stored after Codex receives it but before the agent performs project work. A controller or future trusted prompt hook can provide strict pre-delivery capture.

## Build

Requires Go 1.26+ and Git.

```bash
go build -o hop ./cmd/hop
./hop help
```

## Quick start

Install the embedded skill for Codex. By default this writes to `${CODEX_HOME:-~/.codex}/skills/hop`:

```bash
hop skill install
```

Export it to another agent’s skills directory with:

```bash
hop skill install --path /path/to/agent/skills
```

Restart Codex after installation if the skill is not yet visible. Then use Codex Desktop normally. The skill is configured for implicit invocation on every local repository turn. Its first project action is equivalent to:

```bash
hop begin --agent codex --heredoc <<'HOP_PROMPT_EOF'
<the current user message>
HOP_PROMPT_EOF
```

The agent—not the user—runs this command. It initializes Hop without changing the current Git branch, working tree, or index, stores the prompt, and returns the state IDs and isolated workspace. Follow-up messages in the same Codex task automatically continue the same Hop attempt.

Codex chooses implicitly invoked skills from their descriptions. Explicitly mentioning `$hop` remains the deterministic fallback if a task does not activate it automatically.

After the agent edits the printed workspace:

```bash
hop check P_... -- go test ./...
hop propose --summary "Added password reset emails" P_...
hop land R_... -- go test ./...
```

The command supplied to `land` runs in a temporary worktree containing the exact final tree that would become accepted. If it fails, `refs/hop/accepted` and the SQLite accepted head do not move.

Inspect the project:

```bash
hop status
hop graph
hop state P_...
hop diff R_...
hop history
hop doctor
```

Inspect or hand the skill to a harness without installing it:

```bash
hop skill print
```

For a harness or controller that can capture prompts before delivery, initialize and start explicitly:

```bash
hop init
hop start --agent codex --heredoc <<'HOP_PROMPT_EOF'
Add password reset emails
HOP_PROMPT_EOF
eval "$(hop env P_...)"
```

In this mode, deliver the same message only after `hop start` succeeds. Use `hop prompt --from P_... --heredoc` for controller-managed follow-ups.

Undo the latest accepted transition without rewriting history:

```bash
hop undo
```

## Parallel work

Two prompts started from the same accepted state receive independent worktrees:

```bash
hop start --agent codex "Add a health endpoint"
hop start --agent claude "Add an account empty state"
```

If their changed paths are disjoint, both proposals can land in either order. The second proposal is composed onto the latest accepted tree and may be validated there.

If both proposals changed the same path since their shared base, Hop blocks the stale proposal even when Git could textually merge it. The proposal remains addressable for review or a future reconciliation prompt.

## State model

| Kind | Prefix | Meaning |
|---|---:|---|
| Accepted | `A_` | Canonical project revision |
| Prompt | `P_` | Exact instruction and pre-effect context |
| Checkpoint | `C_` | Immutable workspace progress |
| Proposal | `R_` | Frozen candidate result |
| Failed | `F_` | Terminal failed execution state |
| Cancelled | `X_` | Terminal cancelled execution state |

Each Hop state references an immutable Git tree and synthetic commit. Multiple prompt states can reference the same tree while remaining distinct occurrences.

Source objects are pinned beneath `refs/hop/states/*`, preventing Git garbage collection from deleting states referenced by SQLite. Accepted source history is mirrored at `refs/hop/accepted` and can be exported as ordinary Git commits later.

## Storage

```text
.hop/
├── hop.db                 SQLite state graph and audit log
├── workspaces/            isolated attempt worktrees
├── integration/           temporary final-state validation worktrees
└── accept.lock            short-lived acceptance serialization lock
```

The repository’s `.git/info/exclude` receives `.hop/`; the public `.gitignore`, current branch, and real Git index are left alone.

Initialization refuses to proceed if `.hop` is already tracked as user-owned project source.

## JSON protocol

Add `--json` anywhere:

```bash
hop --json status
hop begin --agent codex --heredoc --json
```

Successful output follows:

```json
{
  "ok": true,
  "data": {}
}
```

The JSON shape is an alpha contract and may evolve before the first tagged release.

## Safety boundary

Hop currently treats any shared changed path as a conflict. Disjoint files can still conflict behaviorally, so manual acceptance remains the default and final-tree validation is strongly recommended.

Agent-reported scope and test claims are never used as the source of truth. Hop computes source trees and changed paths itself.

Non-secret prompt text and check output are stored locally in SQLite without encryption. Before persistence, Hop redacts high-confidence provider tokens and contextual credentials, private keys, authorization headers, and credential-bearing URLs. The same boundary sanitizes proposal summaries plus recorded validation commands and output.

Detection cannot recognize every private or future token format. Prefer environment variables or a secret manager, and rotate any real credential pasted into any agent prompt even when Hop reports that it redacted the value.

Skill-driven Desktop capture stores the agent's verbatim transcription of the visible message and attachment references. It cannot prove byte-for-byte fidelity with Codex's raw submission. A trusted `UserPromptSubmit` hook is the future deterministic capture boundary; the skill remains the no-UI-change alpha workflow.