GitHop/wiki/Getting-Started.md

Getting started

Use Hop with an agent integration

1. Install Hop.
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 the agent to work inside .hop/workspaces. A Hop integration does that coordination for the agent.

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

Before reading or changing project files, the agent runs hop begin. Hop then:

• initializes local state without moving the Git branch or index;
• stores the prompt after redacting detected credentials;
• creates an isolated attempt workspace;
• returns the state and workspace to the agent; and
• keeps all project-changing work inside that workspace.

The agent validates, proposes, and lands the result. A successful hop land updates the visible project folder to the accepted tree.

Confirm the result

From the selected project directory:

hop status
hop history
hop doctor

A normal interactive result reports Root: synchronized.

Ask for review before landing

Automatic landing is the default because the original task authorizes the local code change. To stop at a proposal, say one of the following in the task:

• review first
• proposal only
• do not land

Connect another agent runtime

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

hop skill install --path /path/to/agent/skills --force

Controllers that can persist a prompt before model delivery should use hop start, hop env, and hop prompt; see Agent workflow.