---
You know the ritual.
Claude has the entire problem in its head. It has read the repo, found the bug,
changed six files, failed one test, and finally understood why.
Then:
```text
You've hit your usage limit.
```
You open another agent. It cheerfully asks what you are working on.
Now **you** are the context window.
Elephant removes that part.
## Without / with Elephant
Without Elephant:
```text
Claude: You've hit your usage limit.
Codex: What would you like to work on?
You: Okay, so first you need to understand this 47-message conversation...
```
With Elephant:
```text
Claude: You've hit your usage limit.
[open the same repo in Codex]
Elephant: Recovered the previous Claude Code session.
Objective: fix refresh-token rotation.
State: implementation complete; one integration test still fails.
Changed: auth/session.py, tests/test_rotation.py
Codex: I found the failing test. Continuing from there.
```
The dead model does not need to summarize anything. Elephant was already
recording while it was alive.
## How it works
Elephant is a plugin, not another command you babysit.
```text
Every prompt, response, tool call, failure, and file change
│
▼
append-only local journal
│
completed turn / compaction /
interruption / quota failure
│
▼
recovery capsule
│
open the repo in another agent
│
▼
objective + state + Git evidence
```
It remembers:
- the current objective and last completed state;
- the last prompt and model response;
- modified files and live Git state;
- recent tool/model failures;
- the latest 20 session events;
- a redacted transcript reference when the host exposes one.
Every capture-capable native shell writes the same versioned event format. They
share `~/.elephant/elephant.db`, so Claude's memory is visible to Codex, Hermes,
Pi, OpenCode, Copilot, and every other Elephant adapter.
## Three layers
```text
┌──────────────────────────────────────────────────────────────┐
│ Native shells │
│ Claude · Codex · Hermes · OpenCode · Pi · Copilot · Gemini │
├──────────────────────────────────────────────────────────────┤
│ Elephant kernel │
│ redact · journal · checkpoint · inspect Git · build capsule │
├──────────────────────────────────────────────────────────────┤
│ Continuation │
│ automatic startup injection · Elephant Resume │
└──────────────────────────────────────────────────────────────┘
```
One memory format. Thin native adapters. No universal fake CLI pretending every
agent exposes the same API.
## Install
Install once in each harness you want to hand work between. Python 3.10+ must
be available as `python3` for the local kernel and lifecycle hooks.
### Claude Code
Send these as two separate prompts inside Claude Code:
```text
/plugin marketplace add vishesh9131/elephant
```
```text
/plugin install elephant@elephant
```
Elephant adds lifecycle capture, local MCP recovery tools, automatic startup
recovery, and namespaced commands such as `/elephant:memorize`,
`/elephant:resume`, and `/elephant:help`.
### Codex
```bash
codex plugin marketplace add vishesh9131/elephant
```
Open `/plugins`, choose the **Elephant** marketplace, and install Elephant.
Review and trust its local lifecycle hooks when Codex asks, then start a new
session.
### GitHub Copilot CLI
```bash
copilot plugin marketplace add vishesh9131/elephant
copilot plugin install elephant@elephant
```
The same commands work interactively with a `/` prefix. Elephant captures all
nine Copilot CLI plugin lifecycle events and provides the `resume` skill.
### Gemini CLI
```bash
gemini extensions install https://github.com/vishesh9131/elephant --ref=v0.4.5
```
Gemini loads Elephant's project context and `resume` skill. The public repo is
tagged for Gemini's extension gallery crawler.
### Pi
```bash
pi install git:github.com/vishesh9131/elephant@v0.4.5
```
Requires Node.js 22.19+. Pi loads the native JavaScript extension,
`/elephant `, `/resume`, and the Elephant skills.
### Hermes Agent
```bash
hermes plugins install vishesh9131/elephant --enable
```
Restart Hermes after installing. Elephant registers native lifecycle hooks, the
recovery tools, both Elephant skills, and `/elephant `.
Why `/elephant` instead of `/resume`? Hermes already owns `/resume`. The
elephant remembers names too.
### OpenCode
From a checkout, point your `opencode.json` at Elephant's JavaScript plugin:
```json
{
"plugin": ["/absolute/path/to/elephant/.opencode/plugins/elephant.mjs"]
}
```
The plugin captures prompts, responses, tool calls, compaction, idle, errors,
and session end. The npm package is prepared but not published yet.
## The rest of the herd
Not every harness exposes lifecycle hooks. Elephant says exactly what each one
can do instead of painting “98% quota used” on a guess.
| Harness | Support | Surface |
|---|---|---|
| Claude Code, Codex, Hermes, OpenCode, Pi | Native continuity | Hooks/extensions capture automatically and inject recovery |
| GitHub Copilot CLI | Native recovery | Marketplace plugin, nine hooks, MCP, and skill |
| Gemini / Antigravity, Qoder, Devin, Grok Build | Native recovery | Extension/plugin manifest plus recovery skill |
| OpenClaw, Swival | Native recovery | Packaged skill collection |
| Cursor | Portable recovery | [`.cursor/rules`](.cursor/rules) + Elephant MCP |
| Windsurf | Portable recovery | [`.windsurf/rules`](.windsurf/rules) + Elephant MCP |
| Cline | Portable recovery | [`.clinerules`](.clinerules) + Elephant MCP |
| Kiro | Portable recovery | [`.kiro/steering`](.kiro/steering) + Elephant MCP |
| CodeWhale, Amp, Jules, compatible hosts | Portable recovery | [`AGENTS.md`](AGENTS.md) |
See the [full platform matrix](docs/platform-native.md) for capability details
and current conformance status.
## What happens near quota?
Mostly, nothing special—and that is the point.
Most coding harnesses do **not** expose an exact subscription percentage.
Elephant never invents one. Quota signals are stored as `exact`, `estimated`,
or `unknown`.
Instead of gambling everything on a mythical “99% used” callback, Elephant:
1. journals continuously;
2. checkpoints after every completed model turn;
3. checkpoints again before compaction and at session end;
4. records native interruption and quota-failure events when the host provides
them.
If the quota dies without warning, the memory is already on disk.
## Manual handoff
Automatic journaling stays active, but you can force a handoff whenever you
want. In Claude Code:
```text
/elephant:memorize
```
Then open the same repository in Codex and invoke:
```text
$elephant resume
```
Codex receives the freshest capsule, compares it with the live worktree, and
continues the unfinished objective. Codex exposes installed skills through `$`
mentions; Claude plugin skills are namespaced as `/elephant:`.
For a named chat handoff, use `@Elephant exact auth-fix` before switching
harnesses, then `@Elephant pull auth-fix` in the new one. The prompt hook saves
the label before model execution and refreshes it on quota failure. If Elephant
was installed mid-session, it finds only the active chat for the exact current
project and safely snapshots its newest 256 KiB instead of copying an unbounded
or unrelated transcript. Pull feeds
the redacted chat to the new harness, identifies the previous harness, and gives
a short summary without starting work until you ask.
Codex `exact` uses the current bundled runtime before a possibly older Elephant
MCP process. This preserves the active chat after a plugin refresh without
requiring the user to reconstruct it.
| Command | Purpose |
|---|---|
| `memorize` | Force a fresh checkpoint of the current session |
| `exact
