# Connecting a project to Catchup

**You install nothing.** No runtime, no model, no daemon, no background process. Catchup is a hosted MCP server plus one instruction file. Everything that thinks runs inside the agent you already pay for; everything that renders runs in the cloud.

Setup is two paste operations and takes under five minutes. (Prefer clicking through instead of
pasting into a file? The same three files below are also one link away at [/setup](/setup) on
the deployed app.)

---

## 1. Create the project, get a key

Sign in at [brainfeed-gamma.vercel.app](https://brainfeed-gamma.vercel.app), then **Create project** on the dashboard. Pick a name and a visibility.

**Visibility is chosen here and going public is a one-way door.** Private is the default and is almost always what you want to start with — content that has been public and indexed cannot be un-indexed, so the dashboard will not offer you a way back. Your git repository's visibility has nothing to do with this: a private repo can feed a public project, and a public repo does not make one.

The dashboard then shows your API key **exactly once**, along with the ready-to-paste command for step 2. There is no way to retrieve the key afterwards — only its hash is stored — so if you lose it, rotate it from the project page rather than hunting for it.

Put it somewhere your shell can read it and your git history can't:

```bash
echo 'CATCHUP_API_KEY=bf_...' >> .env
```

Confirm `.env` is gitignored before you do anything else:

```bash
git check-ignore .env && echo "safe"
```

## 2. Connect the agent

```bash
claude mcp add --transport http catchup https://brainfeed-gamma.vercel.app/api/mcp \
  --scope local \
  --header "Authorization: Bearer $CATCHUP_API_KEY"
```

**Use `--scope local`, not `--scope project`.** Project scope writes your key verbatim into `.mcp.json`, a file designed to be committed and shared with your team. Local scope keeps it in your own machine's config. If you already ran it at project scope, add `.mcp.json` to `.gitignore` before your next commit and rotate the key if it ever reached a remote.

Verify it connected:

```bash
claude mcp list | grep catchup
```

You should see `✔ Connected`. If you see a failure, the key is wrong — Claude Code does not fall back to another auth method once you've supplied an `Authorization` header, so a bad key reads as a connection error rather than a 401.

Other MCP-speaking agents work the same way; the server is not Claude-specific. Point them at the same URL with the same bearer header.

## 3. Install the skill

Fetch `SKILL.md` from the deployed app — the same origin as step 1, served straight from the
build rather than a directory only the person running the app has:

```bash
mkdir -p .claude/skills/catchup
curl -fsSL https://brainfeed-gamma.vercel.app/setup/SKILL.md -o .claude/skills/catchup/SKILL.md
```

The skill tells the agent how to distill a session: what to look at, how to cite it, what not to claim, and when the right answer is to write nothing at all. It runs in a forked context, so it doesn't consume the window you're actually coding in.

## 4. Capture at session end

Without this, distillation only happens when an agent happens to decide it should. That is the
same "nobody pulls the knowledge out" failure Catchup exists to fix, moved one layer down —
so this step is recommended, not optional.

Fetch the hook the same way and put it next to your settings:

```bash
mkdir -p .claude && curl -fsSL https://brainfeed-gamma.vercel.app/setup/session-end-hook.sh -o .claude/catchup-session-end.sh && chmod +x .claude/catchup-session-end.sh
```

Then wire it to the `Stop` event in `.claude/settings.json`:

```json
{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": ".claude/catchup-session-end.sh" }
        ]
      }
    ]
  }
}
```

**What it does:** when a session has produced new commits, it holds the session open and tells
the agent to run the skill before finishing. Not a printed reminder — the agent cannot end the
turn without addressing it.

**What it does not do**, which matters more:

- **Silent when nothing was committed.** A conversation, a question, a failed experiment —
  there is no durable knowledge there, and nagging about it is exactly the treadmill this
  product is supposed to avoid.
- **Silent in unrelated repos.** It only fires where Catchup is actually configured, so
  installing it globally does not make every project nag you.
- **Silent on its first run** in a repo. It records where history stands and says nothing,
  rather than demanding a capture of everything you have ever committed.
- **Never loops.** It respects `stop_hook_active`, and it advances its marker *before* holding
  the session open — so if an agent ignores it once, the next session starts clean rather than
  inheriting the debt. Anything genuinely missed resurfaces as a coverage gap in the
  generation brief.

The agent still judges what is worth capturing. The hook only guarantees it is asked.

---

## Checking it works

Ask your agent to run the Catchup skill after a real piece of work. It should call `catchup_get_generation_brief` first, then submit one or more items. Open your feed and swipe.

If it submits nothing and tells you so, that's correct behaviour — not every session produces something worth a card.

## What leaves your machine

Only what the agent chooses to send: short summaries, the reasoning behind a change, and the file paths and commit SHAs it cites. Code snippets travel only if your project's config allows them, and secrets are scrubbed twice — once by the skill before sending, once by the server before storing.

Your git repository's visibility is irrelevant to all of this. A private repo can feed a Catchup project; a public repo doesn't make one public. Visibility is a property of the Catchup project, chosen when you create it.

## Cost

Distillation runs on your own agent subscription, typically one to three thousand output tokens at the end of a session. The server does no model inference at all, so there is nothing metered on our side beyond storage and rendering.

If a session's distillation ever looks expensive, the daily item budget in the generation brief is the throttle — the agent reads it before generating and stops when it's spent.