Grasshopper
Memory for your coding agents. Tell one agent something once, and Codex, Cursor
and Claude Code all remember it, on every machine. One private server holds the
memories; you can see, fix or archive anything they keep.
The guided setup is at usegrasshopper.com/setup.
1. Start your server
Already have one? Skip to Connect an agent.
Download a server archive
(darwin-arm64, windows-amd64 or linux-amd64), check it against
SHA256SUMS, extract it, and run:
./bin/grasshopper-server --quickstart
On Windows: .\bin\grasshopper-server.exe --quickstart
Quickstart creates an empty database and an owner token, and never overwrites
existing state. It prints the memory view address and where the token is. Leave
it running and sign in to the memory view with that token.
To use it from other machines, put it behind a private HTTPS proxy (such as
Tailscale Serve forwarding
to http://127.0.0.1:8106, public access off) and restart with:
./bin/grasshopper-server --quickstart --allowed-proxy-host your-server.tailnet.ts.net:443
Operations covers running it as a service, unsigned
archives, building from source and token recovery.
Connect an agent
Install a connector on each machine. Every machine uses the same server.
2. Install a connector
Use grasshopper-macos, grasshopper-windows or grasshopper-linux to match
the machine.
Codex
codex plugin marketplace add MylesMCook/grasshopper --ref marketplace
codex plugin add grasshopper-macos@grasshopper-marketplace
Cursor
agent plugin marketplace add https://github.com/MylesMCook/grasshopper.git --git-ref marketplace
Then install your entry from the Plugins menu (IDE: Customize → Plugins).
If you also use Claude Code, Cursor can import its Grasshopper plugin instead;
it appears in the Plugins menu as Imported. Keep only one copy.
Claude Code
claude plugin marketplace add MylesMCook/grasshopper#marketplace
claude plugin install grasshopper-macos@grasshopper-marketplace
Approve the three read tools the first time Claude Code asks. To pre-approve
them instead, use the client archive
in place of the two commands above (one route or the other, not both):
./bin/grasshopper connect --agents claude --url https://your-server.tailnet.ts.net
3. Connect once
In a new agent session, say Connect Grasshopper. Give it your server address
if asked, then open the approval link in your memory view, check the device and
code match, and approve. No token passes through the agent.
Codex may ask you to trust its hook and allow network access; Cursor may ask you
to turn on Grasshopper MCP. Start a new session afterwards. To check later, ask
the agent to check Grasshopper.
4. Try it
Ask the agent to remember a preference, start a new session, and ask about it.
Then find it in your memory view.
Use the memory view
Sign in on your server as the owner. The sidebar has New (what agents saved
that you have not kept yet; agents load it at startup only after you keep it.
Handoffs are the exception: the latest one loads without being kept),
All projects, your projects, Agents, Archived and Settings.
Add memory saves a rule of your own for a project or All projects. Open a
memory to edit it, change which project, device or OS it applies to, or archive it;
earlier versions stay in its history. Each project keeps only its
latest handoff, and older ones move to Archived. Projects change what you see,
not who can access it.
Update or remove a connector
Connector changes never delete memories on the server.
From 2.11.0, connectors update themselves. When an agent's session starts and
the server runs a newer release, its client downloads that release's client
archive in the background, checks it against SHA256SUMS, and every agent on
the machine uses it from the next session. Clients follow the server, so
upgrading or rolling back the server is the only update step. Run
grasshopper update to do it now. To turn it off on a machine, create an empty
updates-off file in the client folder next to the path that
grasshopper config-path prints.
Update a connector by hand only to move it to 2.11.0 the first time, or when
check asks. Run ./bin/grasshopper check from the client archive: it lists
each agent's connector, the client it runs, whether that matches the server,
and the exact step for any that are behind. It fails only when an agent points
at a Grasshopper program that no longer exists.
| Agent | Update | Remove |
|---|
| Codex | codex plugin marketplace upgrade grasshopper-marketplace, then codex plugin add your entry again | Remove the entry in the Codex plugin manager |
| Cursor | agent plugin marketplace remove grasshopper-marketplace, then agent plugin marketplace add https://github.com/MylesMCook/grasshopper.git --git-ref marketplace, then update your entry in the Plugins menu. Cursor pins the marketplace to one commit, so agent plugin marketplace update alone does not pick up a new release. An Imported copy updates with Claude Code | Run ./bin/grasshopper cursor remove from the client archive, then uninstall the plugin |
| Claude Code | claude plugin marketplace update grasshopper-marketplace, then claude plugin update your entry | claude plugin uninstall your entry, then claude plugin marketplace remove grasshopper-marketplace |
| Claude Code (client archive) | ./bin/grasshopper setup --agents claude --update | ./bin/grasshopper claude remove, then remove the plugin |
You can disconnect one device in the memory view without affecting others. A
device token can read the whole store; project scope is not access control.
Back up and update the server
Before replacing a server, run the backup tool from the new server archive
and keep an encrypted copy off the machine:
./bin/grasshopper-backup --quickstart
./bin/grasshopper-backup --verify /absolute/path/to/backup.db
On macOS with launchd, ./bin/grasshopper-server upgrade
does the backup, the switch and a rollback on failure in one step (details). Otherwise, stop
the old server, keep its archive and database, and never run two servers on one
database. Operations covers
restoring a backup, rolling back and the one-time re-embedding when upgrading
from 2.3.x or earlier.
Develop
go test ./...
go vet ./...
node --test internal/service/visualizer/app.test.cjs web/*.test.cjs
AGENTS.md has the layout and project rules, and
DESIGN.md the visual system. Verification
lists what has been checked on real machines. The
shared memory policy governs all three agents.
Report security concerns privately,
not in a public issue.
