SpineCodex
A Codex distribution that compiles subtask trees into context, cutting long-horizon coding costs by 32%–74%.
- Source repo
- GhabiX/SpineCodex
- Stars
- ★ 151
- Last updated
- 3d ago
- License
- Apache-2.0
- Primary language
- Rust
- FA score
- 37/100 · Major gaps
At a glance
- How it runs
- Works with
- Platform-specificCodex · OpenAI API
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- Engineers doing large multi-milestone refactors who don't want flat history compaction to erase subtask boundaries
- Not a fit if
- Teams that want an account setup fully independent of an existing ~/.codex configuration
- Users doing short one-off edits who don't care about context cost
- Anyone who needs zero model-API spend
- Website
- arxiv.org/abs/2610.37224 ↗ set on GitHub
- Maintenance
- Commits in the last 30 dayslast commit 2026-11-18latest release v0.6.0 (2026-11-19)
- Source review
- 37/100 · Major gaps 1 safety controls not found
What does this agent do, and when should you use it?
SpineCodex is a standalone, open-source distribution of OpenAI Codex CLI that runs long-horizon coding under a persistent work tree called SpineTree. While reasoning, the agent marks subtask boundaries with four lightweight primitives — Open, Close, Next and Spawn — keeping sequential steps inline in the current session and fanning independent branches out in parallel, with results returned into the same tree. Before each model call, the Spine runtime compiles SpineTree into minimal effective context: finished subtasks collapse into their returned results while the untouched parent context stays byte-for-byte identical, so prompt-prefix caching keeps hitting. It ships as the npm package @spinejit/spine-codex, a global CLI that reuses your existing ~/.codex configuration, credentials and skills; v0.6.0 tracks upstream Codex 0.170.0. An optional /experimental switch exports closed-node memory to .codex/spinetree/ for inspection.
Run from the terminal, SpineCodex reads your task and local codebase, then drives the model through extended reasoning and tool calls. The runtime maintains SpineTree: the agent opens and closes subtasks (Open / Close), advances sequential steps (Next), and spawns independent branches (Spawn) whose results fold back into the same tree. Before every model request, the compilation frontend replaces closed branches at the active suffix with concise returned results, leaving preceding parent context unchanged to preserve prefix-cache hits. Inside the TUI, slash commands such as /experimental enable a Spinetree memory projection that writes closed-node memory under .codex/spinetree/.
- Engineers doing large multi-milestone refactors who don't want flat history compaction to erase subtask boundaries
- Researchers benchmarking coding-agent cost efficiency on long-horizon suites like SWE-Milestone or ProgramBench
- Existing Codex CLI users who want to try an enhanced runtime without changing any code or startup workflow
- Developers who need to explore several independent approaches concurrently and gather results in one place
- Teams tracking per-request input tokens and total spend against history-folding or recursive-subagent setups
Key setup facts
Pulled from the install and usage notes below. The project README has the current values.
- Install / run
npm install -g @spinejit/spine-codex@latest
- Config files
~/.codex
How do you install or deploy this agent?
You need Node.js with npm, plus a working ~/.codex configuration and credentials (SpineCodex inherits them).
npm install -g @spinejit/spine-codex@latestOnce installed, launch it from any terminal with spine-codex.
How do you use this agent?
Start it inside your project directory; first confirm ~/.codex already holds valid credentials and skills.
spine-codexDescribe the task in the TUI as you would with Codex — the agent declares Open / Close / Next / Spawn boundaries itself. To inspect the memory projection of closed nodes, run inside the TUI:
/experimentalExports then land in the .codex/spinetree/ directory.
What are this agent's strengths and limitations?
- Compiles a subtask tree rather than a linear history; the README reports total cost down 32.4% (GPT-5.6 Sol) and 37.9% (Grok 4.6) versus native Codex
- Sequential subtasks open and close inside the current session, so only independent branches pay the Spawn overhead of cross-branch handoff
- Parent context is kept byte-for-byte for prefix-cache reuse while completed branches are folded away, satisfying both cache hits and context trimming
- Inherits existing ~/.codex configuration, credentials and skills, so one global npm install is enough to start
- Tracks upstream OpenAI Codex releases (v0.6.0 targets 0.170.0), ships under Apache-2.0, and is backed by an arXiv paper with ablation studies
- Depends on the OpenAI Codex ecosystem and a ~/.codex setup — it is a distribution of a specific upstream, not a general agent framework
- The cost and pass-rate figures come from the authors' own three-benchmark evaluation, with no independent reproduction documented
- Still at 0.x with a release cadence tied to upstream Codex, so upgrades can shift behavior
- Getting the most out of it means understanding the compilation semantics of Open / Close / Next / Spawn, which adds a learning curve
- Requires network access to model APIs; there is no offline mode
How does this agent compare with similar options?
The README positions SpineCodex against three concrete alternatives: native OpenAI Codex (-45% average input tokens per request, -32.4% total cost on SWE-Milestone); recursive subagent delegation (-73.7% total cost, with 19 vs. 17 milestones resolved); and history compression/folding strategies (+14.8%–16.7% score, -22.7%–58.1% cost). The same authors also publish Spine plugins for Pi and DeepSeek Harness for runtimes other than Codex.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| SpineCodex This agent | 37 · Major gaps | CLIFree + model costs | ★ 151 | 3d ago | Rust | Codex · OpenAI API |
| Crewplane | 76 · Some gaps | CLIFree + model costs | ★ 56 | 4d ago | Python | Codex · Claude Code |
| GraphCode | 53 · Major gaps | Desktop appFree + model costs | ★ 159 | 2d ago | Swift | ChatGPT · Codex · Claude Code |
| mu Coding Agent | 72 · Some gaps | Desktop appFree + model costs | ★ 614 | 2d ago | TypeScript | — |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows this is a Codex-derived distribution; the README claims inheritance of ~/.codex credentials and config but does not describe least privilege, approval flow, or data flow; docs/sandbox.md only links to official documentation and gives no concrete boundaries within this repository. The imagegen skill requires user confirmation for CLI fallback and does not overwrite existing assets, which is a local highlight, but overall permission and confirmation mechanisms depend on upstream and are not documented here, so only 1 is given. Rollback mechanism is entirely absent from the sample (0). Source attribution is good: LICENSE is Apache-2.0 and the README clearly attributes upstream OpenAI Codex and NOTICE, giving 2.
README and docs/install.md are clearly inconsistent: the install doc still points to cloning the openai/codex repository rather than this repository; the version number appears in the README as both a v0.5.1 demo and v0.6.0 description, so self-consistency is weak (1). On dependency availability, package.json pins pnpm/node versions and resolutions but does not explain the correspondence between the npm package and the Rust build, so only 1 is given. Failure messages are partly explicit in bwrap and app-server, but overall not systematized, giving 1.
The README describes long-horizon coding scenarios and benchmarks fairly clearly, so audience and scenarios are identifiable (2). However, capability boundaries rely mainly on the paper and external links; the repository does not give concrete constraints or disabling conditions for Spine primitives (1). On trigger precision, skill descriptions are fairly precise (e.g., applicability/non-applicability of imagegen and review-agent), but the main product's trigger conditions are not described (1). Environment fit only lists macOS/Ubuntu/WSL2 and memory requirements, not native Windows or container scenarios (1).
Information architecture has README, docs, and skills layers, but docs are mostly external-link placeholders and the structure is thin (1). Install notes exist and give system requirements, but the wrong clone address weakens credibility (1). On naming stability, package name and version number are basically consistent, but the README's version narrative is mixed (1). Examples and FAQ consist only of a benchmark table and a few commands, lacking common questions (1). Known limitations are entirely absent (0). License is complete and is Apache-2.0 (2). Versioning and changelog have Recent Releases and a release-notes link (2). Maintenance responsibility lists two maintainers and an Issues channel, but publisher identity is unverified (1).
On output usability, the README gives install commands and a TUI demo but lacks concrete usage examples and output samples (1). Marginal value depends on paper benchmarks; the repository provides no reproducible comparison scripts or data (1). Cost-benefit rests only on the README's claimed 32%-74% cost reduction and benchmark table, lacking locally verifiable cost accounting (1).
On claim traceability, the README cites an arXiv number and benchmark names, but there are no corresponding data files in the repository (1). On cross-source corroboration, skills and source samples partly corroborate the product form, but benchmark and cost claims have no in-repo corroboration (1). On fact/inference separation, the README mixes paper conclusions with product claims without marking which are measured and which are cited (1).
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- README claims inheritance of ~/.codex credentials and config, but the repo does not document permission scope, approval policy, or data flow; review sandbox and network settings before use.
- docs/install.md clones openai/codex rather than this repository, so following it may build upstream instead of this distribution.
- Benchmark and cost claims (32%-74%) come only from a cited paper; no reproducible scripts or data are in the repo, so they should not drive adoption decisions alone.
- Publisher identity is unverified; maintenance responsibility and update path need independent confirmation.
- No rollback or recovery mechanism is described in the sample; treat operations with external side effects cautiously.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v0.6.0 0.6.0
Release notes excerpt
Allow the native Intel Mac release build six hours on Codex 0.170 On rehearsal 44296720357 five native builds passed. The Intel runner canceled its still-running rustc at the four-hour deadline. Give that matrix entry the hosted six-hour budget, preserving compiler flags, artifact content and package verification. --- Upstream Codex compatibility: 0.170.0 Upstream Codex baseline: rust-v0.170.0 Upstream Codex commit: 29eb79e9866b3262a777fdf8195c1b9e63684c91 --- SpineCodex 0.6.0 SpineCodex now tracks OpenAI Codex rust-v0.170.0 at commit …View on GitHub ↗ -
v0.5.1 0.5.1
Release notes excerpt
chore(release): prepare SpineCodex 0.5.1 --- Upstream Codex compatibility: 0.164.0 Upstream Codex baseline: rust-v0.164.0 Upstream Codex commit: 6aaac694803004a63c6f393d153c96d22521a6b9 --- SpineCodex 0.5.1 This patch restores the local startup policy used before automatic managed-daemon startup was introduced. - Local new, resume and fork sessions passively discover a compatible Spine app-server. When none is available, they start the embedded app-server from the current CLI. - Invocation overrides, including --profile, keep their configuration in the embedded app-server. …View on GitHub ↗ -
v0.5.0 0.5.0
Release notes excerpt
Fix Spine task pressure to follow committed sampling checkpoints --- Upstream Codex compatibility: 0.164.0 Upstream Codex baseline: rust-v0.164.0 Upstream Codex commit: 6aaac694803004a63c6f393d153c96d22521a6b9 --- SpineCodex 0.5.0 Updates the upstream Codex baseline to 0.164.0 (rust-v0.164.0, commit 6aaac694803004a63c6f393d153c96d22521a6b9). - Adapt Spine sampling, recursive spawn, history persistence and TUI integration to the new upstream APIs, including compressed rollout readers and typed context metadata. …View on GitHub ↗
FAQ
Do I need to supply a separate API key?
How is Spine different from spawning a subagent per subtask?
Under what conditions were the cost numbers measured?
Does the spinetree memory projection touch my repo?
.codex/spinetree/ for inspection.What happens when upstream Codex moves?
Is SpineCodex open source?
Is SpineCodex safe to use?
Is SpineCodex still maintained?
Who makes SpineCodex?
What is SpineCodex's official website?
Thanks — we use this to improve the page.