GnosysLabs/Hop
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 1 Wiki Activity

Install portable agent-neutral Hop skill and documentation

Browse Source 
Hop-State: A_06FN69X2VW0BAXG4A4DT6V0
Hop-Proposal: R_06FN69VET1STZNKPWK913K8
Hop-Task: T_06FN637799RW5Q7WH9H6PJR
Hop-Attempt: AT_06FN63779BJRBK1VFQ94GRR
This commit is contained in:
Hop
2026-07-11 14:48:54 -07:00
parent 2f00b2dd3f
commit 68d8bf2f7d
20 changed files with 649 additions and 124 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/hop/SKILL.md
+35 -14
View File
@@ -1,6 +1,6 @@
---
name: hop
description: Capture local repository prompts as Hop states and perform agent work in isolated Hop workspaces. Use at the start of every Codex Desktop or CLI repository turn and follow-up, before inspecting files, running project commands, editing, reviewing, delegating, landing, or undoing—even when the user does not mention Hop. Also use whenever HOP_STATE_ID, HOP_TASK_ID, HOP_ATTEMPT_ID, CODEX_THREAD_ID, or .hop/hop.db is present.
description: Capture local repository prompts as Hop states and perform agent work in isolated Hop workspaces. Use at the start of every interactive coding-agent repository turn and follow-up, before inspecting files, running project commands, editing, reviewing, delegating, landing, or undoing—even when the user does not mention Hop. Also use whenever HOP_STATE_ID, HOP_TASK_ID, HOP_ATTEMPT_ID, HOP_AGENT, CODEX_THREAD_ID, or .hop/hop.db is present.
---
# Hop
@@ -11,25 +11,45 @@ returned Hop workspace.
## Capture the current prompt first
Do not inspect repository files, plan from repository contents, run project
commands, edit, or delegate before capture. Run this from the selected project
directory:
commands, edit, or delegate before capture. Run the form for the current shell
from the selected project directory.
POSIX shell:
```bash
hop begin --agent codex --heredoc <<'HOP_PROMPT_EOF'
hop begin --heredoc <<'HOP_PROMPT_EOF'
<copy the current user message verbatim>
HOP_PROMPT_EOF
```
Choose a different quoted delimiter if that exact delimiter appears in the
message. Include visible attachment paths and references. Do not paraphrase,
pre-redact, or omit a suspected credential in this one capture stream; Hop must
see it to replace it deterministically before persistence. `--heredoc` removes
only the shell-added final newline. Never copy the credential anywhere else.
PowerShell:
`hop begin` performs the Desktop bootstrap:
```powershell
$hopPrompt = @'
<copy the current user message verbatim>
'@
$hopPrompt | hop begin --heredoc
```
Choose a different non-interpolating stdin construction if the applicable
terminator appears in the message. Include visible attachment paths and
references. Do not paraphrase, pre-redact, or omit a suspected credential in
this one capture stream; Hop must see it to replace it deterministically before
persistence. `--heredoc` removes only the shell-added final newline. Never copy
the credential anywhere else.
An integration may identify its runtime through `HOP_AGENT` or `--agent`, and
should pass a stable `--session` value when it has one. A stable session lets
Hop connect unfinished follow-ups without making the user carry state IDs.
Codex is one adapter example: when `CODEX_THREAD_ID` is present, `hop begin`
uses it as the default session and identifies the runtime as `codex` unless
`HOP_AGENT` or `--agent` overrides that name.
`hop begin` performs the interactive-agent bootstrap:
- Initialize Hop automatically when the project has not used it before.
- Use `CODEX_THREAD_ID` to bind this Codex task to its unfinished Hop work.
- Use the integration's stable session identity to bind later messages to
unfinished Hop work. Without one, each invocation begins independent work.
- Create a prompt state and isolated workspace on the first turn.
- Checkpoint prior workspace effects and append follow-ups until that work lands.
- Follow a reconciliation into its fresh attempt, then start the first prompt
@@ -149,10 +169,11 @@ safe continuation needs new user authority.
If visible-root synchronization is blocked, do not bypass it with `hop accept`,
force checkout, reset, or file copying. Preserve the proposal and identify the
user-owned paths that must be resolved. `hop accept` is reserved for an
explicitly controller-only workflow; Desktop work always uses `hop land`.
explicitly controller-only workflow; interactive agent work uses `hop land`.
Use `hop undo` only after a separately captured, explicit user request.
Read [references/protocol.md](references/protocol.md) for state semantics, exit
codes, recovery, and controller-grade pre-delivery capture. Skill-driven
Desktop capture is a pre-project-effect boundary; it does not claim the prompt
was stored before Codex received it.
interactive capture is a pre-project-effect boundary; it does not claim the
prompt was stored before the runtime received it. On Codex Desktop, for
example, Codex has already received the prompt before this skill can run.
skills/hop/references/protocol.md
+55 -26
View File
@@ -34,12 +34,16 @@ Prompt, checkpoint, and proposal states may reference identical Git trees while
| `HOP_TASK_ID` | Logical task grouping related prompts and attempts |
| `HOP_ATTEMPT_ID` | Current agent approach/run |
| `HOP_WORKSPACE` | Only directory the agent may modify |
| `HOP_AGENT` | Optional runtime name used by `hop begin` when `--agent` is omitted |
Interactive agents may begin without these variables. `hop begin` returns the
equivalent IDs and workspace, while `CODEX_THREAD_ID` binds later messages in
the same Codex task to unfinished work. Follow-ups before acceptance continue
the attempt; the first prompt after acceptance starts a fresh task and attempt
at the latest accepted state.
equivalent IDs and workspace. Integrations should identify themselves with
`HOP_AGENT` or `--agent` and pass a stable `--session` value when available.
That session binds later messages to unfinished work; without it, each
invocation begins independent work. The Codex adapter uses `CODEX_THREAD_ID` as
the default session and `codex` as the default runtime name. Follow-ups before
acceptance continue the attempt; the first prompt after acceptance starts a
fresh task and attempt at the latest accepted state.
## Command contract
@@ -61,10 +65,26 @@ hop undo
### Agent
POSIX shell:
```bash
hop begin --agent codex --heredoc <<'HOP_PROMPT_EOF'
hop begin --heredoc <<'HOP_PROMPT_EOF'
<exact current user message>
HOP_PROMPT_EOF
```
PowerShell:
```powershell
$hopPrompt = @'
<exact current user message>
'@
$hopPrompt | hop begin --heredoc
```
Then continue in the returned workspace:
```bash
hop state "$HOP_STATE_ID" --json
hop status --json
hop check "$HOP_STATE_ID" -- <command>
@@ -73,6 +93,11 @@ hop land <proposal-state> -- <final validation command>
hop refresh <proposal-state>
```
An adapter may set `HOP_AGENT=<runtime>` or pass `--agent <runtime>`. If it has
a stable conversation/run identifier, it should also pass `--session <id>` on
every `hop begin`. Codex normally needs neither explicit flag because
`CODEX_THREAD_ID` supplies its session adapter automatically.
`hop check` snapshots the attempt and runs the command in a detached worktree materialized from that exact checkpoint. Edits made concurrently in the live workspace do not change the tested tree.
`hop propose` freezes the current nonignored workspace tree. Later workspace edits cannot change the proposal.
@@ -85,13 +110,13 @@ unresolved product ambiguity, or newly required destructive/external scope
stops automatic acceptance. Path overlap and a stale accepted head do not:
Hop merges, retries, or prepares agent reconciliation.
`hop land` is the Desktop operation. It performs a real Git three-way content
merge, so compatible edits in the same file and identical changes compose
automatically. It validates and advances accepted state, then safely
materializes that tree into the selected visible project root. The root must
still match an accepted Hop ancestor, and ignored or untracked destination
collisions block before acceptance. Materialization uses a disposable index and
never moves HEAD, the active branch, or the user's real index.
`hop land` is the interactive working-root operation. It performs a real Git
three-way content merge, so compatible edits in the same file and identical
changes compose automatically. It validates and advances accepted state, then
safely materializes that tree into the selected visible project root. The root
must still match an accepted Hop ancestor, and ignored or untracked destination
collisions block before acceptance. Materialization uses a disposable index
and never moves HEAD, the active branch, or the user's real index.
When the three-way merge has genuine unresolved conflicts, `hop land` returns
exit `20` and automatically prepares a reconciliation prompt in the original
@@ -110,13 +135,16 @@ explicit form of the same preparation step.
`hop sync` safely catches a stale accepted-ancestor root up to the current
accepted state, including projects created with older Hop builds.
`hop begin` is the Codex Desktop entry point. It initializes Hop when necessary,
captures the current message before the agent performs project work, and uses
`CODEX_THREAD_ID` as the default session key. A later `hop begin` in the same
Codex task checkpoints the prior workspace before appending a follow-up while
that work remains unfinished. Reconciliation transfers the session to its fresh
attempt. After a proposal is accepted, the next `hop begin` starts from the
latest accepted state and never reopens the completed workspace.
`hop begin` is the interactive-agent entry point. It initializes Hop when
necessary and captures the current message before the agent performs project
work. Runtime adapters identify themselves through `HOP_AGENT` or `--agent`
and use `--session` to supply a stable conversation/run key. A later
`hop begin` with the same session checkpoints the prior workspace before
appending a follow-up while that work remains unfinished. Reconciliation
transfers the session to its fresh attempt. After a proposal is accepted, the
next `hop begin` starts from the latest accepted state and never reopens the
completed workspace. Codex Desktop supplies `CODEX_THREAD_ID` as its default
session key, so its adapter does not need to add `--session` explicitly.
Pass the original message to `hop begin` without model-side redaction. Hop's
sanitizer replaces detected credential values before any durable write and
@@ -139,19 +167,20 @@ A failed `hop check` or final landing check persists its evidence. A blocked or
## Capture modes
### Codex Desktop skill
### Interactive agent skill
The user types normally in Codex Desktop. The Hop skill makes `hop begin` its
first project action and then directs every operation into the returned
workspace. This is a pre-project-effect boundary: Codex has already received
the prompt, but no repository inspection, command, or modification may precede
the durable prompt state.
The user types normally in their agent interface. The Hop skill makes
`hop begin` its first project action and then directs every operation into the
returned workspace. This is a pre-project-effect boundary: the runtime has
already received the prompt, but no repository inspection, command, or
modification may precede the durable prompt state. Codex Desktop is one such
adapter; it provides session continuity through `CODEX_THREAD_ID`.
### Controller-grade pre-delivery capture
```bash
hop init
hop start --agent codex "Add password reset emails"
hop start --agent <runtime> "Add password reset emails"
```
Use the returned workspace and environment to launch the agent. For example, conceptually: