{ "markdown": "

\n \"Catalyst\n

\n\n

Catalyst

\n\n

\n Hand a coding session from one agent to another without losing the thread.
\n Start in Claude Code, continue in Codex or Antigravity — or just survive /compact. The context travels as a file in your repo, not as a memory in one vendor's chat.\n

\n\n

\n \"Release\"\n \"CI\"\n \"License\"\n

\n\n## The problem\n\nEvery long agent session ends the same way: `/compact`, a context limit, or you want a different model for the next step. The decisions, the rejected paths, what \"done\" means, the next check — gone, or re-explained from memory. And each vendor keeps that state in its own format, so switching agents means starting over.\n\n## What Catalyst does\n\n1. **Write.** The `handoff` skill (prompted by the `PreCompact` hook when available) writes a typed, schema-validated brief to `.catalyst/handoffs/.json` in your repo's main worktree: goal, done-when, next acceptance check, decisions with rationale, rejected paths, open risks, files to read first.\n2. **Switch.** Open the same repo in any agent that has Catalyst installed. The brief is plain JSON in your tree; it does not care who wrote it.\n3. **Resume.** The `SessionStart` hook renders the brief back into the new session on Claude Code and Codex; on Antigravity a `PreInvocation` adapter does the same on the first model call once registered (see install). Anywhere else, say `handoff resume`. Drift guards refuse a brief from another branch or repo and flag a stale one.\n\n

\n \"A\n

\n\n## Where it runs\n\n| Host | Skills | `SessionStart` (resume) | `PreCompact` (auto-write) | Status |\n|---|---|---|---|---|\n| Claude Code | ✓ | ✓ | ✓ | verified |\n| Codex CLI | ✓ | ✓ after one-time `/hooks` trust | ✓ after trust | hooks load verified |\n| Antigravity CLI | ✓ (+ commands as skills) | ✓ after a one-time `~/.gemini/config/hooks.json` entry (`PreInvocation`, first model call) | no compaction event | verified on agy 1.1.27 |\n| GitHub Copilot (VS Code, CLI) | ✓ | Claude-format compatible | Claude-format compatible | unverified |\n| Gemini CLI | ✓ + `AGENTS.md` as context | — | — | unverified |\n| ~76 others via the `skills` CLI | ✓ | — | — | skills only |\n\nHooks never block anything and fail open; they only inject context. Before writing, Catalyst adds `.catalyst/` to the main worktree's `.gitignore` if needed. Outside Git, it creates no ignore file. Legacy `.claude/handoffs/` briefs remain readable; new writes use `.catalyst/handoffs/`. Transfer the file explicitly if the next agent runs on another machine.\n\n## Install\n\n**Claude Code**\n```\n/plugin marketplace add adrijshikhar/catalyst\n/plugin install catalyst@catalyst\n```\n\n**Codex CLI** — then run `/hooks` once inside Codex and trust the two `catalyst@catalyst` entries.\n```bash\ncodex plugin marketplace add adrijshikhar/catalyst && codex plugin add catalyst@catalyst\n```\n\n**Antigravity CLI**\n```bash\nagy plugin install https://github.com/adrijshikhar/catalyst\n```\nSkills load immediately. For the resume hook, add this once to `~/.gemini/config/hooks.json` (agy 1.1.27 parses a plugin's `hooks.json` but only executes hooks declared at user or workspace level):\n```json\n\"catalyst\": {\n \"PreInvocation\": [\n {\"type\": \"command\", \"command\": \"~/.gemini/config/plugins/catalyst/hooks/PreInvocation-handoff-read.sh\", \"timeout\": 10}\n ]\n}\n```\nIt fires on the first model call of each conversation and injects the brief announce; every later call emits nothing.\n\n**GitHub Copilot CLI** (unverified)\n```bash\ncopilot plugin marketplace add adrijshikhar/catalyst && copilot plugin install catalyst@catalyst\n```\n\n**Gemini CLI** (unverified)\n```bash\ngemini extensions install https://github.com/adrijshikhar/catalyst\n```\n\n**Anything else** — skills only, via [vercel-labs/skills](https://github.com/vercel-labs/skills):\n```bash\nnpx skills add adrijshikhar/catalyst --agent cursor # or kiro-cli, windsurf, opencode, '*' …\n```\n\nRequires Python 3 for the handoff scripts and `jq` for the hooks. Pin or roll back on Claude Code with `/plugin install catalyst@catalyst@`.\n\n## Skills\n\n| Skill | What it does |\n|-------|--------------|\n| [`handoff`](./skills/handoff/SKILL.md) | WRITE / READ / RECOVER / REGROUND / BRIEF. Typed session checkpoints, native subagent dispatch, external task files with completion sections, shared worktree-aware storage and drift guards. |\n| [`hooks`](./skills/hooks/SKILL.md) | Status and authoring for the two hooks that fire `handoff` automatically. |\n\n## Use\n\n- **“Handoff this to a subagent”** — prepare a scoped brief and dispatch through the host's native agent tool. Results return through that host.\n- **“Handoff this to Codex”** — create a self-contained task file under `.catalyst/tasks/` and a short launch prompt to copy. Choose a separate worktree/branch (recommended) or the current workspace for coding. The recipient needs no Catalyst installation, updates the file's Completion section and returns a short pointer for you to relay. Full inline output requires an explicit request.\n\n- `/handoff` — write a brief for the current branch; `/handoff resume` — render it; `/handoff reground` — re-inject the goal mid-session; `/handoff list` / `prune` — manage the store. Slash commands are Claude Code only; elsewhere ask for the `handoff` skill by name.\n- `/hooks status` — what is registered; `/hooks disable precompact|sessionstart` — quiet one hook.\n\nFull brief anatomy, design principles and the host matrix in depth: **[docs/HARNESS.md](./docs/HARNESS.md)**. Grounded in Anthropic's [harness engineering](https://www.anthropic.com/engineering/harness-design-long-running-apps) patterns.\n\n## Contributing & license\n\n[CONTRIBUTING.md](./CONTRIBUTING.md). MIT — see [LICENSE](./LICENSE).\n", "bytes": 6439, "sha": "cb6b92ca6a606d9629ab3245ad256d8030ee76ff21bb89b3098372b34ce9c6d3", "repo_slug": "adrijshikhar/catalyst", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/plg_adrijshikhar_catalyst_a62a0702/readme" }