# Installing Grains

Grains is an AI co-pilot for Heads of Product. It runs entirely on your Mac — your conversations, files, and dashboard never leave your machine except to talk to Claude.

This guide gets you running in 5–10 minutes.

---

## What you'll need

| | Item | How to check |
|---|---|---|
| ✅ | macOS (Apple Silicon or Intel) | Should "just work" — any current Mac |
| ✅ | Terminal | Open the Terminal app (Cmd+Space → "Terminal") |
| ⚙️ | An Anthropic API key OR Claude Code installed and logged in | See "Authentication" below |

You do **not** need: Docker, Node.js, npm, Homebrew, Git, or any other tools. The installer handles everything else.

### Authentication — one of two paths

Grains talks to Claude through Anthropic. Pick the path that fits you:

**Path A — Claude Code login.** If you've already run `claude login`, Grains reuses your existing credentials. Nothing extra to set up. Skip to "Install".

**Path B — Anthropic API key.** Get one at [console.anthropic.com/settings/keys](https://console.anthropic.com/settings/keys). Keep it ready — you'll paste it during setup.

You can switch between A and B at any time from Settings inside the app.

---

## Install

Single command. Paste this into your terminal:

```bash
curl -fsSL https://www.pavelracu.com/grains/install | bash
```

What it does:
1. Downloads Grains to `~/grains/`
2. Installs Bun (the runtime) if you don't have it
3. Installs project dependencies
4. Prints a "done" message

Takes 2–4 minutes the first time, mostly waiting on the Bun install and `bun install`.

If you want to install somewhere else, set `GRAINS_INSTALL_DIR`:
```bash
curl -fsSL https://www.pavelracu.com/grains/install | GRAINS_INSTALL_DIR=~/work/grains bash
```

---

## Launch

The installer creates a native macOS application for you.

Open **Launchpad** or **Spotlight** (Cmd + Space) and search for **Grains**.
*(Or find it in `~/Applications/Grains.app`)*.

1. Double-click to open. The app will stay in your Dock while running.
2. It automatically opens `http://localhost:5181` in your browser.
3. When you're done, right-click the Grains icon in your Dock and select **Quit** to shut down the server.

---

## First launch — the setup wizard

The wizard fires automatically the first time you open Grains. Three steps:

### Step 1: Authentication

The wizard checks for Claude Code and an API key. You'll see green checkmarks next to whatever it found.

- **If you have Claude Code:** click "Use Claude Code login" → Continue.
- **If you don't:** click "Use an Anthropic API key", paste your key (starts with `sk-ant-…`), Continue.

### Step 2: Workspace folder

This is the folder Grains reads from for your file tree, dashboard scans, and chat default working directory. It's where Claude has filesystem context.

Pick anywhere — iCloud, Documents, a project repo, an empty folder you'll fill in. You can change it later from Settings.

### Step 3: Confirm

Review and click "Finish setup". The app reloads with the dashboard.

---

## What you should see after setup

- **Docs panel** (left) — your workspace folder
- **Dashboard** (center) — greeting + segment tabs (Decide / Chase / Do / Snoozed / Resolved), empty until your first scan
- **Composer** (top) — write a message to Claude (Chat mode) or capture a note (Note mode)

If the dashboard is empty, click **"scan now"** under the composer to surface open threads from your sources (Linear, Notion, files, recent chats). The first scan takes 20–60 seconds.

---

## If something goes wrong

### "command not found: bun" after the install

The installer added Bun to your shell config but the current terminal hasn't picked it up. Close the terminal and open a new one.

### Browser shows "This site can't be reached"

If the app isn't starting:
1. Open Terminal.
2. Run `cd ~/grains && bun start` directly to see any error output.
3. Check if port 5181 is in use: `lsof -ti:5181 | xargs kill`

If the UI fails to connect to Claude:
- **Permission errors writing to `~/.claude/...`** — make sure the folder is writable: `ls -la ~/.claude`.

### "Claude Code native binary not found" when you chat

You picked the OAuth path but Claude Code isn't installed. Open Settings → Authentication → switch to API key (and paste one), or install Claude Code first: [docs.anthropic.com/claude-code/quickstart](https://docs.anthropic.com/en/docs/claude-code/quickstart).

### "Authentication failed" in chat

Your API key may have been rejected. Open Settings → Authentication → paste the key again. If it still fails, verify it works at [console.anthropic.com/settings/keys](https://console.anthropic.com/settings/keys).

### Setup wizard won't show even though I'm new

```bash
rm ~/.claude/projects/-Users-$(whoami)/memory/settings.json
```
Then reload the browser. (This deletes only the Grains-specific settings file — your Claude Code data is untouched.)

### Activity shows duplicates / lots of dead items

```bash
cd ~/grains
bun run scripts/cleanup-chats.ts          # dry run, shows what would be archived
bun run scripts/cleanup-chats.ts --apply  # commits the archive
```

---

## What Grains stores on your machine

| Where | What |
|---|---|
| `~/.claude/projects/-Users-[you]/memory/settings.json` | Grains settings (workspace, auth, API key if you chose that) |
| `~/.claude/projects/-Users-[you]/memory/*.json/*.md` | postpones, resolutions, thread chats, scan cache, check verdicts |
| `~/.claude/projects/-Users-[you]/*.jsonl` | Every chat, one file per session |
| `~/grains/` (or your custom dir) | The Grains app itself |

Nothing else leaves your machine automatically. See `docs/privacy.md` (in the install directory) for the full data flow.

---

## Updating

When a new release ships:

```bash
rm -rf ~/grains
rm -rf ~/Applications/Grains.app
curl -fsSL https://www.pavelracu.com/grains/install | bash
```

Your settings persist in `~/.claude/...` and survive reinstalls. You don't go through the wizard again.

---

## Uninstalling

```bash
# 1. Stop the server (Ctrl+C in the terminal where it's running)

# 2. Remove the app
rm -rf ~/grains

# 3. (Optional) Remove Grains's settings
rm ~/.claude/projects/-Users-$(whoami)/memory/settings.json
```

Your Claude Code data and chats in `~/.claude/` are not touched.

---

## Getting help

Found a bug or have a question? In the app: **Settings → Report an issue** (opens a pre-filled report). Or message Pavel directly.
