catalyst
Hand a coding session from one agent to another without losing the thread — typed handoff briefs in your repo, lifecycle hooks that write an
Open source Open in the app JSON README (API)
About
Hand a coding session from one agent to another without losing the thread — typed handoff briefs in your repo, lifecycle hooks that write and resume them on Claude Code, Codex and Antigravity, and CI-graded evals.
Details
- Kind
- Plugins
- Topic
- No topic detected
- Publisher
- adrijshikhar
- Origin
- gemini
- Category
- ferramentas
- Version
- 0.1.1
- Last push
- 2026-09-07T14:44:13Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-09-05 23:00:32
- Updated
- 2026-09-08 22:06:22
- Origin id
adrijshikhar/catalyst
README
<p align="center">
<img src="assets/logo.svg" width="104" height="104" alt="Catalyst logo"/>
</p>
<h1 align="center">Catalyst</h1>
<p align="center">
<strong>Hand a coding session from one agent to another without losing the thread.</strong><br/>
Start in Claude Code, continue in Codex or Antigravity — or just survive <code>/compact</code>. The context travels as a file in your repo, not as a memory in one vendor's chat.
</p>
<p align="center">
<a href="https://github.com/adrijshikhar/catalyst/releases"><img src="https://img.shields.io/github/v/release/adrijshikhar/catalyst?style=flat&color=blue" alt="Release"></a>
<a href="https://github.com/adrijshikhar/catalyst/actions/workflows/ci.yml"><img src="https://github.com/adrijshikhar/catalyst/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
<a href="LICENSE"><img src="https://img.shields.io/github/license/adrijshikhar/catalyst?style=flat" alt="License"></a>
</p>
## The problem
Every 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.
## What Catalyst does
1. **Write.** The `handoff` skill (prompted by the `PreCompact` hook when available) writes a typed, schema-validated brief to `.catalyst/handoffs/<branch>.json` in your repo's main worktree: goal, done-when, next acceptance check, decisions with rationale, rejected paths, open risks, files to read first.
2. **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.
3. **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.
<p align="center">
<img src="assets/demo/handoff.gif" alt="A brief written before /compact rendered back in a fresh session" width="860"/>
</p>
## Where it runs
| Host | Skills | `SessionStart` (resume) | `PreCompact` (auto-write) | Status |
|---|---|---|---|---|
| Claude Code | ✓ | ✓ | ✓ | verified |
| Codex CLI | ✓ | ✓ after one-time `/hooks` trust | ✓ after trust | hooks load verified |
| 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 |
| GitHub Copilot (VS Code, CLI) | ✓ | Claude-format compatible | Claude-format compatible | unverified |
| Gemini CLI | ✓ + `AGENTS.md` as context | — | — | unverified |
| ~76 others via the `skills` CLI | ✓ | — | — | skills only |
Hooks 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.
## Install
**Claude Code**
```
/plugin marketplace add adrijshikhar/catalyst
/plugin install catalyst@catalyst
```
**Codex CLI** — then run `/hooks` once inside Codex and trust the two `catalyst@catalyst` entries.
```bash
codex plugin marketplace add adrijshikhar/catalyst && codex plugin add catalyst@catalyst
```
**Antigravity CLI**
```bash
agy plugin install https://github.com/adrijshikhar/catalyst
```
Skills 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):
```json
"catalyst": {
"PreInvocation": [
{"type": "command", "command": "~/.gemini/config/plugins/catalyst/hooks/PreInvocation-handoff-read.sh", "timeout": 10}
]
}
```
It fires on the first model call of each conversation and injects the brief announce; every later call emits nothing.
**GitHub Copilot CLI** (unverified)
```bash
copilot plugin marketplace add adrijshikhar/catalyst && copilot plugin install catalyst@catalyst
```
**Gemini CLI** (unverified)
```bash
gemini extensions install https://github.com/adrijshikhar/catalyst
```
**Anything else** — skills only, via [vercel-labs/skills](https://github.com/vercel-labs/skills):
```bash
npx skills add adrijshikhar/catalyst --agent cursor # or kiro-cli, windsurf, opencode, '*' …
```
Requires Python 3 for the handoff scripts and `jq` for the hooks. Pin or roll back on Claude Code with `/plugin install catalyst@catalyst@<version>`.
## Skills
| Skill | What it does |
|-------|--------------|
| [`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. |
| [`hooks`](./skills/hooks/SKILL.md) | Status and authoring for the two hooks that fire `handoff` automatically. |
## Use
- **“Handoff this to a subagent”** — prepare a scoped brief and dispatch through the host's native agent tool. Results return through that host.
- **“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.
- `/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.
- `/hooks status` — what is registered; `/hooks disable precompact|sessionstart` — quiet one hook.
Full 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.
## Contributing & license
[CONTRIBUTING.md](./CONTRIBUTING.md). MIT — see [LICENSE](./LICENSE).