# Geist: notes for coding agents

You are an agent (Claude Code or similar) and your user asked you to install
Geist, or to move their Claude Code setup into it. This page tells you how.
Do the steps one at a time and tell your user what you do.

## Status first

Geist 3.0 is out for macOS (Apple silicon), Linux (x86_64) and Windows (x64). The
apps are not signed yet: Homebrew and the install scripts clear what macOS and
Windows would otherwise block. The release files and their checksums are at
https://getgeist.dev/releases/latest.json and https://getgeist.dev/releases/<version>/SHA256SUMS.

## What Geist is

A desktop app (macOS, Linux, Windows) for long Claude Code sessions. A small
service, `geistd`, runs the sessions; the app shows them. One `geistd` runs on
each machine that does work: this computer and any Linux servers. The app talks
to all of them at once, and a project that lives on several machines (same git
remote) is one group in the left bar.

## Install on this computer

- macOS: `brew trust lixsldotnet/tap && brew install --cask lixsldotnet/tap/geist` (or the Linux line below)
- Linux and macOS: `curl -fsSL https://getgeist.dev/install.sh | sh`
- Windows (PowerShell): `irm https://getgeist.dev/install.ps1 | iex`

Then start Geist. On the first start it downloads its own pinned Claude Code
and opens a setup wizard. Your user does the login there: it needs their
browser and their Claude account. Never handle their password or tokens.

## Move an existing Claude Code setup in

Geist's Claude Code has its own config folder (under `~/.geist`), so a plain
`claude` in the terminal and Geist do not get in each other's way. To bring the
user's setup over:

1. In Geist: Settings (cog), section "Claude setup", "Import local Claude setup".
   It copies CLAUDE.md, skills, agents, commands, docs, hooks, plugins, MCP
   servers and memory from `~/.claude` of the same machine. The login, history
   and transcripts stay where they are. Importing again overwrites what Geist
   has.
2. Old terminal sessions: in a project folder, `geist --resume` lists the
   folder's `claude` sessions and opens one in Geist; `geist --continue` opens
   the newest. In the app: the project's "..." menu, "Resume a Claude Code
   session".
3. Projects: `geist <folder>` opens a folder as a project with a new session.

## Several machines

1. In Geist: the places list in the top bar, "Add a server". The wizard installs
   `geistd` over SSH with the user's SSH key (no passwords). The server must be
   Linux (x64 or arm64) with git; with systemd it keeps running as a service.
   A server that already runs `geistd` can be connected with its address and
   token instead.
2. Every place runs the same Claude account as this computer: sessions talk
   to each other through Claude, which needs one account. Geist hands this
   computer's account to each server, and a server logged in with another one
   starts no sessions; the places list says which account to log in with.
   Logins happen in one place: the usage panel in the top bar, "Accounts".
   Geist runs the login on each server and opens its sign-in page in this
   computer's browser; the user pastes the code it shows. Several accounts
   work the same way, and "Use" switches every machine at once. Import on a
   server reads that server's own `~/.claude`.
3. To give a server the same setup as this computer, copy the setup files to
   the server's `~/.claude` first (CLAUDE.md, `skills/`, `agents/`,
   `commands/`, `hooks/`, settings) and then import there. Ask your user before
   you copy anything. Never copy credentials (`.credentials.json`, keychain
   items, API keys in settings or MCP configs): the user logs in on each
   machine.
4. Clone the same repos on the servers. Projects with the same git remote are
   merged in the left bar; the `+` of a merged project asks on which machine a
   new session starts.

## A prompt your user can paste

```
Install Geist from https://getgeist.dev (read https://getgeist.dev/agents.md
first) on this computer. Then help me move my Claude Code setup into it: import
my ~/.claude, and list my recent terminal sessions in this folder so I can
resume them in Geist. If I name servers, add them as places and give them the
same setup, without copying any credentials. Ask me before each step that
changes something.
```