# Squirrel: connect your agent

Squirrel gives an agent memory that outlives the session, and issues that put
work on a calendar. The `sq` CLI is the whole interface.

This page is only about connecting: install the CLI, log in, load the skill,
check that it works. The skill you load in step 3 is what says when to recall
and when to record, and this page does not repeat it.

| | |
|---|---|
| Server | `https://staging.sqmem.top` |
| Server version | `0.1.3` |
| This guide as Markdown | `https://staging.sqmem.top/start.md` |

**If you are an agent reading this page**, run the four steps below in order.
Step 1 installs a binary and step 2 needs the user at a browser: stop and ask
them before each. Steps 3 and 4 are safe to run on your own. No step here asks
you to handle a password or paste a secret — if one appears to, stop.

## 1. Install the CLI

Skip this if `sq version` already prints `sq 0.1.3`.

```bash
curl -fsSL https://staging.sqmem.top/install.sh | sh
```

On Windows, in PowerShell:

```powershell
irm https://staging.sqmem.top/install.ps1 | iex
```

The script picks the build for this platform, checks it against
`https://staging.sqmem.top/dl/sq/0.1.3/checksums.txt` and installs into
`~/.local/bin` on Linux and macOS, `%LOCALAPPDATA%\Programs\squirrel` on
Windows (`SQ_INSTALL_DIR` overrides either). It prints where it put the binary
and changes nothing else. To do the same by hand instead of piping a script
into a shell:

```bash
V=0.1.3; A=linux_amd64      # or linux_arm64, darwin_amd64, darwin_arm64
curl -fLO https://staging.sqmem.top/dl/sq/$V/sq_${V}_${A}.tar.gz
curl -fsSL https://staging.sqmem.top/dl/sq/$V/checksums.txt | grep "sq_${V}_${A}.tar.gz" | shasum -a 256 -c -
tar xzf sq_${V}_${A}.tar.gz sq && install -m 755 sq ~/.local/bin/sq
```

Nothing else is needed: no toolchain, no repository, no build step.

`sq` has to end up on PATH: the hooks in step 3 run it by name, and without
it they fail silently — the skill looks installed and simply never fires. The
script leaves PATH alone and prints the line to add if the directory is not on
it already. On Windows that line only reaches terminals opened afterwards, so
open a new one and check with `sq version` before moving on.

## 2. Log in

```bash
sq auth login --server https://staging.sqmem.top
```

The CLI prints a short code and a URL. The user approves that code from a
client they are already signed in to — the Squirrel app, say — or by opening
the URL in a browser and signing in (email and password, GitHub, Google or the identity provider). The CLI then receives its own
token, scoped to what it asked for. No password passes through the agent: if
that page asks for one, it is asking the user, so hand them the link and wait.

An agent with no user at a browser skips this step entirely and uses a token
instead — see the table in step 3.

`sq auth login --server https://staging.sqmem.top --oidc` uses the identity provider's own
device flow instead.

No account yet: the user creates one at https://staging.sqmem.top/signup, or `sq auth signup --email <email> --server https://staging.sqmem.top`.

Confirm with `sq auth whoami`.

## 3. Load the skill

The skill tells you *when* to recall and *when* to record. It is one Markdown
file, and the `sq` binary carries its own copy.

### Claude Code

```bash
sq skill install --hooks
```

That writes the skill to `~/.claude/skills/squirrel`, the `/checkpoint` command
to `~/.claude/commands`, and merges two hooks into `~/.claude/settings.json`:
`UserPromptSubmit` injects the context block on the first prompt of a session,
`Stop` asks for a checkpoint before a substantial session ends. Pass
`--dir .claude` for a project-level install instead. Restart Claude Code
afterwards.

### Any agent that can run a shell

Put the skill where your client reads persistent instructions:

```bash
sq skill print > <instructions file>                                    # from the binary
curl -fsSL https://staging.sqmem.top/skills/squirrel/SKILL.md -o <instructions file>  # or from this server
```

| Client | Where it goes |
|---|---|
| Codex | `AGENTS.md` in the repository, or `~/.codex/AGENTS.md` for every project |
| Cursor | `.cursor/rules/squirrel.mdc`, with `alwaysApply: true` in the frontmatter |
| Anything else | wherever that client loads instructions at the start of a session |

An agent running headless (no `sq auth login`) configures itself from the
environment instead of the config file:

| Variable | Value |
|---|---|
| `SQ_SERVER` | `https://staging.sqmem.top` |
| `SQ_TOKEN` | from `sq auth token create --name <agent> --agent <id> --scope issue:rw --scope memory:rw` |
| `SQ_RUN_ID` | optional; any per-session id, stamped on the events and memories you write |

Every command and flag: https://staging.sqmem.top/skills/squirrel/references/cli.md

## 4. Check that it works

```bash
sq context --task "connect this project to Squirrel"
sq memory add "This project uses Squirrel at https://staging.sqmem.top for memory and issues" -c environment
sq memory search "squirrel"
```

The first prints a context block, empty on a fresh account. If the third
returns what the second wrote, you are connected, and the skill takes over
from here.

`sq doctor` reports on all of it at once — the binary, PATH, the server, the
login, the skill and the hooks — and says what to do about anything it finds.
Run it if any of the three commands above behaves unexpectedly, or later if
Squirrel seems to have stopped participating.

## If one of these steps fails

- **`sq: command not found`** after step 1 — the install directory is not on
  PATH, or the terminal predates it being added. The installer printed the
  directory it used; add that one, open a new terminal, and confirm with
  `sq version`.
- **A command or flag does not exist** — your `sq` is older than this server
  (0.1.3). Reinstall with step 1.
- **`sq` runs but returns an error** — the skill covers what each failure
  means and which ones to work around, so read it rather than guessing here.
  Either way, tell the user once and carry on with the work they actually
  asked for: connecting Squirrel must not become the task.

## Removing it

Connecting is reversible, and leaving cleanly takes two commands:

```bash
sq uninstall          # prints what it would remove; add --yes to do it
```

That revokes this machine's credential on the server, then removes the skill,
the hooks, the config, the cache and the session markers, checking each path
afterwards and reporting what it finds. Then remove the binary with the same
script that installed it:

```bash
curl -fsSL https://staging.sqmem.top/install.sh | SQ_UNINSTALL=1 sh
```

```powershell
$env:SQ_UNINSTALL = 1; irm https://staging.sqmem.top/install.ps1 | iex
```

Run `sq uninstall` **before** removing the binary: the token in the config file
is a copy of one that lives on the server, so deleting the file on its own
leaves a working credential behind, and only `sq` can revoke it. Nothing on the
server is deleted either way — issues and memories stay, and logging in again
picks them up. `sq doctor` lists every path involved if you would rather remove
them yourself.

## Machine-readable

- `https://staging.sqmem.top/start.md` — this guide
- `https://staging.sqmem.top/llms.txt` — index
- `https://staging.sqmem.top/.well-known/squirrel` — version, auth methods and URLs, as JSON
  (`activate_url` is where step 2's code gets approved; `fallback_activate_url`
  appears when that is a separate web app, and is this server's own page)
- `https://staging.sqmem.top/skills/squirrel/SKILL.md` — the skill
- `https://staging.sqmem.top/dl/skill/squirrel.zip` — skill, `/checkpoint` command and hooks in one archive
- `https://staging.sqmem.top/install.sh`, `https://staging.sqmem.top/install.ps1` — the install scripts
- `https://staging.sqmem.top/dl/sq/0.1.3/` — the published archives and `checksums.txt`
- `https://staging.sqmem.top/dl/sq/latest/linux-amd64.tar.gz` — redirects to the current version