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.
Linux verification License Telemetry
Install • Features • Evaluation • Docs
Contents
Quickstart
What is Elpis
Why Elpis
Core Features
Context engineering
Context Ledger and observability
Sessions and continuity
Memory
Bring your own provider
Integrations and tools
Privacy and ownership
Evaluation status
Documentation
License
Quickstart
v0.4.1 is the Linux x8664 release, based on Codex rust-v0.160.0. Review the installer before running it:
The installer verifies SHA-256 checksums and includes the Code Mode host and Linux sandbox. RTK is optional and is not installed automatically. macOS and Windows binaries are not included. Choose a provider and sign in or configure its API key, then select a model with /model.
State lives in /.elpis-next, or the directory selected by ELPISHOME; inherited CODEXHOME is ignored. The v0.3.0 database is incompatible with this foundation and is preserved rather than automatically migrated. See the current release README for upgrades and rollback.
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.
The desktop app
The desktop app runs the same engine as the terminal app and shares its state folder, /.elpis-next.
Workflows
Describe a job. The Mother agent, the planning agent, either does it herself or designs a team of agents that you can see and edit on a board. Each agent owns its own folder, a second agent checks its work, and the Mother agent reviews the combined result before anything reaches your project.
Love Spot
A drawing board where Matilda, the app's companion, answers and draws with you. Paste screenshots onto the board and draw on them.
Agents on any provider
In the terminal app, the Agent command center lists every chat and its helpers. A helper may run on another provider than its parent.
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 configured historical runs with automatic pruning enabled under the superseded high-frequency setup used one byte-identical prompt, the same model, and the same source commit on both arms. In those runs, peak context per request fell 47–65%; 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
Elpis makes admitted instructions, chosen files and saved memory inspectable. Saving information and choosing to include it in the next request are separate controls. Durable evidence remains available outside the working context.
Historical architecture illustration. Current defaults and controls are described below.
Control What it does When Optional RTK filtering An external shell-output filter; not installed automatically. Before eligible output reaches the model Deterministic safety cap Bounds exceptionally large tool results, inherited from Codex. Before the agent sees them Experimental Smart Prune Can shorten eligible fresh tool output; a failed attempt passes the original through. Once, before its first main-model admission
Smart Prune is experimental and off by default. When enabled, it may shorten eligible fresh tool results before their first admission to the main model. Already-sent history stays stable. Native /compact summarizes conversation history separately.
Historical pruning example
The following artifact comes from the retired configuration.
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:
After — what the model carries on the next request:
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 capped character-derived estimates. Toggling a row writes admission.toml, which controls what the next turn receives.
Development rules are ordinary Markdown Ledger rows, not skills: newly discovered rules start included and an explicit exclusion persists. A nonempty configured development-rule root list replaces the managed fallback; an empty list uses it. Elpis leaves ordinary and bundled skills off by product default, while deliberate user configuration can enable a selected skill. Enabled skills expose compact metadata and keep their bodies lazy; /skills shows available candidates and their origins, but mentions and the model-visible list contain enabled skills only. The Ledger has no skills-catalog token row; its per-source estimates are not tokenizer measurements.
Context Ledger · 13 October 2026 · light theme. Smart Prune and subagent delegation are enabled in this session. Smart Prune is experimental and off by default. Category shares and source sizes are estimates; the measured request total is separate. Open the original image to inspect it at full size.
/context answers a different question: where the window went. It displays token usage by user messages, agent responses, tool calls, system prompt, Development rules, and free space, alongside available backtrack checkpoints.
Sessions and continuity
Elpis keeps a working checkpoint alongside the runtime's conversation history. That checkpoint carries the goal, decisions, changed files, verification, blockers and next step into later work.
Resume and handoff
Exact resume reopens the original runtime thread. A portable checkpoint supplies a compact working state; it does not reproduce the complete transcript. Elpis refreshes admitted context between turns so changes to included sources can reach the next request.
Memory
The responding agent can explicitly save useful knowledge and the workspace checkpoint through a guarded local tool. Saving makes information durable; the Context Ledger separately decides whether it enters future working context.
Control over recall
Admitting MEMORY.md includes up to 8,000 trimmed Unicode characters in the working context. Excluding it stops that admission. A saved fact still needs source evidence and correction when circumstances change.
The former extraction and consolidation pipeline is superseded. Current memory does not depend on a second model summarizing conversations in the background. Available verification covers specific save, correction and recall paths; it does not establish a general improvement in coding quality.
See the current README and the memory section of the context contract.
Bring your own provider
Elpis keeps context, continuity, permissions and evidence around the selected model or runtime. Provider selection and authentication are separate decisions.
Choose a route
Use /model or the supported --provider launch option. The local gateway supports Anthropic, Gemini and OpenRouter routes alongside OpenAI. Configure credentials for the selected route; a key alone does not select it. Available models depend on that route and account.
The session dashboard exposes current model selections and recorded usage. It shows unavailable subscription prices explicitly rather than estimating a provider's internal cost.
A Claude Code subscription uses the official Claude runtime through a separate adapter path. It is distinct from direct Anthropic API access, which needs its own API credentials. Capabilities and authentication follow the selected path.
See the current README and provider contract for installation and version-specific configuration.
Integrations and tools
Extend Elpis with external capabilities that stay in their own processes through MCP:
Workspace retrieval: rag-mcp 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 recorded admission audit covers 13–16 October 2026 across 20 sessions. It summarizes pruning attempts and admitted tool-output tokens; it does not establish savings on a provider bill or improved task quality.
Recorded measure Result Pruning attempts 1,598 Admitted results 1,453 Unchanged results 120 Model errors 21 Cancelled attempts 3 Malformed result 1 Tool-output tokens before admission 4,069,052 Tool-output tokens admitted 1,017,282 Tool-output tokens removed 3,051,770 Weighted tool-output reduction 75.0% Median pruning latency 7.43 seconds 95th-percentile pruning latency 18.53 seconds
Auxiliary usage is available for 1,574 attempts; 24 have missing usage. The recorded auxiliary calls used 6,543,376 input tokens and 1,016,297 output tokens, totaling 7,559,673. Those costs must be considered alongside the reduction in admitted tool output.
The available sessions do not form a matched pruning-on versus pruning-off comparison. Original rollout evidence is incomplete, so these aggregates cannot support a causal claim about total token savings, billing, information retention, or coding quality.
Documentation
Context and pruning — admission, lifetimes, pressure pruning, and audit records
Sessions and continuity — exact resume, lean continuation, GOAL.md, and ES.md
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/.