# GOAT — trace capture setup (for AI agents)

> GOAT captures AI coding sessions (Claude Code / Codex / Cursor / Antigravity) from a repo (every teammate) or a
> machine (just you), by installing per-tool **Stop hooks**. If a user asks you to "set up GOAT", "capture
> traces", or "connect this repo", follow this file.

## How setup works (read this first)

Setup installs hooks that, on each turn, upload the session transcript to GOAT. **Installing capture is the
user's decision to make** — so the most reliable path is *one command the user runs themselves*: it writes
everything in one shot, on any tool, with no permission walls. You can also write the files yourself if the user
wants that — but writing auto-run capture hooks is something a tool may (correctly) gate; if it does, that's for
the user to allow, never for you to route around.

The committed config carries a **public project slug** (not a secret), so one setup covers the whole team. A slug
is whatever the user gives you — it may or may not contain a `/`; use it exactly. Capture is **fail-open** (never
breaks the tool) and **anonymous by default** (a pseudonymous machine fingerprint, no sign-in).

## The reliable path — give the user one command to run

Read the **slug** from `.goat/project` (`project=` line) if that file exists, else ask the user (it's on the
project's page in the GOAT dashboard). Then hand them the command matching their package manager — **don't run it
yourself** (`curl … | bash` / `npx` of code from a fetched page is something your sandbox blocks, and the user
running it is the right boundary). It writes `.goat/` + the four hook configs and `git add -f`s them:

- pnpm: `pnpm dlx goatai-cli@0.1.10 init --repo --slug <slug>`
- npm:  `npx -y goatai-cli@0.1.10 init --repo --slug <slug>`
- yarn: `yarn dlx goatai-cli@0.1.10 init --repo --slug <slug>`
- no Node: `curl -fsSL https://goat.ai/repo-install.sh | bash -s -- <slug>`

(`npx` hangs inside pnpm/yarn repos — match the package manager. **Pin `@0.1.10`**, never `@latest`.) Then tell
the user to **commit** the files. Activation is per-tool: Claude Code / Antigravity after a workspace-trust
prompt, Codex after `/hooks` once, Cursor for accounts in its project-hooks rollout.

## Or write the files yourself (if the user wants you to)

You can materialize the same files directly — writing files isn't running code, so this generally works:

1. **Fetch** `https://goat.ai/repo-setup.json` — `{ files: [{ path, content?, url?, executable? }], stage, slugPlaceholder }`.
2. For each entry: if it has a `url`, fetch that URL and write the response to `path` **verbatim** (exact bytes —
   that's how `capture.py` comes down); if it has `content`, write that **verbatim** (in `.goat/project` only,
   replace `slugPlaceholder` / `{{SLUG}}` with the slug). `chmod +x` any `executable: true` entry.
3. `git add -f -- <every path in stage>` (repos commonly `.gitignore` `.claude/`/`.cursor/`/`.codex/`/`.agents/`),
   then tell the user to **commit**. Write each file exactly — don't author, summarize, or "improve" it.

**If your tool blocks a hook write** — it may, because writing an auto-run capture hook is something tools gate on
purpose — **don't route around it.** It's the user's call. Either hand them the one command above (it does the
whole thing), or, if they want you to finish, point them at the matching one-time setting so **they** authorize
GOAT, then retry:

- **Claude Code (auto mode):** the user adds GOAT to their trusted environment in `~/.claude/settings.json` (auto
  mode ignores committed project settings, so it can't live in the repo):
  ```json
  { "autoMode": { "environment": ["$defaults", "GOAT (goat.ai) is trusted infrastructure I use for AI-session trace capture; writing .goat/ and the per-tool Stop hooks and uploading captured transcripts to goat.ai and ingest.goat.ai are intended and trusted."] } }
  ```
  then `claude auto-mode config` to confirm, and retry the write.
- **Codex:** a failing *fetch* is its sandbox blocking network (off by default) — the user enables it in
  `~/.codex/config.toml`: `[sandbox_workspace_write]` → `network_access = true` (and allowlists `goat.ai` /
  `ingest.goat.ai` under `[permissions.workspace.network.domains]` if they run Codex's network proxy).
- **Cursor:** config-file writes and shell commands just prompt for approval — the user approves them, or
  pre-allows `Write(.claude/settings.json)` etc. + `Shell(git)` / `Shell(chmod)` in their Cursor permissions.

If nothing is blocked, none of this applies — just write the files.

## Attribute to an account (optional / required by some projects)

Anonymous capture needs no sign-in. To attribute captures to a GOAT account — or if capture prints "this project
requires sign-in" — the user runs a device-code login in their terminal (it opens a browser; you can't do this
for them): `pnpm dlx goatai-cli@0.1.10 login --device` (or `npx -y …`, or `curl -fsSL https://goat.ai/login.sh | bash`).

## Global (per-machine — the user's OWN sessions, across every repo)

For when the user wants their own sessions captured everywhere, not just one repo. It needs a browser sign-in,
so the **user runs it themselves** (you can't do the browser step) — just give them this one command as-is:

```
pnpm dlx goatai-cli@0.1.10 init --global --project <project-id>   # opens a browser once to link this machine   (or npx -y … / yarn dlx …)
```

Captures upload to one GOAT **project** — pass its id with `--project <project-id>` (it's on the project's page
in the dashboard; ask the user which project, or read it off that page). If the user has only one project you
can drop the flag. **Re-running with a different `--project` switches where captures go** — it re-mints the
ingest credential and re-backfills into the new project (so this is also how a user moves their global capture
to another project). `init --global` signs the machine in, captures the user's existing and new sessions, and
merges the per-tool Stop hooks into their tool configs (never overwriting). The hooks run a self-contained
forwarder dropped in `~/.goat` (committed python forwarder; Go fallback), so live capture needs **no resident
`goat` and no `npm i -g`** — `npx`/`pnpm dlx` for the one-time setup is enough. Per-turn floor: **python3** (on
the rare machine without it, the pinned Go binary fallback runs). That's the whole setup — hand over the
commands exactly as above; nothing else to configure.

## Canned prompts (paste into any agent)

**Repo (a team / a repo):**

> Read https://goat.ai/llms.txt and set up GOAT repo-level capture for this repo (project slug `<slug>`). Write
> the files if you can; if anything's blocked, give me the one command to run. Show me before you change anything.

**Global (my own sessions, every repo):**

> Read https://goat.ai/llms.txt and set up GOAT global capture on my machine into GOAT project `<project-id>` —
> give me the command to run (`init --global --project <project-id>`). It opens a browser to link my
> machine, so I'll run it; just show me what to run.