How Elpis
works.

Concept walkthrough of the admission flow — Smart Prune scanning a completed tool result before the main model sees it (illustrated with fixture data, not a captured session):

Contents

• Quickstart
• What is Elpis
• Why Elpis
• Core Features
  • Context engineering
  • Context Ledger and observability
  • Live session dashboard
  • 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

Quickstart

v0.4.1 is the Linux x86_64 release, based on Codex rust-v0.160.0. Review the installer before running it:

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

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 ELPIS_HOME; inherited CODEX_HOME 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.

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.

Smart Prune is off by default. Already-sent history stays stable. Native /compact summarizes conversation history independently; it does not run Ace first. The legacy /force-prune command is not ported to the current foundation.

This diagram describes the retired automatic threshold-triggered configuration, not current Smart Prune behavior.

Historical pruning example

The following artifact comes from the retired configuration.

From a configured historical run with automatic pruning enabled under the superseded high-frequency setup (42 passes shown here; not current default behavior). 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 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.

In v0.2.0, Ledger and /context share category colors and a full-window scale. They distinguish active context usage from locally estimated request categories: user and agent messages, reasoning, tool calls/results, instructions, developer messages, and tool definitions. Category estimates are not provider-billed counts. Available backtrack checkpoints and local evidence links remain inspectable.

Earlier category-view capture; this image is retained to explain /context, not the September 9 appearance.

Live session dashboard

/dashboard opens the local session dashboard. Its seven views cover models, agents, activity, context, token usage, experimental Smart Prune and API keys. Agent hierarchy and model choices remain visible alongside the working session.

Recorded usage may be incomplete; unavailable subscription prices are shown explicitly.

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.

The October 10 local candidate isolates generated goals and checkpoints by thread, including simultaneous chats in the same workspace. A fresh thread does not automatically inherit another chat's generated state. A handoff explicitly admits the desired checkpoint.

The local candidate also restores the inherited review and worktree workflows. These changes and their validation are described in the continuity contract. The screenshot above shows a local candidate; published release behavior is documented separately.

Multi-agent work

The agents view makes the hierarchy and each agent's model visible. Experimental work graphs add task dependencies, bounded write scopes, concurrency limits and a required verifier for writable tasks. They are off by default; recorded checks do not guarantee a correct result.

See the session contract and work-graph contract.

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.

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 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

Current automated checks cover specific runtime, installer and continuity paths; they do not establish general coding-quality gains. The inherited whole Codex suite is not claimed green. Historical research below describes earlier configurations.

Evidence reviewed September 9, 2026. RQ1, RQ2, and RQ5 below describe historical evaluations. RQ4 includes the newer frozen-build cost study: 61 accepted pairs in 17 batches. Neither study benchmarks the latest UI binary. See the content and evidence audit.

The historical evaluation reports three paired, byte-identical configured workloads on gpt-5.6-luna (258,400 token context window), using a superseded high-frequency pruning setup. These runs share a workload and do not establish general task quality.

RQ1: Context Reduction & Operating Hygiene

Across those configured historical runs, Elpis maintained working sets within safe operational thresholds.

Peak Context Utilization

In those configured historical runs, 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

In those configured historical runs, Codex suffered wide distribution variance as transcripts accumulated, while Elpis tightly stabilized median token input at 68.8k–69.6k tokens (26.6%–27.0% of the window):

Trajectory Dynamics across Context Health Bands

When normalized across the recorded request lifecycle (0% to 100% completion), the historical Codex trace grows toward emergency rollover. The Elpis trace shown here uses automatic pruning under the superseded high-frequency setup; it is not current default behavior:

Operating Zone Breakdown

Across those configured historical 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): Not established. The executed runs are incomplete and unreplicated, so they do not support a comparative correctness claim in either direction. No per-arm score is reported, and there is no evidence that pruning improves task completion or output quality.

RQ4: Pruning Overhead & Token Economics

The September 9 cost study measures fresh-output admission on frozen binary d58e8c9b8861, using synthetic fixtures. Costs include main-agent and optimizer usage, priced at recorded September 8 rates; they are estimates, not invoices. Cache-hit fractions were observed, not controlled.

Longer runs can amortize optimizer cost; short runs cost more in these fixtures. The two Low/35 batches are a descriptive aggregation, not a pooled significance claim. A separate None-effort multi-file probe failed exact citation fidelity. Timeouts, stalls, format misses, and exclusions remain in the full report. These results do not establish real-repository task quality or universal savings. The chart data and provenance are regenerated from the recorded metrics by python3 scripts/refresh-public-evidence.py.

Historical overhead, retained for comparison:

Pruning adds an auxiliary model call sequenced against the main agent, and rewriting history invalidates the provider's cached prefix. Both costs are real. The figures below are configured historical runs with automatic pruning enabled under the superseded high-frequency setup; they bound that configuration's penalty rather than describe the current default: 730,810 auxiliary tokens spent to reclaim 605,377 context tokens (0.83 reclaimed per spent token).

RQ5: Forensic Auditability

The historical configuration recorded pruning events 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.

Current UI verification

The other implementation agent's September 9 report records 127 focused passing tests covering motion, startup, streaming, the ledger, and status; native frame exports and an installed PTY smoke check also passed according to that report. This content audit did not independently rerun those UI checks. This is scoped regression evidence, not a clean full-suite claim: pre-existing suite failures remain. The cost/pruning calculators passed 18 tests, and all 17 cost batches reproduced from the archived records without a discrepancy. See the audit for the separate build identities, test scope, chart provenance, and public-content checks.

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 draft, not a completed comparative-results paper

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/.