diff --git a/Agent-Workflow.md b/Agent-Workflow.md index ac81245..048e8f1 100644 --- a/Agent-Workflow.md +++ b/Agent-Workflow.md @@ -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' HOP_PROMPT_EOF ``` +In PowerShell: + +```powershell +$hopPrompt = @' + +'@ +$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 diff --git a/Architecture.md b/Architecture.md index c871df0..c80e00b 100644 --- a/Architecture.md +++ b/Architecture.md @@ -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). diff --git a/CLI-Reference.md b/CLI-Reference.md index 962edd6..21267c6 100644 --- a/CLI-Reference.md +++ b/CLI-Reference.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 diff --git a/Core-Concepts.md b/Core-Concepts.md index 77fe933..4e53f31 100644 --- a/Core-Concepts.md +++ b/Core-Concepts.md @@ -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. diff --git a/Getting-Started.md b/Getting-Started.md index 9839a47..62cd559 100644 --- a/Getting-Started.md +++ b/Getting-Started.md @@ -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 diff --git a/Home.md b/Home.md index 17a24af..3d8b554 100644 --- a/Home.md +++ b/Home.md @@ -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 diff --git a/Installation.md b/Installation.md index 6b77af9..dc592f1 100644 --- a/Installation.md +++ b/Installation.md @@ -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. diff --git a/Release-Checklist.md b/Release-Checklist.md index cda5c9d..78126d7 100644 --- a/Release-Checklist.md +++ b/Release-Checklist.md @@ -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 diff --git a/Troubleshooting.md b/Troubleshooting.md index cd4588e..72f16dd 100644 --- a/Troubleshooting.md +++ b/Troubleshooting.md @@ -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 diff --git a/Upgrading-and-Uninstalling.md b/Upgrading-and-Uninstalling.md index a931fe6..83feeb7 100644 --- a/Upgrading-and-Uninstalling.md +++ b/Upgrading-and-Uninstalling.md @@ -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