setup-catalyst git:20260824.3b80357B

Immutable. This exact content is served forever at /api/v1/blob/9e83a934f0c530ea.

---
name: setup-catalyst
description: "Diagnose and fix Catalyst setup issues. Validates tools, database, config, OTel, direnv, and thoughts. Automatically fixes what it can — creates directories, initializes the database, sets WAL mode, runs migrations. Use for new installs, upgrades, or when something isn't working."
---

# Setup Catalyst

Diagnose the full Catalyst environment, fix everything fixable, and verify the fixes worked.

## Phase 1: Diagnose

Locate and run the health check script:

```bash
# Backing scripts live in catalyst-dev (the shared framework core). Resolve them
# (and fail fast with a clear message if catalyst-dev is not installed).
source "${CLAUDE_PLUGIN_ROOT:-plugins/foundry}/scripts/require-catalyst-dev.sh" \
    "${CLAUDE_PLUGIN_ROOT:-plugins/foundry}" || exit 1
SCRIPT="${CATALYST_DEV_SCRIPTS}/check-setup.sh"

bash "$SCRIPT" 2>&1 || true
```

Parse the output. Categorize every warning and failure into:

- **Auto-fixable** — can be fixed right now without user input
- **Needs user input** — requires API tokens, credentials, or decisions
- **Manual only** — requires tool installation or external action

## Phase 2: Fix

For auto-fixable issues, fix them immediately — don't ask, just do it. These are safe, local,
reversible operations.

**Exception: thoughts/ repair is NOT a bare `mkdir`.** The humanlayer thoughts system expects
`thoughts/shared` and `thoughts/global` to be **symlinks** into a central thoughts repo. A bare
`mkdir` over a clobbered symlink silently routes all subsequent agent writes to a non-syncing
local directory. Always route thoughts repair through `catalyst-thoughts.sh`, and treat a
regular-directory-where-a-symlink-should-be as **fatal** — surface the recovery command to the
user rather than overwriting anything.

| Issue | Fix |
|-------|-----|
| `~/catalyst/` missing | `mkdir -p ~/catalyst/{wt,events,history}` |
| `~/catalyst/wt/` missing | `mkdir -p ~/catalyst/wt` |
| `~/catalyst/events/` missing | `mkdir -p ~/catalyst/events` |
| Database missing or schema incomplete | Run `catalyst-db.sh init` (locating it the same way as the check script) |
| `schema_migrations` table missing | Run `catalyst-db.sh init` — it's idempotent |
| WAL mode not set | `sqlite3 ~/catalyst/catalyst.db 'PRAGMA journal_mode=WAL;'` |
| `thoughts/shared/<dir>` missing | Run `bash plugins/dev/scripts/catalyst-thoughts.sh init-or-repair` (re-uses humanlayer when configured; warns loudly when no thoughts repo is set up) |
| `~/.catalyst/bin/` missing OR any catalyst-* symlink absent/broken | Run `bash plugins/dev/scripts/install-cli.sh` — idempotent, safe to re-run. If `$HOME/.catalyst/bin` is not on `$PATH`, the script prints the exact line to add to `~/.zshrc` or `~/.bashrc` — relay that to the user so they can finish the one-time PATH setup. |
| `thoughts/shared` is a regular directory (not a symlink) | **Fatal — do not auto-fix.** Tell the user the humanlayer symlink was clobbered and show recovery: `mv thoughts/shared thoughts/shared.orphaned-$(date +%Y%m%d)` then `bash plugins/dev/scripts/catalyst-thoughts.sh init-or-repair` |
| Drift detected: keys present in `plugins/dev/templates/config.template.json` but missing from `.catalyst/config.json` (CTL-489) | Enumerate via `bash plugins/dev/scripts/check-config-drift.sh --json`. Generate a preview merge to a temp file via `--merge-into /tmp/merged.json` and show the user `diff -u .catalyst/config.json /tmp/merged.json`. On user confirmation, `jq` deep-merge into the real file: `bash plugins/dev/scripts/check-config-drift.sh --merge-into .catalyst/config.json.new && mv .catalyst/config.json.new .catalyst/config.json`. Merge preserves every existing user value (project on the right of jq's `*` recursive merge). |
| Profile drift between `.catalyst/config.json` and humanlayer mapping | Run `bash plugins/dev/scripts/catalyst-thoughts.sh init-or-repair` — it now auto-repairs drift by running `humanlayer thoughts uninit --force && humanlayer thoughts init --profile <config profile> --directory <config directory>`. (Plain `humanlayer thoughts init --force` does NOT update an existing repo→profile mapping, so the `uninit` step is required.) |
| Agent house-rules block (the "Working the Loop" reflexes) — run this **proactively every setup**, not only when check-project-setup.sh §9 flags it (§9 is skipped for a repo with no agent doc at all, so a doc-less repo would otherwise never be seeded) | From the project root run `bash "${CATALYST_DEV_SCRIPTS}/ensure-agent-house-rules.sh" --fix` (resolve `${CATALYST_DEV_SCRIPTS}` via the Phase-1 `require-catalyst-dev.sh` source — the plugin lives outside the consumer repo, so a repo-relative path won't exist). Idempotent and self-detecting: seeds the canonical block into the doc the driving agent loads (AGENTS.md when CLAUDE.md imports it, else CLAUDE.md), creates an `AGENTS.md` + thin `@AGENTS.md` bridge if the repo has neither, migrates a legacy block to sentinels, and re-syncs a stale one — a no-op when already current. Safe, local, reversible — this is the auto-seed that makes every enrolled repo carry the reflexes, so run it without asking. |
| Single-harness repo (missing `@AGENTS.md` bridge / non-portable skills) — run this **proactively every setup**, not only when check-project-setup.sh §10 flags it (§10 is a hot-path, TTL-gated warning, and a direct `catalyst-foundry:setup-catalyst` invocation for an upgrade never runs check-project-setup.sh at all, so relying on the §10 flag alone would silently skip the migration) | From the project root dry-run the classifier: `bash "${CATALYST_DEV_SCRIPTS}/migrate-dual-harness.sh" --repo . --quiet`, then act on its exit code **per the rc contract owned by the `catalyst-foundry:migrate-dual-harness` skill** (single source of truth — read that skill's Phase 2 table; do not rely on a copy here). In brief: rc `0` no-op; rc `10` apply `--fix` (idempotent, safe without asking); rc `11` **stop** and tell the user to run `/catalyst-foundry:migrate-dual-harness` (setup cannot auto-invoke it); rc `4` surface the stderr diagnostic verbatim and stop. Any drift between this summary and the owning skill: the owning skill wins. |

**Config-template drift (CTL-489).** When the template gains a key that an existing project's
`.catalyst/config.json` lacks (the original CTL-487 silent-fallback bug — catalyst itself ran in
`oneshot-legacy` for two months because `orchestration.dispatchMode` was absent), Phase 2 surfaces
a unified diff and asks for confirmation before merging. Concretely:

1. Run `bash plugins/dev/scripts/check-config-drift.sh --json --config .catalyst/config.json
   --template <template>` to enumerate missing leaves. The template path comes from
   `$CLAUDE_PLUGIN_ROOT/templates/config.template.json` in production, or
   `plugins/dev/templates/config.template.json` when dogfooding from the repo.
2. If the array is non-empty, generate a preview merge file via
   `bash plugins/dev/scripts/check-config-drift.sh --merge-into /tmp/merged.json` and show the user
   the unified diff: `diff -u .catalyst/config.json /tmp/merged.json`.
3. Ask: "Apply these template additions? [y/N]". Default is NO — drift is non-fatal and the
   warning will keep showing on subsequent workflow invocations until the user opts in.
4. On confirmation, write the merged file atomically to `.catalyst/config.json` (`mv` from a
   sibling `.tmp` file). The merge uses jq's `*` operator with the project on the right —
   existing values always win, missing keys are added.
5. The merge **never** overwrites existing user values. If the user has a custom
   `catalyst.filter.groqModel`, the template's default is NOT applied to that key.
6. If the user declines, leave `.catalyst/config.json` untouched. The drift warning continues to
   appear on subsequent workflow invocations, providing passive nagging until resolved.

**Linear bot user ID (CTL-550 / CTL-749 / CTL-549).** `catalyst.monitor.linear.botUserId` is the
Linear user UUID of the Catalyst app-actor — the "Linear for Agents" app identity that posts
comments *as the app* (installed by CTL-550). It is **required for the Linear app-actor comms
channel** — i.e. when the execution-core daemon mirrors phase-agent output to Linear and wakes on
human replies (CTL-550 / CTL-549 / CTL-749). It is the self-echo / loop-prevention guard for the
whole bidirectional channel. CTL-749 / CTL-549 built a channel where a human reply on a ticket
wakes a parked worker; without `botUserId` loaded, the system cannot tell the agent's *own*
comments and description-updates apart from a human's, so (a) the agent's own mirror comments get
written into the worker `inbox.jsonl` as if they were human input (noise / false "human replied"
signals), and (b) bot-authored issue events feed back into the event log as write loops. The
orch-monitor's Linear webhook handler suppresses bot-authored issue events using this value, and
the execution-core daemon uses it to filter the agent's self-echo from each worker's inbox.

This value is **workspace-specific** and is NOT shipped in the committed template
(`config.template.json` keeps it `null`). It is not secret — it appears on every comment the app
posts — but it must be obtained per workspace and written into Layer 1
`.catalyst/config.json → catalyst.monitor.linear.botUserId` (alongside the other `monitor.linear`
keys such as `teams` and `webhookSecretEnv`). To obtain it, query `viewer.id` with the app-actor
token (the app OAuth credentials live in Layer 2
`~/.config/catalyst/config-<projectKey>.json → catalyst.linear.agent.{clientId,clientSecret,accessToken}`):

```bash
TOKEN=$(jq -r '.catalyst.linear.agent.accessToken' ~/.config/catalyst/config-<projectKey>.json)
BOT_ID=$(curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"query{viewer{id name}}"}' | jq -r .data.viewer.id)
```

(Alternatively, mint a fresh app token via `grant_type=client_credentials` with `actor=app` and
`scope="app:mentionable,app:assignable"` at `POST https://api.linear.app/oauth/token`, then run the
same `viewer{id}` query.) Write `$BOT_ID` into
`.catalyst/config.json → catalyst.monitor.linear.botUserId`. Both the monitor and the daemon read
`botUserId` **only at startup**, so after setting it you must restart them:
`catalyst-monitor stop && catalyst-monitor start`, then `catalyst-execution-core restart`. This is
a needs-user-input step (it requires the app-actor credentials), not an auto-fix — never write the
value for the user without confirming it came from their own app-actor token.

**Non-interactive / headless mode (CTL-842).** `setup-catalyst.sh` can run without a
controlling terminal — CI pipelines, SSH exec, cron, and `curl | bash` via `curl … | bash -s --
--non-interactive`. Three flags activate the mode:

- `--non-interactive` or `--defaults` CLI flags (both identical)
- `CATALYST_AUTONOMOUS=1` environment variable (set by execution-core workers)

In this mode:

- `ask_yes_no` returns the default answer without reading stdin; a 3rd argument overrides the NI
  answer (install-offer sites pass `"n"` so they silently decline in CI).
- `prompt_value` echoes the default to stderr and returns it without consuming stdin.
- Install offers (`npm install -g humanlayer`, `brew install jq`, etc.) are declined automatically.
- The Linear config step is skipped when no token is discoverable from the environment or standard
  config paths (`~/.config/catalyst/`, `~/.config/humanlayer/`). Prints: `Skipping Linear
  (non-interactive, no token discoverable)`.
- The Sentry, PostHog, and Exa config steps are skipped unconditionally in NI mode.
- When multiple Linear teams or Sentry orgs/projects are found, the first entry is auto-selected
  with a printed notice — no prompt.

The tty redirect (`exec </dev/tty`) runs only in interactive mode and only when `can_open_tty`
confirms the device is actually openable (subshell probe: `(: </dev/tty) 2>/dev/null`). This
prevents ENXIO crashes on PTY-less CI runners where `/dev/tty` exists as a device node but is
not attached to a session.

The source guard (`if ! (return 0 2>/dev/null); then main "$@"; fi`) replaces the old
`BASH_SOURCE[0]`-based check and works correctly in `curl | bash` pipelines where
`BASH_SOURCE[0]` is unset.

**Execution-core state contract (CTL-564).** `setup-catalyst.sh` runs an extra
step — `setup_execution_core_states` — right after the Linear workflow-state
fetch for every `--full` repo (CTL-722: not gated on `dispatchMode` any more).
That step delegates to the standalone
`plugins/dev/scripts/setup-execution-core-states.sh`, which ensures the team's
contract workflow states exist (`Todo` + `Research`, `Plan`, `Implement`,
`Validate`, `PR`; `Triage` already exists), writes the 10-phase → 5-state
collapse `stateMap` (idempotent — preserves user-customised maps), refreshes
`stateIds`, and upserts the team's entry in the central
`~/catalyst/execution-core/registry.json`. A Linear-permission failure in
the standalone script never aborts setup. The standalone script is also
idempotent and can be run directly per team (`setup-execution-core-states.sh
--config .catalyst/config.json [--dry-run] [--json]`).

**Linear git automations (CTL-759).** As its last Linear step,
`setup-execution-core-states.sh` reconciles the team's *git automations* —
Linear's built-in "move ticket on git event" rules. It pins exactly two
(`start` → `PR`, `merge` → `Done`) and deletes any `review` automation, so the
execution-core daemon stays the single authority on ticket state. The reconcile
is best-effort and tolerant: a Linear permission/transport failure prints a
WARNING and continues — it never aborts setup and never alters the script's exit
codes. `check-project-setup.sh` (hot path) warns on drift via a TTL-gated cached
read; a missing per-project token is a silent skip. Separately, Linear's
**branch-name "magic words" toggle** (Settings → Team → Workflow → Git) has no
API surface and **cannot** be reconciled — it must be turned OFF by hand, or it
races the daemon and re-introduces the CTL-758 backward state-write.

**Execution-core daemon env / proxy audit (machine-local, opt-in).**
`catalyst-execution-core start` sources a machine-local env file —
`~/.config/catalyst/execution-core.env` (override with `CATALYST_EXECUTION_CORE_ENV`)
— right before it launches the daemon, so every var it exports is inherited by the
daemon and every phase-agent bg job. An **absent file is a complete no-op** and is
the common case; this is **not** auto-fixable because the values (proxy port, MITM
CA path) are machine-specific. The committed template
`plugins/dev/templates/execution-core.env.example` documents every option. The two
uses are (1) routing the daemon's Linear/gh fetch traffic through a local mitmproxy
audit and (2) widening the Linear state-cache TTL (`LINEAR_STATE_CACHE_TTL_MS`).

The risk this guards against: a proxy that is configured but quietly broken silently
kills the daemon's Linear connectivity on a fresh or changed machine, with nothing
obvious to debug. So when the env file sets a proxy, `check-setup.sh` verifies it and
warns **loudly + actionably** on each failure mode — (a) the proxy port is not
listening, (b) `NODE_EXTRA_CA_CERTS` points at a missing file, or (c) `NODE_USE_ENV_PROXY=1`
is missing. The `NODE_USE_ENV_PROXY` flag matters because Node 20+/24+ native fetch
(undici) **ignores** `HTTPS_PROXY`/`HTTP_PROXY` without it — so the daemon's calls
would bypass the audit entirely while looking perfectly healthy. `check-project-setup.sh`
(the hot-path gate) carries only that one silent-bypass warning; full port/CA
diagnostics live in `check-setup.sh`. Treat any of these as **needs-user-input** — relay
the specific warning and fix, never write a machine path on the user's behalf, and
remind them to `catalyst-execution-core restart` after editing (the daemon re-sources
the file only on start/restart).

For issues needing user input, explain what's needed and how to provide it:

| Issue | What to tell the user |
|-------|----------------------|
| Linear API token not set | Show the secrets file path, explain where to get the token from Linear settings |
| No project config | Suggest running `setup-catalyst.sh` or offer to create a minimal `.catalyst/config.json` interactively |
| direnv not installed | Show `brew install direnv` and the shell hook setup |
| Linear "magic words" auto-move ON | Tell the user to turn it OFF in Settings → Team → Workflow → Git — it races the execution-core daemon and causes backward state writes (CTL-758). No API surface; must be toggled by hand. |
| Linear `review` git automation set | Run `setup-execution-core-states.sh` to remove it; the pipeline owns the Validate/review state, not Linear. |
| Personal git automations override team ones | Remind the user that Linear lets each member set *personal* git automations that shadow the team defaults — check Settings → Account → Git if drift persists after the team reconcile. |
| Proxy audit / daemon env wanted | Copy `plugins/dev/templates/execution-core.env.example` to `~/.config/catalyst/execution-core.env`, uncomment the vars you need (proxy + CA + `NODE_USE_ENV_PROXY=1`, and/or `LINEAR_STATE_CACHE_TTL_MS`), then `catalyst-execution-core restart`. **Needs user input, not auto-fix** — the proxy port and CA path are machine-specific. Never write machine paths for the user. |
| Daemon env proxy configured but broken | The check reports the exact failure: port not listening (start `mitmdump … --listen-port <port>` or unset the proxy), `NODE_EXTRA_CA_CERTS` missing (fix the path / re-run mitmproxy to regenerate its CA), or `NODE_USE_ENV_PROXY=1` missing (add it — without it Node fetch silently bypasses the audit). Relay the specific warning + fix; restart the daemon after. |

**Observability (OTel) is optional.** If Docker or OTel containers aren't found, note it as
informational — don't treat it as an issue. Point the user to
https://github.com/ryanrozich/claude-code-otel if they want to set it up.

## Phase 3: Verify

After fixing, run the health check script again (re-resolve, since each bash block
runs in a fresh shell):

```bash
source "${CLAUDE_PLUGIN_ROOT:-plugins/foundry}/scripts/require-catalyst-dev.sh" \
    "${CLAUDE_PLUGIN_ROOT:-plugins/foundry}" || exit 1
bash "${CATALYST_DEV_SCRIPTS}/check-setup.sh" 2>&1 || true
```

Re-run the drift check independently to confirm zero remaining drift (CTL-489):

```bash
bash plugins/dev/scripts/check-config-drift.sh \
  --config .catalyst/config.json \
  --template plugins/dev/templates/config.template.json
```

Compare the before/after results. Report:

1. What was fixed (with counts)
2. What still needs attention (with specific next steps)
3. Overall status

## Output Format

```
── Catalyst Setup ──────────────────────────────

[Phase 1 output from check-setup.sh]

── Fixing Issues ───────────────────────────────
  ✅ Created ~/catalyst/events/
  ✅ Initialized session database
  ✅ Set WAL mode
  ✅ Created thoughts/shared/reports/

── Config Drift ────────────────────────────────
Detected 2 missing template keys:
  • catalyst.orchestration.dispatchMode → "phase-agents"
  • catalyst.filter.groqModel → "llama-3.1-8b-instant"

Preview diff:
  --- .catalyst/config.json
  +++ /tmp/merged.json
  +    "orchestration": { "dispatchMode": "phase-agents" },
  +    "filter": { "groqModel": "llama-3.1-8b-instant" },

Apply these template additions? [y/N] y
  ✅ Merged 2 keys into .catalyst/config.json (existing values preserved)

── Verification ────────────────────────────────

[Phase 3 output from check-setup.sh]

── Summary ─────────────────────────────────────
Fixed 4 issues automatically.

Still needs attention:
  • Linear API token — add to ~/.config/catalyst/config-<project>.json
  • OTel stack — run: docker compose up -d
```

## Important

- **Always run the check script first** — don't guess what's wrong
- **Fix silently** — auto-fixable issues are safe operations, don't ask permission for mkdir or
  sqlite3 pragmas
- **Always verify after fixing** — run the check script a second time to confirm
- **Never touch secrets** — don't write API tokens or credentials, just tell the user where to put
  them
- **Idempotent** — safe to run multiple times, won't break anything that's already working