Never lose a thread again.

You run an agent inside Elpis, and it becomes Elpis.

Elpis is an open-source fork of OpenAI's Codex CLI that keeps the proven execution foundation while adding explicit context control, durable continuity, auditable pruning, and provider-neutral ownership around the model loop.

Install • Features • Evaluation • Docs

Contents

• Quickstart

• What is Elpis

• Why Elpis

• Core Features

  • Context engineering

  • Context Ledger and observability

  • Sessions and continuity

  • Memory

  • Deterministic work graphs

  • Bring your own provider

  • Integrations and tools

  • Privacy and ownership

• Evaluation status

  • RQ1: Context Reduction & Operating Hygiene

  • RQ2 & RQ3: Target Retention & Task Quality

  • RQ4: Pruning Overhead & Token Economics

  • RQ5: Forensic Auditability

• Documentation

• License

Related MCP server: MCP Agent Memory

Quickstart

Linux x86_64 and macOS on Apple Silicon:

curl -fsSL https://raw.githubusercontent.com/MasihMoafi/Elpis/main/scripts/install-elpis.sh | bash && ~/.local/bin/elpis

The installer picks the right binary for your machine and installs RTK, which powers shell-output filtering. On first launch, choose a provider and sign in or enter its API key.

v0.1.2 is the current release.

What is Elpis

Elpis is a provider-neutral coding-agent environment. The selected model or runtime performs inference; Elpis owns the surrounding working state: context admission, continuity, memory, permissions, tools, evidence, and the terminal interface.

It starts from OpenAI's Apache-2.0 Codex CLI and preserves its execution foundation — terminal UI, patches, permissions, sandboxing, sessions, and tool lifecycle — while adding a continuity- first control layer around it. Change the provider without throwing away the project context. Nothing about the project has to be explained twice.

Different paths. Same roots. One shared project.

Why Elpis

Long sessions fill up with transcripts, file reads, searches, command output, and dead ends. The useful state gets buried in the story of how the agent reached it, while every request pays for more context.

Elpis separates the active working set from durable evidence. The next request receives a small, inspectable context; the exact record stays on disk and can be retrieved when it is needed.

Three paired runs used one byte-identical prompt, the same model, and the same source commit on both arms. Peak context per request fell 47–65% in all three runs; median context stabilized at 26.6–27.1%. Codex peaked above 90% of the window in each run, while Elpis stayed safely bounded in the green zone.

Elpis never modifies a model's own output or a request already in flight. Pruning rewrites only harness-supplied tool output, using a separate model instance sequenced against the main agent.

Core Features

Context engineering

Context is a budgeted working set, not a dumped transcript. Elpis makes admission visible and uses a layered pipeline to keep useful findings while removing disposable exploration:

/prune runs the audited Ace pass on demand without rewriting user instructions, assistant messages, or model reasoning. Elpis's /compact remains the conservative fallback when selective pruning cannot reclaim enough context; the raw transcript remains durable evidence.

What a pruning decision looks like

One real pass from disk. A search command whose raw output ran to 18,930 characters — close to 5,000 tokens carried across requests:

Before — what the model was carrying:

Script completed · Wall time 0.1 seconds · Output:

tui/src/external_agent_config_migration.rs:800:   item_type: …ItemType::AgentsMd,
tui/src/external_agent_config_migration_flow.rs:75: …ItemType::AgentsMd
tui/src/theme_picker.rs:283:  fn theme_picker_subtitle(home: …) -> String
tui/src/theme_picker.rs:392:     subtitle: Some(theme_picker_subtitle(
tui/src/theme_picker.rs:605:     let subtitle = theme_picker_subtitle(…, Some(200));
tui/src/theme_picker.rs:617:     let subtitle = theme_picker_subtitle(…, Some(140));
tui/src/app_event.rs:152:        OpenAgentPicker,
… roughly two hundred more lines of the same shape …

After — what the model carries on the next request:

[Ace pruned 231 lines of ripgrep output (18,930 chars → 248 chars).
Findings:
- Found ItemType::AgentsMd in external_agent_config_migration.rs:800
- Found theme_picker_subtitle definitions in theme_picker.rs:283,392,605,617
- Full raw output preserved in rollout evidence: rollout://sess-01j8/tool-14.log]

Context Ledger and observability

The Context Ledger (Tab; during an active turn, Alt+C always toggles it) lists admitted goals, rules, memory, and other portable sources with their byte sizes and token budgets. Toggling a row writes admission.toml, which controls what the next turn receives.

/context answers a different question: where the window went. It displays token usage by user messages, agent responses, tool calls, system prompt, skills, and free space, alongside available backtrack checkpoints.

Sessions and continuity

Keep the working context across model switches, compaction, and restarts:

• GOAL.md holds the current task. It is carried into each request, stays visible across compaction, and is editable during a run.

• ES.md is an event-derived executive summary. It records modified files, commands run, blockers, and next steps, and is updated as the run progresses.

• Exact resume continues an existing thread with its full history, using the provider-native session when one is available.

• Lean continuation starts a clean thread from the current GOAL.md, ES.md, and active rules. This sheds old exploration without losing the objective.

Memory

Durable memory is one Markdown file, MEMORY.md, in the Elpis memory directory (derived from CODEX_HOME). The Context Ledger discovers it, lists it as a row, admits it by default, and lets you switch it off for the next turn.

• One visible file. Plain text. Read it, edit it, commit it to git, or delete it.

• Admitted in the open. Because it is a Ledger row, you can always see whether memory reached the model, and drop it when you do not want it.

• Retrieval beyond that file is your choice. Register an MCP server — for example rag-mcp-lancedb — and Elpis will use it.

Elpis previously ran an extraction, consolidation, and promotion pipeline. It was removed because it did not work: across two threshold settings it produced zero durable promotions, every sweep landing one recall short of the gate. Memory that rewrites itself in the background without appearing anywhere is the failure mode the Ledger row exists to prevent.

Deterministic work graphs

A coordinator can fan work out to several agents under an engine that validates the plan before anything runs. This is Elpis's own; it is not part of the Codex foundation.

The coordinator submits a complete task graph — tasks, dependencies, write scopes, acceptance criteria, and environments. Elpis then owns the scheduling:

• Cycles cannot be scheduled. Kahn's topological algorithm proves the graph is acyclic and rejects it otherwise, so no worker is created for a plan that could only deadlock.

• Write conflicts are caught by construction. Path-prefix intersection detects overlapping write scopes, and all writable tasks in one environment are serialized even when their declared prefixes do not overlap.

• Verification is not optional. A writable task without a directly dependent verify task in the same environment is rejected before dispatch.

• Evidence gates progress. Dependent work is released only after an accepted result; a failed, cancelled, or blocked prerequisite blocks its descendants.

Elpis never creates, merges, rebases, deletes, or pushes branches or worktrees. Preparing and integrating them stays coordinator-owned, because those operations change durable user state and deserve deliberate review.

Off by default. Enable with enable_fanout = true under [features]; there is no slash command. Full rules and the graph schema are in docs/WORK_GRAPHS.md.

Bring your own provider

Elpis is not tied to a single model vendor:

• OpenAI: GPT-4o, GPT-5.6-Luna, o1, o3, and compatible endpoints.

• Anthropic: Claude 3.5 Sonnet, Claude 3 Opus, Claude 3.5 Haiku.

• Google: Gemini 2.0 Flash, Gemini 1.5 Pro.

• Local & self-hosted: Ollama, vLLM, and any OpenAI-compatible server.

Switch models mid-session without restarting. The working context, goal, and session memory are preserved across provider boundaries.

Integrations and tools

Extend Elpis with external capabilities that stay in their own processes through MCP:

• Workspace retrieval: rag-mcp-lancedb provides local LanceDB/Tantivy search over your documents.

• Voice transcription: WhisperType provides local speech-to-text without adding its model/runtime dependencies to Elpis core.

Privacy and ownership

Telemetry is off by default and no analytics are uploaded unless you explicitly configure an exporter. Bring your own provider keys. Durable Elpis state is local files and SQLite that you can inspect, edit, export, or delete.

Evaluation status

The published evaluation empirically benchmarks Elpis against OpenAI's Codex CLI across three paired, byte-identical workloads on gpt-5.6-luna (258,400 token context window).

RQ1: Context Reduction & Operating Hygiene

Across all three independent runs, Elpis prevents context exhaustion by maintaining working sets within safe operational thresholds.

Peak Context Utilization

Codex expanded into the critical danger zone (>90% window) in every run, forcing 3 emergency compactions. Elpis maintained peak window utilization at 32.5–49.5%, achieving a 47–65% reduction in peak context footprint:

Input Token Distribution & Interquartile Stability

While Codex suffered wide distribution variance as transcripts accumulated, Elpis tightly stabilized median token input across all runs at 68.8k–69.6k tokens (26.6%–27.0% of the window):

Trajectory Dynamics across Context Health Bands

When normalized across the request lifecycle (0% to 100% completion), Codex exhibits unbounded monotonic growth until emergency rollover occurs. Elpis triggers the Ace cycle whenever context crosses the 30% boundary, steadily returning working state to the green target zone:

Operating Zone Breakdown

Across all executed requests, Elpis spent over 95% of its operating lifespan inside the safe and healthy bands, with zero requests entering the critical danger zone:

RQ2 & RQ3: Target Retention & Task Quality

• RQ2 (Information Retention): In benchmark audits testing recall of key file paths, schemas, and error signatures after pruning, 100% of tested targets (6/6) were retained intact in active context.

• RQ3 (Task Performance): Verified task completion was maintained across all arms. Both Elpis and Codex achieved equivalent task success with 0 functional regression.

RQ4: Pruning Overhead & Token Economics

Pruning adds an auxiliary model call sequenced against the main agent. In the 41-pass benchmark run, 730,810 auxiliary tokens were spent to reclaim 605,377 context tokens (0.83 reclaimed per spent token):

RQ5: Forensic Auditability

Every pruning event produces an immutable audit record on disk under ~/.elpis/logs/pruning/. In full forensic reconstruction evaluations, 7 of 9 properties were completely recoverable from disk, 2 partial, and 0 absent.

Documentation

• Context and pruning — admission, lifetimes, pressure pruning, and audit records

• Sessions and continuity — exact resume, lean continuation, GOAL.md, and ES.md

• Deterministic work graphs — plan validation, write scopes, concurrency, and evidence gates

• Providers — provider adapters, BYOK, and protocol limitations

• Evals & benchmarks — source data, procedures, scorers, and results

• Technical guide — product thesis, requirements, and architecture

• Research paper — technical preprint and formal specifications

License

Apache-2.0.

The execution foundation — terminal UI, patches, permissions, sandboxing, and sessions — derives from OpenAI's Apache-2.0 Codex CLI. Elpis extends that foundation with context admission and pruning, continuity checkpoints, auditable evidence, and provider control. Codex-derived source retains its upstream notices under codex-rs/.