Elephant

The model forgets. The elephant doesn't.

Claude hits quota. Codex keeps going.
_{Automatic, local-first session continuity across AI coding harnesses.}

Visit the Elephant website →

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:

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:

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:

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.

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

┌──────────────────────────────────────────────────────────────┐
│ 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:

/plugin marketplace add vishesh9131/elephant

/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

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

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

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

pi install git:github.com/vishesh9131/elephant@v0.4.5

Requires Node.js 22.19+. Pi loads the native JavaScript extension, /elephant <command>, /resume, and the Elephant skills.

Hermes Agent

hermes plugins install vishesh9131/elephant --enable

Restart Hermes after installing. Elephant registers native lifecycle hooks, the recovery tools, both Elephant skills, and /elephant <command>.

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:

{
  "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.

See the full platform matrix 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:

/elephant:memorize

Then open the same repository in Codex and invoke:

$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:<command>.

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.

Hermes and Pi use /elephant <command>. Other skill-capable hosts use $elephant <command>, their native skill picker, or natural-language invocation.

Cleanup is deliberately two-step. This only previews sessions older than 30 days, always retains at least the newest 10 sessions, and skips anything pinned:

/elephant:clean

To apply that preview in Claude Code, explicitly confirm it:

/elephant:clean 30d --keep 10 --yes

Then /elephant:compact can reclaim unused database pages. In Codex, use the same arguments after $elephant; in Hermes and Pi, use /elephant.

Local means local

Elephant has no account, cloud, analytics, telemetry, ad network, or mysterious “improve the product” upload.

~/.elephant/
├── elephant.db       # events, recovery capsules, and cleanup pins
└── transcripts/      # optional compressed transcript copies

Sensitive keys and common credential formats are redacted before persistence. Redaction is defense-in-depth, not magic: protect the machine and do not share the database casually.

Set ELEPHANT_DATA_DIR to move the store. Read the privacy notice and security policy.

Resume explicitly

Automatic recovery happens when a native host starts a new session in a project that has an Elephant capsule from another session.

When you want to ask directly:

Recovery compares the capsule's Git metadata with the live worktree. The files on disk win. Elephant remembers the past; it does not overwrite the present.

Tested, not merely listed

The conformance suite proves the same flow across adapters:

capture → checkpoint → switch harness → recover → verify Git state

The current release includes:

• real plugin-load checks for Claude Code, OpenCode, Pi, Copilot, and Hermes when their binaries are installed, plus remote marketplace discovery in Codex;
• live model-turn verification for Copilot CLI and Hermes;
• cross-harness Claude → OpenCode → Pi → portable recovery contracts;
• 11 Python/JavaScript tests for journaling, redaction, MCP, manifests, and continuation.

Run everything available on your machine:

PYTHONPATH=src python3 scripts/conformance.py
python3 -m unittest discover -s tests -v

The event protocol is documented in docs/protocol.md.

FAQ

Does Elephant ask the dying model to summarize the session?

No. A model at quota is about as useful as a fire alarm after the building is gone. Elephant records continuously and builds the handoff itself.

Does it copy my session to another company's server?

No. Harnesses still send prompts to their own configured model providers, but Elephant's journal stays on your machine.

Can it really know when I am at 98%?

Only if the harness exposes that number. Most do not. Elephant would rather be useful at an honest unknown than impressive at a fictional 98%.

What if the repo changed after the handoff?

The live worktree is authoritative. Elephant shows the old capsule as evidence, compares Git state, and continues from what actually exists.

Why “Elephant”?

Because “Cross-Harness Context Persistence Orchestration Kernel” remembered the architecture and forgot the joke.

Development

The core is dependency-free Python. Host-specific code stays thin: manifests, hook maps, skills, and small JavaScript/Python adapters around the shared event protocol.

To add another harness:

1. declare what its API genuinely exposes;
2. map native events into the Elephant protocol;
3. package the host's native install surface;
4. prove capture → checkpoint → recovery in conformance tests.

Contributions are welcome. Fake support badges are not.

License

MIT. Elephants travel better when the gate is open.