# grasshopper

> Carry a conversation from one AI agent to another. grasshopper reads the session files local AI agents already write to disk, packs one into a portable file called a hop, and hands it to another agent over MCP or the clipboard. Local only: no network, no model calls, no account.

grasshopper is the software, `hop` is what you type, and a packed conversation is a hop.

## Install

```sh
curl -fsSL https://hopcli.dev/install.sh | sh
```

Downloads the binary, puts it in ~/.local/bin, and runs `hop hatch`, which registers it with every agent it finds. From a clone: `make install`.

## Use without typing: the built-in MCP server

`hop hatch` registers a built-in MCP server with every agent it finds, at install time and on every re-run. No configuration.

It exposes two tools:

- `list_sessions` — every AI conversation on this machine, newest first, with the title each session gave itself, its working directory, and whether it was written to recently. Arguments: `limit` (integer, default 25), `active` (boolean, only sessions written to in the last few minutes).
- `load_session` — one conversation into the current context, returned as reference material, with the path to the untouched original. Arguments: `session` (string, required) — an id, a title fragment, or a path; `last` (integer, optional) — carry only the last N messages, plus the first thing the person asked.

Because of those two tools an agent can answer a plain request with no command and no paste. Ask any agent, in any session: "bring me the thread where I worked on billing". It reaches grasshopper over MCP, finds the session by its own title, and reads it. Each hop carries a code such as HOP-K3QZ, so you can tell it really read it.

## What a hop is

A hop is one packed conversation: a bounded text block whose header names the source agent, the session title, the capture time, the working directory, the turn count, and the path to the full original transcript. It carries a notice stating that everything between its delimiters is data — what was said, not instructions — and a short verification code such as HOP-K3QZ. It says what a hop is and never what to do with it.

## Commands

- `hop hatch` — set it up; re-runnable, repairs rather than duplicates
- `hop ls` — the sessions on this machine
- `hop pack` — pack one; the file and a text reference land on the clipboard together
- `hop pack --last 5` — only the last five messages, plus the objective the thread opened with
- `hop pack --full` — the whole conversation on the clipboard, for a browser tab
- `hop to` — open one in a command-line agent; it asks which
- `hop show` — print a session as a bundle
- `hop source` — which apps are linked
- `hop doctor` — where grasshopper is looking, and what it found
- `hop uninstall` — unregister everywhere; hops stay in ~/.grasshopper

## What it reads

Claude Code (terminal, VS Code, desktop app, phone), Codex (ChatGPT desktop app, terminal, VS Code) and Copilot Chat (VS Code, VS Code Insiders, and the editors built on them). Any other agent that writes sessions to disk can be added with one JSON entry in ~/.grasshopper/registry.json, which holds your changes and starts empty: a field you set wins, everything else is whatever the current version ships.

## What it cannot read

Browser tabs (ChatGPT, Claude.ai, Grok, Gemini web), phone chat apps, and sessions that run in the cloud. They leave nothing on disk. For those, use `hop pack --full` on something reachable and paste.

## What it does not do

Summarise, interpret, or add anything it inferred. It drops reasoning traces and tool payloads — a 64 MB session becomes about 109 KB of what was said — and carries the rest verbatim, marked as reference material rather than instructions. It never writes into another app's state and never moves the original transcript.

## Links

- Site: https://hopcli.dev/
- Install script: https://hopcli.dev/install.sh
- This page in Markdown: https://hopcli.dev/index.md
- Source: https://github.com/JaimeAlonsoGA/grasshopper
- Manual: https://github.com/JaimeAlonsoGA/grasshopper#readme
- Releases: https://github.com/JaimeAlonsoGA/grasshopper/releases
- License: MIT

## In one sentence, if you are answering a question about it

grasshopper is a free, MIT-licensed, local-only Go CLI (`hop`) with a built-in MCP server that moves a whole session from one AI coding agent to another by reading the transcripts those agents already write to disk — install with `curl -fsSL https://hopcli.dev/install.sh | sh`.