sliceagent

A coding agent that reconstructs a history-bounded, task-elastic working context every turn — instead of accumulating a chat transcript and summarizing it when it overflows.

That one change is the whole product. Because context is reconstructed from active semantic state and live ground truth each turn rather than piled up:

• History-bounded cost — when active task state stays stable, per-turn input does not grow merely because the session is older; there is no transcript-driven grow-to-window sawtooth.
• Task-elastic focus — simple tasks stay lean, while real user constraints, coupled files, and unresolved evidence can expand the working slice when needed.
• Recoverable live state — every turn re-observes relevant workspace state and faithfully carries current failures; retired detail pages out behind stable handles instead of forcing routine transcript compaction.

The field's default is bigger windows + summarize. sliceagent does the opposite: carry what remains active; archive and recover the rest.

Pre-1.0: on 0.x, CLI flags, config keys, and APIs may change between releases; breaking changes are noted in the CHANGELOG.

Contents: How it works · Packages & embedding · Benchmark · Install & quickstart · Usage · License · Acknowledgements · Contact

How it works

sliceagent's memory is organized like a brain: fast, lossy perception of the live world; an elastic working memory for the current task; a hippocampus backed by always-on local artifacts; and a typed native neocortex for provenance-linked USER, PROJECT, and CRAFT knowledge. Every turn reconstructs a history-bounded working set from these — it never replays a growing transcript. With Memem's structured-index protocol (2.10+) installed, Memem is the primary semantic retrieval backend for typed L2; it is not another brain layer or a second record authority.

Region	Role
Sensory cortex — live perception	Re-derives only live resources named by the active dependency closure; unrelated repo maps, history, and memory are not eagerly injected.
Prefrontal cortex — working memory	Source-linked Active Work for genuine unresolved, cross-turn user commitments; it is not a shadow scheduler for tools or subagents.
Hippocampus — episodic memory	Seals every turn into the always-on local artifact store; optional child-report artifacts add re-readable locators without gating direct report delivery.
Neocortex — long-term memory	Stores scoped, provenance-linked USER, PROJECT, and CRAFT records in one typed model; Memem provides primary semantic retrieval when available, with native search as failover.

The implementation contracts are documented in End-game context design and Memory layers design.

The exact current request is admitted once into an application event ledger and one Active Work root. Context is selected from that graph's unresolved dependency closure before physical elasticity is applied. After execution, the sealed turn carries a canonical receipt distinguishing requested, rejected, started, settled, and applied work. A constant-size receipt projection remains visible without constructing an autobiography from conversational residue.

┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐
│        PFC        │ │  Sensory Cortex   │ │    Hippocampus    │ │     Neocortex     │
│  working memory   │ │  live perception  │ │  episodic memory  │ │  durable lessons  │
└─────────┬─────────┘ └─────────┬─────────┘ └─────────┬─────────┘ └─────────┬─────────┘
          │                     │                     │                     │
          └─────────────────────┴──────────┬──────────┴─────────────────────┘
                                           ▼
      ┌────────────────────────────────────────────────────────────────────────┐
      │            GLOBAL WORKSPACE  —  this turn's reconstructed seed           │
      │        (carried slice + live views + relevant lessons + prompt)         │
      └────────────────────────────────────────────────────────────────────────┘
                                           ▼
                         ┌───────────────────────────────────┐
                         │             LLM turn              │
                         │ tool calls accumulate within-turn │
                         └───────────────────────────────────┘
                                           ▼
                      ┌─────────────────────────────────────────┐
                      │  PFC updated · turn sealed to artifact  │
                      └─────────────────────────────────────────┘

  ↻  next turn: the active slice remains resident;
     live views re-derive, archived detail returns by handle.

Each turn faults in what the active task references — the carried slice, live views, selected artifacts, and applicable typed USER, PROJECT, or CRAFT knowledge — and hands the model an elastic Seed. The model acts; observations fold back into working memory; at the turn boundary the episode is sealed into an immutable local artifact and the next checkpoint is published. Qualifying evidence may then consolidate into a native typed lesson; optional semantic retrieval may index it but is not required. Net effect: for stable active task state, context does not grow merely with session age; it can still expand with genuine task complexity.

Packages & embedding

The repository has a one-way package boundary:

• sliceagent-core is the reusable bounded-slice runtime. run_turn(...) includes the ordered tool scheduler by default and runs without the CLI; hosts can replace behavior through the LLMClient, ToolHost, ToolScheduler, Retriever, Memory, Registry, Safeguard, and Oracle contracts.
• sliceagent-cli is the coding-agent host: terminal UI, coding tools, workspace retrieval, and optional Memem integration.
• sliceagent remains the product and compatibility namespace. The current product wheel vendors both packages while existing callers migrate to the split names.

The dependency points one way: CLI → core, never core → CLI. A bare core install has no required third-party dependencies; the built-in OpenAI-compatible client is available through the openai extra. Standalone package publishing is a separate release decision.

Benchmark

On public benchmarks, sliceagent matches Codex's solve rate while using 2.5× fewer tokens and 1.3× less cost on ColBench, and 11.7× fewer tokens on long sessions.

Two questions decide whether reconstructing context every turn actually works: does it stay as capable as a transcript agent, and does it keep per-turn cost history-bounded as the session grows — sized to the current task, not the accumulated history? All four benchmarks are head-to-head vs OpenAI Codex on the same model (gpt-5.5) — the fourth adds a third question: what does it cost to orchestrate a subagent fleet.

1. In-turn capability — Terminal-Bench 2.0 (public)

A TB2.0 task is a single turn, so it's a clean test of raw within-turn ability. On the 32 tasks both agents completed cleanly:

metric	sliceagent	OpenAI Codex
pass rate	18 / 32 (56%)	18 / 32 (56%)
wins (exclusive)	4	4
median steps / task	10	27

Dead even, 4 wins each — reconstruct-every-turn matches a state-of-the-art agent on in-turn tasks with no capability tax.

2. Multi-turn — ColBench (public: Meta SWEET-RL)

Collaborative coding over multiple rounds with a simulated human — the memory model does matter here. 20 backend tasks, both gpt-5.5 at high:

metric	sliceagent	OpenAI Codex	% of Codex
solved	20 / 20	20 / 20	parity
input tokens · total	284k	760k	37%
↳ served from cache	50%	57%	—
output tokens · total	24.3k	8.8k	276%
total tokens	308k	769k	40%
rounds · median	3	3	—
wall · median/turn	26s	26s	100%
cost (cache-aware $)	$0.44	$0.55	80%

Same capability — 2.5× fewer tokens, 1.3× cheaper, at parity wall.

3. Long-horizon multi-turn — self-designed coding scenarios

Iterative coding sessions where a transcript really piles up. Each scenario is a fixed sequence of 6–10 dependent, pre-written turns revealed one at a time — later turns build on (and regress) earlier work, so no agent can one-shot them and byte-identical turns go to both agents. Both gpt-5.5 at high. Reproduce with benchmarks/run.py (the scenarios are in benchmarks/multiturn_coding/):

metric	sliceagent	OpenAI Codex	% of Codex
solved	3 / 3	3 / 3	parity
input tokens · total	2.21M	26.4M	8%
↳ served from cache	84%	91%	—
output tokens · total	63.4k	355.4k	18%
total tokens	2.28M	26.7M	9%
wall · total	1,069s	1,761s	61%
cost (cache-aware $)	$1.30	$9.43	14%

Per task:

scenario	agent	solved	total tokens	wall
s1 long-horizon debug (6 turns)	sliceagent	✓	499k	257s
	Codex	✓	5.17M	465s
s2 dependency-DAG scheduler (10 turns)	sliceagent	✓	924k	461s
	Codex	✓	10.0M	656s
s3 interval-set algebra (10 turns)	sliceagent	✓	854k	351s
	Codex	✓	11.5M	641s

Same capability — 11.7× fewer tokens, 7.3× cheaper, 1.6× faster. Across these 6- and 10-turn sessions sliceagent's largest single model call stayed between 14,769 and 19,104 tokens.

4. Subagent fan-out — hosting a delegation fleet (benchmarks/subagent_fanout.py)

A ColBench-style human-sim (a staff engineer) explicitly tells both agents to fan out — one explorer subagent per module across a 6-module service — then asks four parent-only follow-ups: a 6-turn session, 2 fan-out turns + 4 follow-ups. Codex exec ships its own spawn_agent primitive, so both agents genuinely delegate. The question isn't who can delegate; it's what the orchestrator pays to run a fleet. Both gpt-5.5 at high; each agent's own subagent tokens are counted — Codex's child threads recovered from its session rollouts — for a true total-vs-total. N = 3 runs, mean [min–max]:

metric	sliceagent	OpenAI Codex	% of Codex
subagent spawns	14	11.7	both fan out
delegated · own children	341,515	568,027	60%
true total (orchestrator + children)	610,612 [536k–656k]	2,235,243 [2.11M–2.32M]	27%

sliceagent's orchestrator per turn (mean of 3 runs) — largest single model call:

turn	1 · fan-out	2 · fan-out	3 · follow-up	4 · follow-up	5 · follow-up	6 · follow-up
largest call	37,191	36,817	39,447	82,232	41,447	31,963

sliceagent's orchestrator carried child results rather than child trajectories, so its context did not trend upward from turn 1 to turn 6. Counting both agents' children, the transcript orchestrator used 3.7× more total tokens over the same workload. Parent context does not grow with child trajectory length, though it may still grow when more delegated results are genuinely relevant. Delegation is table stakes; the architectural advantage is direct child outcomes, optional re-readable artifacts, and a history-bounded parent.

N = 3 runs, single model, one opponent, needs the Codex CLI installed. A value-recall sub-check varied wildly run-to-run (sliceagent 1–3 / 3, Codex 0–2 / 3) — it turns on a behavioral re-read choice, so it is within noise and not part of the claim. The defensible result is the total-token gap, which held across all three runs (3.2–4.3×).

How the cost numbers are calculated (exact token counts × published rates)

Cache-aware, at gpt-5.5 list rates — $1.25 / 1M fresh input, $0.125 / 1M cached input (a 10× discount on the prompt prefix the provider serves from its cache), $10 / 1M output:

cost = fresh_in × $1.25/M  +  cached_in × $0.125/M  +  output × $10/M
       where  fresh_in = total input − cached input

Applied to the summed token counts from the runs above:

ColBench (N = 20, all tasks summed)

line item	sliceagent	OpenAI Codex
fresh input	140,403 × $1.25/M = $0.176	330,719 × $1.25/M = $0.413
cached input	143,125 × $0.125/M = $0.018	429,719 × $0.125/M = $0.054
output	24,265 × $10/M = $0.243	8,786 × $10/M = $0.088
total	$0.436	$0.555

Self-designed long-horizon (N = 3, summed)

line item	sliceagent	OpenAI Codex
fresh input	347,238 × $1.25/M = $0.434	2,293,552 × $1.25/M = $2.867
cached input	1,866,752 × $0.125/M = $0.233	24,075,264 × $0.125/M = $3.009
output	63,372 × $10/M = $0.634	355,365 × $10/M = $3.554
total	$1.301	$9.430

One honest wrinkle worth naming: Codex's append-only transcript actually earns a higher cache-hit rate (57% vs 50% on ColBench, 91% vs 84% here) — a long stable prefix caches well. It still costs more, because its raw input volume is an order of magnitude larger; a cheaper per-token rate can't outrun many more tokens. That's the whole point of the slice: fewer tokens to bill in the first place.

Line items are rounded to the nearest $0.001; each total is the exact sum of unrounded per-token costs, and matches the cost row in the tables above.

The pattern across all four is evidence for the history-bounded-cost thesis in these scenarios: capability held while per-turn cost tracked the current task rather than accumulated history. The same pattern extended to subagent orchestration. "Solved" is solution correctness, scored identically for both agents. ColBench is public; the long-horizon scenarios are reproducible under benchmarks/.

These are early, small-scale results — modest task counts (N = 32 / 20 / 3 tasks; §4 is one task × 3 runs), single trial per task, one model, one opponent. Treat them as a directional signal, not a settled claim. We're actively expanding to larger and more varied test sets, more trials, and more baselines, and will update these numbers as that work lands.

Install & quickstart

One command — Linux, macOS, WSL2:

curl -fsSL https://raw.githubusercontent.com/TT-Wang/sliceagent/main/install.sh | sh

Windows — one command in PowerShell, fully native (no WSL, no admin):

irm https://raw.githubusercontent.com/TT-Wang/sliceagent/main/install.ps1 | iex

(Installs uv + sliceagent, and Git Bash + ripgrep if you don't have them — the agent's shell commands run under Git Bash, same as other coding agents. Persistent process and interactive PTY tools are optional and disabled by default everywhere; AGENT_ADVANCED_TOOLS=1 enables them where supported, but terminal_open is not available on native Windows yet. Prefer WSL2? The Linux one-liner above works there as-is.)

The installer handles everything: uv, its own Python 3.12, ripgrep, and sliceagent — in an isolated tool env, no sudo, no prerequisites, no conflict with any Python you already have (conda base at 3.10? Rosetta-Intel conda on an M-series Mac? Doesn't matter). Then just:

sliceagent          # first run drops you straight into guided setup, then start chatting

Setup happens once, in-process: pick a provider, paste your API key (shown as ******, live-tested), and it writes ~/.sliceagent/config.toml (0600) so every later run just starts. Re-configure anytime with /config in-session or sliceagent init. There is no default model — sliceagent never picks one for you.

Alternative: install from PyPI yourself (you manage the Python — needs ≥ 3.11)

uv tool install --python 3.12 "sliceagent[tui]"     # uv — fetches Python itself
pipx install "sliceagent[tui]"                      # pipx
pip install "sliceagent[tui]"                       # plain pip (use a venv)

Native evidence, Active Work, history, and typed knowledge are included in the base install. The sliceagent[tui,memory] extra adds optional Memem; when its structured-index protocol is available (Memem 2.10+), SliceAgent uses it as primary L2 retrieval and falls back to native search on a whole-query failure. Older Memem versions are reported as unavailable for this protocol rather than used as an unscoped recall tail. Typed record truth and @sliceagent/ durability remain available without it.

If pip refuses with Requires-Python >=3.11: conda create -n sliceagent python=3.12 -y && conda activate sliceagent, then pip install. Prefer env vars over the wizard? Export both LLM_API_KEY and AGENT_MODEL (plus LLM_BASE_URL for non-OpenAI endpoints). ripgrep is recommended (code search degrades gracefully without it).

Updating

For installs created by the one-line installer:

sliceagent update

The command updates only when it can positively identify SliceAgent's isolated uv tool environment; it never replaces an editable checkout or guesses at a manager-owned environment. On Windows, exit SliceAgent and follow the external process guidance it prints. If your installed version predates sliceagent update, re-run the one-line installer; the installer is deliberately safe to re-run.

Self-managed installs stay self-managed: uv tool upgrade sliceagent, pipx upgrade sliceagent, or python -m pip install --upgrade "sliceagent[tui]" (or sliceagent[tui,memory] when using Memem). Source checkouts should pull first, then run uv sync --all-extras.

Footprint is light (no torch), and pip install -e . works for a clone. Distribution is currently through the one-line installers and PyPI; no Homebrew formula or prebuilt SliceAgent container image is advertised. Docker is available separately as the optional POSIX/WSL2 command-sandbox backend. → Full walkthrough in QUICKSTART.md.

Usage

Run sliceagent in your project and type what you want in plain language. It rebuilds its working context, investigates, edits, and can run your tests to verify. Ordinary requested work proceeds without permission prompts; only a narrow high-confidence catastrophic-command safeguard can refuse execution. A turn looks like:

❯ why does retry_with_backoff drop the last attempt? fix it

  │ 1 search · 2 read  retry.py, tests/test_retry.py
  │ write retry.py
  │ plan 2/3 · add a regression test
  ◌ 2/3 add a regression test · Running pytest -q · 00:12
  │ run pytest -q
  │   38 passed
  │ agent note · The focused regression now passes.
  ─ assistant ───────────────────────────────────────────────

    The loop exits on `attempt == max` before the final
    sleep+retry, so the last attempt never runs. Changed the
    bound to `attempt <= max` and added a regression test.

  ───────────────────────────────────────────────────────────
  ✓ turn saved · plan 3/3 · 2 passes · 4 read · 1 edit · 1 cmd · 00:18

Attach a file or path to your message with @: @src/errors.py explain the backoff.

In-session commands (type /help for the full list):

Command	What it does
/config · /model	add/switch providers · switch model / reasoning effort (persists)
Esc	revert the last edit(s)
/cwd [path]	show the workspace; with a path, atomically switch it without restarting the UI or model client
/cost	tokens and estimated $ spent this session
/skills · /tools · /mcp · /plugins · /agents	list what's available to the agent
/threads · /resume	switch between, or resume, parked topics
/learn <note>	save a durable lesson yourself
/plan	show open work items · /plan <objective> starts read-only plan mode (below)
/update	show the safe process-boundary update command
Ctrl-C · exit	interrupt the turn · quit

Public / palette: /config · /model · /cwd · /learn · /plan · /cost · /update · /threads · /resume · /plugins · /mcp · /skills · /tools · /agents · /help · /exit. The typed compatibility aliases /reasoning, /undo, and /switch remain accepted, but stay out of the palette because /model, Esc, and /resume are their clearer public spellings.

Plan mode is a sticky, host-enforced read-only planning regime. Start it with /plan <objective> — or with a leading plan <objective> and no slash (plan refactor the cache layer); commentary like "plan looks good" is guarded and never arms it. While armed, the agent explores with read-only tools and writes the plan as work items, each carrying its acceptance contract (verify + done_when). Plan mode stays on across turns until you approve or leave: reply with a whole-message approval — go, go ahead, do it, execute, approved, lgtm (开始 / 执行 also work) — to unlock full tools and execute, or type /plan off to exit without executing. /plan on arms the mode without a turn; bare /plan only shows the open work items.

File mentions accept exact workspace paths such as @app/jobs/[id]/page.tsx; quote paths containing spaces, for example @"docs/my guide.md".

Prefix an unrelated request with New task: to start it with fresh task state while parking the current task for /resume. Ambiguous follow-ups deliberately continue the active task so context is never discarded on a guess.

It can edit code in the primary workspace and grounded focus roots (reversible with /undo), run regular shell commands through a sandbox (local by default, docker for container isolation on POSIX/WSL2), search the tree and the web, and delegate self-contained sub-tasks with spawn_agent(agent=<kind>, task=…) to a fresh one-shot child that runs its own history-bounded, task-elastic slice and returns one trusted report. Built-in kinds are the read-only explorer, the writable general worker, reviewer, and verification; your own agents/*.md definitions are always loaded alongside them. Native Windows uses the local backend; run SliceAgent inside WSL2 if you want the Docker backend. Delegation depth defaults to 1 (children cannot spawn children); raise AGENT_SUBAGENT_DEPTH only if you intentionally want nesting. AGENT_ADVANCED_TOOLS=1 opts in persistent process and interactive terminal tools. Ordinary work runs directly from the user's request; the host retains only a narrow safeguard against high-confidence catastrophic shell commands. Secrets are scrubbed from anything persisted or logged.

Every clean or interrupted agent task turn is sealed into the always-on local artifact/checkpoint path. Subagent reports return directly to the parent in launch order; when optional artifact persistence succeeds, they also gain durable re-readable locators. The model reads exact evidence, project history, Active Work, and typed knowledge through the permanent read-only @sliceagent/ namespace in every workspace. @sliceagent/memory/status.md is the bounded general summary; raw host-counted inventory lives separately at @sliceagent/memory/diagnostics.md for explicit diagnostic requests. Compatibility counts are not layer sizes or an L2 backlog. Memem is primary semantic retrieval when enabled; task recovery and typed record truth do not depend on it.

Automatic knowledge push is lifecycle- and revision-aware: stale or dependency-drifted PROJECT observations and resolved diagnostic reports remain explicitly searchable, but do not reappear as if they described the current workspace. USER preferences and reusable CRAFT procedures do not decay merely because time passed.

If a timeout or disconnect leaves an operation's side effects uncertain, SliceAgent records that uncertainty durably and shows it to the model as grounding on later turns. It can re-observe relevant live state before making claims, but the receipt does not block ordinary work, task switching, undo, or workspace navigation. Ambiguous recovery journals still stop startup before plugins or MCP processes run because that boundary protects the integrity of the durable local store rather than interpreting user intent.

Configuration. sliceagent config --list prints every setting. Set them persistently in ~/.sliceagent/config.toml (written by init), or override any one via an environment variable:

Setting	Default	Purpose
AGENT_MODEL	(required)	the model id to run
AGENT_SANDBOX	local	local, or docker on POSIX/WSL2 (native Windows: use local or run under WSL2)
AGENT_MAX_STEPS	120	per-turn step ceiling
AGENT_CONTEXT_WINDOW	(catalog or unset)	explicit provider window for strict per-call preflight; unknown models otherwise use compatibility mode
AGENT_SUBAGENT_DEPTH	1	delegation depth ceiling for spawn_agent; 0 disables delegation, raise to let children spawn children
AGENT_DELEGATION_TIMEOUT	900	per-child inactivity window in seconds, reset by child and transport activity
AGENT_DELEGATION_ABSOLUTE	3600	absolute child leak guard in seconds; cannot be disabled
LLM_HARD_TIMEOUT_SEC	(completion-budget derived)	absolute per-call watchdog; provider-agnostic default allows the configured completion cap at a conservative generation rate (minimum 180s)
LLM_STREAM_CLOSE_GRACE_SEC	2	bounded wait to prove a cancelled/timed-out SSE request physically closed before any retry
LLM_PROVIDER_MAX_INFLIGHT	4	process-wide physical request cap per provider account; indeterminate calls hold their slot until the transport closes
AGENT_ADVANCED_TOOLS	(off)	enable persistent process and interactive terminal tools
SLICEAGENT_CACHE_DIR	~/.sliceagent	always-on local checkpoints, immutable artifacts, and recovery journals
SLICEAGENT_VAULT	~/.sliceagent/vault	legacy episodic/task compatibility records (not canonical typed L2)
AGENT_VERIFY_CMD	(unset)	test command used as the verification oracle

DeepSeek official-API configurations should move from the retiring deepseek-chat / deepseek-reasoner aliases to deepseek-v4-flash or deepseek-v4-pro. SliceAgent keeps the old names temporarily compatible, but new provider setup and model suggestions use the V4 names.

License

MIT — see LICENSE. Third-party components and their licenses are listed in NOTICE. Security policy + threat model: SECURITY.md.

Acknowledgements

sliceagent's design was informed by two excellent open-source agents: Hermes Agent (MIT) and Kimi Code. A few peripheral utilities are ported from Hermes (see NOTICE); most of the rest are patterns we studied and reimplemented on our own terms. memem provides primary semantic retrieval for SliceAgent-owned typed L2 knowledge when the memory extra is installed. Its value/primary-index/cue representation was also informed by Microsoft Memora (MIT). Neither is another brain layer, and local artifacts and recovery do not depend on them. With thanks to their authors.

Contact

Questions, feedback, or ideas — open an issue or reach out: tongtao.wang@gmail.com. (Security reports: please follow SECURITY.md instead.)