Install portable agent-neutral Hop skill and documentation

Hop-State: A_06FN69X2VW0BAXG4A4DT6V0 Hop-Proposal: R_06FN69VET1STZNKPWK913K8 Hop-Task: T_06FN637799RW5Q7WH9H6PJR Hop-Attempt: AT_06FN63779BJRBK1VFQ94GRR
2026-07-11 14:48:54 -07:00
parent 2f00b2dd3f
commit 68d8bf2f7d
20 changed files with 649 additions and 124 deletions
@@ -1,16 +1,26 @@
-# Codex Desktop and agent workflow
+# Agent integrations and workflow

-## Codex Desktop
+## Skill-based integration

-Users type into Codex normally. The installed skill makes prompt capture the
-agent's first repository action:
+A compatible agent skill makes prompt capture the agent's first repository
+action. The integration supplies a stable agent and session identity. In a
+POSIX shell:

 ```bash
-hop begin --agent codex --heredoc <<'HOP_PROMPT_EOF'
+hop begin --agent my-agent --session stable-session-id --heredoc <<'HOP_PROMPT_EOF'
 <exact visible user message>
 HOP_PROMPT_EOF
 ```

+In PowerShell:
+
+```powershell
+$hopPrompt = @'
+<exact visible user message>
+'@
+$hopPrompt | hop begin --agent my-agent --session stable-session-id --heredoc
+```
+
 The agent adopts the returned `HOP_STATE_ID`, `HOP_TASK_ID`,
 `HOP_ATTEMPT_ID`, and `HOP_WORKSPACE`, then confines reads, commands, edits, and
 tests to that workspace.
@@ -26,15 +36,22 @@ hop land R_... -- go test ./...
 No second landing authorization is requested unless the user explicitly asks
 for review-first behavior.

-Desktop capture stores the agent's verbatim transcription of the visible
-message and its attachment references. Because the skill runs after Codex
+Skill-based capture stores the agent's verbatim transcription of the visible
+message and its attachment references. Because the skill runs after the client
 receives the message, it cannot prove byte-for-byte fidelity with the raw
 submission. A trusted prompt-submission hook or controller is the deterministic
 capture boundary.

+### Codex Desktop example
+
+The bundled Codex integration uses `CODEX_THREAD_ID` as its stable session key,
+defaults the agent name to `codex`, and lets the user type normally. Its bundle
+is installed at `${CODEX_HOME:-~/.codex}/skills/hop`; the same files are also
+installed at `~/.agents/skills/hop` for compatible clients.
+
 ## Follow-up messages

-A later `hop begin` with the same Codex task session checkpoints existing
+A later `hop begin` with the same integration session checkpoints existing
 workspace effects, appends a new prompt state, and continues the same attempt
 while that work remains unfinished. If Hop prepares reconciliation, the session
 follows its fresh workspace. After the result lands, the next prompt starts a
@@ -60,8 +77,8 @@ follow-ups use:
 hop prompt --from P_... --heredoc
 ```

-This provides a stronger pre-delivery boundary than a Desktop skill, which can
-only guarantee capture before project effects.
+This provides a stronger pre-delivery boundary than an agent-side skill, which
+can only guarantee capture before project effects.

 ## Agent rules

@@ -25,7 +25,7 @@ mirrored at `refs/hop/accepted`.
 - prompt/task/attempt identity;
 - typed state edges and accepted lineage;
 - evidence tied to exact source trees;
- session heads for Desktop follow-ups;
+- session heads for interactive-agent follow-ups;
 - materialized-root state; and
 - immutable audit events.

@@ -46,9 +46,9 @@ initialization when `.hop` is already tracked as user-owned project content.
 ## Acceptance consistency

 Acceptance is serialized and compare-and-swapped. SQLite is authoritative;
-derived Git refs can be repaired by `hop doctor --repair`. Desktop landing also
-tracks which accepted state is physically visible, allowing safe catch-up with
-`hop sync` without treating a divergent folder as disposable.
+derived Git refs can be repaired by `hop doctor --repair`. Visible-root landing
+also tracks which accepted state is physically visible, allowing safe catch-up
+with `hop sync` without treating a divergent folder as disposable.

 For the full product direction, read the
 [product blueprint](https://githop.xyz/GnosysLabs/Hop/src/branch/main/docs/product-blueprint.md).
@@ -18,7 +18,7 @@ release.
 | Command | Purpose |
 |---|---|
 | `hop init [path]` | Initialize Hop without moving the Git branch or index |
-| `hop begin ...` | Desktop entry point: initialize if needed, capture prompt, continue session |
+| `hop begin ...` | Interactive-agent entry point: initialize if needed, capture prompt, continue session |
 | `hop prompt ...` | Controller-managed prompt or follow-up capture |
 | `hop checkpoint STATE` | Freeze current attempt progress |
 | `hop check STATE -- COMMAND...` | Validate an immutable checkpoint |
@@ -49,15 +49,16 @@ release.
 | `hop history` | Accepted lineage |
 | `hop version` | Installed version |

-## Skill distribution
+## Agent integration bundle

 ```bash
 hop skill install [--path SKILLS_DIR] [--force]
 hop skill print
 ```

-Without `--path`, the skill installs under
-`${CODEX_HOME:-~/.codex}/skills/hop`.
+Without `--path`, Hop installs the same Hop-managed skill files at
+`~/.agents/skills/hop` and `${CODEX_HOME:-~/.codex}/skills/hop`. With `--path`,
+it installs only to `SKILLS_DIR/hop`.

 ## Exit codes

@@ -22,9 +22,10 @@ different moments and causal roles.

 A task groups the prompts and attempts pursuing one user outcome. Follow-up
 messages pursuing unfinished work stay connected automatically through
-`CODEX_THREAD_ID`. Once that outcome is accepted, the next message starts a new
-Hop task at the latest accepted state even when the Codex conversation stays
-open.
+a stable session ID supplied by the integration. Codex Desktop supplies
+`CODEX_THREAD_ID` automatically. Once that outcome is accepted, the next message
+starts a new Hop task at the latest accepted state even when the client
+conversation stays open.

 ## Attempt and workspace

@@ -54,7 +55,7 @@ state but intentionally leaves the visible folder unchanged.

 ## Visible root

-The visible root is the project directory selected in Codex. Hop only
-materializes into it when it still matches an accepted Hop ancestor. Untracked,
-ignored, staged, or ordinary file divergence that could be overwritten causes a
-fail-closed error.
+The visible root is the project directory selected in an agent client or passed
+as the controller's working directory. Hop only materializes into it when it
+still matches an accepted Hop ancestor. Untracked, ignored, staged, or ordinary
+file divergence that could be overwritten causes a fail-closed error.
@@ -1,18 +1,27 @@
 # Getting started

-## Use Hop from Codex Desktop
+## Use Hop with an agent integration

 1. [Install Hop](Installation).
-2. Restart Codex Desktop if it was already open.
-3. Select an existing Git project as the Codex working directory.
-4. Ask Codex to make a normal change.
+2. Select an existing Git project in a compatible agent client, or make it the
+   controller's working directory.
+3. Ask the agent to make a normal change.

 That is the full user workflow. Do not manually create `.hop`, route the prompt
-through a terminal, or tell Codex to work inside `.hop/workspaces`. The Hop skill
-does that coordination for the agent.
+through a terminal, or tell the agent to work inside `.hop/workspaces`. A Hop
+integration does that coordination for the agent.

-The skill is eligible for implicit activation on every repository task. Mention
-`$hop` in the task if you want deterministic explicit activation.
+Without `--path`, `hop skill install` writes the same Hop-managed skill files to
+`~/.agents/skills/hop` and `${CODEX_HOME:-~/.codex}/skills/hop`. Compatible
+runtimes can use the shared bundle. An explicit `--path` installs only to the
+requested skills directory.
+
+### Codex Desktop example
+
+Restart Codex Desktop after installing or upgrading the skill, select a Git
+project, and ask Codex to work normally. The skill is eligible for implicit
+activation on every repository task; mention `$hop` for deterministic explicit
+activation.

 ## What happens on the first task

@@ -37,7 +46,7 @@ hop history
 hop doctor
 ```

-A normal Desktop result reports `Root: synchronized`.
+A normal interactive result reports `Root: synchronized`.

 ## Ask for review before landing

@@ -48,9 +57,10 @@ local code change. To stop at a proposal, say one of the following in the task:
 - `proposal only`
 - `do not land`

-## Use another agent runtime
+## Connect another agent runtime

-Install the embedded skill into that runtime's skills directory:
+If a compatible runtime does not read `~/.agents/skills`, install the embedded
+bundle into that runtime's skills directory:

 ```bash
 hop skill install --path /path/to/agent/skills --force
@@ -10,7 +10,7 @@ visible project folder.
 - [Installation](Installation)
 - [Getting started](Getting-Started)
 - [Core concepts](Core-Concepts)
- [Codex Desktop and agent workflow](Agent-Workflow)
+- [Agent integrations and workflow](Agent-Workflow)
 - [Parallel agents and conflict resolution](Parallel-Agents-and-Conflicts)

 ## Reference and operations
@@ -36,9 +36,10 @@ Windows PowerShell:
 irm https://githop.xyz/GnosysLabs/Hop/raw/branch/main/scripts/install.ps1 | iex
 ```

-Restart Codex Desktop, open a Git project, and ask Codex to work normally. The
-installed skill activates Hop before the agent inspects or changes the project;
-there is no separate prompt router and no required manual `hop init` step.
+Open a Git project in a compatible agent client and work normally. The installed
+skill bundle activates Hop before the agent inspects or changes the project;
+controllers can invoke the same protocol directly. Codex Desktop is a bundled
+integration, and there is no required manual `hop init` step.

 Hop is currently an alpha. Keep Git history and normal backups, read release
 notes before upgrading, and report unexpected behavior with `hop doctor` output
@@ -16,7 +16,11 @@ The installer:
 3. downloads `checksums.txt` and verifies SHA-256 before extraction;
 4. installs the CLI to `~/.local/bin/hop`;
 5. adds `~/.local/bin` to `.zprofile` or `.profile` when necessary; and
-6. runs `hop skill install --force` for Codex.
+6. runs `hop skill install --force` to install the bundled agent integration.
+
+The no-path skill command writes the same Hop-managed skill files to
+`~/.agents/skills/hop` and `${CODEX_HOME:-~/.codex}/skills/hop`. The second path
+supports Codex Desktop; compatible clients can use the shared `.agents` path.

 Review before execution:

@@ -32,7 +36,7 @@ Installer options are environment variables:
 |---|---|---|
 | `HOP_VERSION` | `latest` | Release tag such as `v0.1.0` |
 | `HOP_INSTALL_DIR` | `~/.local/bin` | Binary destination |
-| `HOP_INSTALL_SKILL` | `1` | Set to `0` to skip Codex skill installation |
+| `HOP_INSTALL_SKILL` | `1` | Set to `0` for a CLI-only or custom integration |
 | `HOP_MODIFY_PATH` | `1` | Set to `0` to leave shell profiles unchanged |
 | `HOP_GITEA_URL` | `https://githop.xyz` | Gitea instance base URL |
 | `HOP_REPOSITORY` | `GnosysLabs/Hop` | Alternate Gitea owner/repository |
@@ -52,15 +56,15 @@ irm https://githop.xyz/GnosysLabs/Hop/raw/branch/main/scripts/install.ps1 | iex
 ```

 The script verifies the Windows archive, installs to
-`%LOCALAPPDATA%\Programs\Hop`, updates the user PATH, and installs the Codex
-skill. To pin a version after downloading the script:
+`%LOCALAPPDATA%\Programs\Hop`, updates the user PATH, and installs the shared and
+Codex-compatible skill bundles. To pin a version after downloading the script:

 ```powershell
 .\install.ps1 -Version v0.1.0
 ```

-Use `-SkipSkill` only when another agent runtime will receive the skill. Use
-`-SkipPath` when another tool manages your PATH.
+Use `-SkipSkill` for a CLI-only or separately managed integration. Use `-SkipPath`
+when another tool manages your PATH.

 ## Go install

@@ -71,7 +75,8 @@ go install githop.xyz/GnosysLabs/Hop/cmd/hop@latest
 hop skill install --force
 ```

-Put `$(go env GOPATH)/bin` on PATH if `hop` is not found.
+Put `$(go env GOPATH)/bin` on PATH if `hop` is not found. The second command
+installs both default skill bundles; omit it for a CLI-only installation.

 ## Build from source

@@ -87,6 +92,12 @@ install -m 755 hop "$HOME/.local/bin/hop"

 Source builds are intended for contributors and as a pre-release fallback.

+To install only one compatible runtime target, pass its parent skills directory:
+
+```bash
+hop skill install --path /path/to/agent/skills --force
+```
+
 ## Verify

 ```bash
@@ -95,5 +106,5 @@ hop help
 git --version
 ```

-If Codex Desktop was open during installation, restart it. See
+Restart any agent client that was open while its skill bundle changed. See
 [Getting started](Getting-Started) next.
@@ -40,7 +40,8 @@ scripts/release-local.sh --snapshot

 Inspect `dist/` and test at least one archive on each operating system family.
 Confirm `hop version` reports the snapshot/tag-injected version and
-`hop skill install --force` installs usable skill files.
+`hop skill install --force` installs identical Hop-managed files at both
+default skill destinations while preserving unrelated user files.

 ## Create a release

@@ -13,14 +13,16 @@ printf '%s\n' "$PATH"
 The default Unix location is `~/.local/bin`. On Windows it is
 `%LOCALAPPDATA%\Programs\Hop`.

-## Codex does not activate Hop
+## An agent integration does not activate Hop

 ```bash
 hop skill install --force
 ```

-Restart Codex Desktop. Mention `$hop` in a task as a deterministic activation
-fallback.
+The command refreshes both default skill bundles. Restart the agent client. For
+Codex Desktop, mention `$hop` in a task as a deterministic activation fallback.
+For another compatible runtime, confirm that it reads `~/.agents/skills` or run
+`hop skill install --path /path/to/agent/skills --force`.

 ## The installer cannot find a release

@@ -55,7 +57,7 @@ workspace, and rerun the check.

 Hop found visible files or index state it will not overwrite. Preserve those
 changes. Capture them as a new Hop task or resolve them intentionally, then
-retry `hop land`. Do not bypass this with `hop accept` in Desktop workflows.
+retry `hop land`. Do not bypass this with `hop accept` in interactive workflows.

 ## Internal ref or object warning

@@ -2,7 +2,8 @@

 ## Upgrade packaged installations

-Rerun the installer. It replaces the binary and refreshes the embedded skill:
+Rerun the installer. It replaces the binary and refreshes both default skill
+bundles:

 ```bash
 curl -fsSL https://githop.xyz/GnosysLabs/Hop/raw/branch/main/scripts/install.sh | sh
@@ -31,7 +32,7 @@ hop skill install --force
 hop doctor
 ```

-Restart Codex Desktop when the installed skill changed.
+Restart any agent client whose installed skill changed.

 ## Upgrade Go installations

@@ -46,12 +47,13 @@ Hop opens and migrates older supported SQLite schemas automatically. Back up
 important repositories before alpha upgrades and read the release notes for any
 one-way schema change.

-## Uninstall the CLI and skill
+## Uninstall the CLI and skill bundles

 Unix default:

 ```bash
 rm -f "$HOME/.local/bin/hop"
+rm -rf "$HOME/.agents/skills/hop"
 rm -rf "${CODEX_HOME:-$HOME/.codex}/skills/hop"
 ```

@@ -59,9 +61,12 @@ Windows PowerShell:

 ```powershell
 Remove-Item -Force "$env:LOCALAPPDATA\Programs\Hop\hop.exe"
+Remove-Item -Recurse -Force "$HOME\.agents\skills\hop"
 Remove-Item -Recurse -Force "$HOME\.codex\skills\hop"
 ```

+If `CODEX_HOME` points somewhere else, remove its `skills\hop` directory instead
+of `$HOME\.codex\skills\hop`. Remove any explicit `--path` target manually.
 Remove the Hop install directory from PATH if it is no longer used.

 Uninstalling the program does not delete project-local `.hop/` histories. That