Simplicio

Local-first AI coding agent and runtime that cuts up to 96% of the tokens per task. Single compiled binary, zero runtime dependencies.

🇧🇷 Versão em português: README.pt-BR.md · Official site: simpleti.com.br/simplicio/#start

---

Install in one line

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/wesleysimplicio/simplicio/main/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://raw.githubusercontent.com/wesleysimplicio/simplicio/main/install.ps1 | iex"

Then verify and start:

simplicio version
simplicio ecosystem doctor --repo . --json   # is the ecosystem contract healthy? (#2950)
simplicio chat --repo .

Full instructions for every platform (macOS, Linux, Windows, Docker, source) are in INSTALL.md. For the whole-ecosystem picture (what simplicio-mapper/simplicio-dev-cli/simplicio-loop are and how they relate to this runtime), see docs/SIMPLICIO_STACK.md.

---

Use it as an MCP server (plug it under any LLM host)

Simplicio runs as an MCP server that Claude Code, Gemini CLI, Codex, Cursor, VS Code, Zed, and more plug under — giving your assistant a governed, token-saving substrate instead of raw file access.

bash scripts/install-mcp.sh      # installs `simplicio`, registers the server, smoke-tests it
simplicio serve --mcp --stdio    # or run the server manually

Your assistant gets 10 deterministic tools: simplicio_map (orient) · simplicio_memory (FTS + vector recall) · simplicio_edit (sandboxed mechanical edit) · simplicio_gate (risk classify) · simplicio_validate · simplicio_run (gate → bridge → evidence) · simplicio_symbol (def + callers in one) · simplicio_search · simplicio_read (signature-level) · simplicio_exec (the full CLI, gated). The neural memory loads on first run and is always available; an update refreshes the core skills without touching what you've captured.

One runtime dependency for the memory layer: sqlite3 (apt-get install sqlite3 / brew install sqlite). The lean build needs no C/C++ toolchain.

Full guide: INSTALL_MCP.md.

---

Docker — quick start

# Official image (multi-arch: amd64 + arm64)
docker pull ghcr.io/wesleysimplicio/simplicio:latest

# Deterministic command (no model, no network):
docker run --rm \
  -v "$HOME/.simplicio:/home/simplicio/.simplicio" \
  -v "$PWD:/work" -w /work \
  ghcr.io/wesleysimplicio/simplicio:latest map --repo . --json

# Or via compose (gateway, agent, tui):
cp .env.docker.example .env
docker compose run --rm agent validate --repo .

Build, profiles, and publishing details: docs/PACKAGING.md.

---

What it is

Simplicio is a terminal-based AI coding agent and runtime. The frontier LLM orients and reviews; Simplicio supplies the cheap, deterministic muscle — repo mapping, neural memory recall, zero-token mechanical edits, action gating, quality gates, and tamper-evident evidence — so each task costs a fraction of the tokens it otherwise would.

• Chat REPL — conversational assistant over your repo
• Agent mode — multi-turn task execution with a sub-agent fabric
• Neural memory — SQLite/FTS5 recall (optional vector ANN) instead of re-reading files
• Deterministic editing — mechanical edits with zero LLM tokens
• Delivery gates — definition-of-done, certification, regression checks
• Deterministic Runtime — filesystem, evidence, gates, and MCP effects; provider/model execution remains owned by Simplicio Agent/Loop for now

The task surface is simplicio-runtime; the task discipline is inherited from the proven simplicio-loop flow. In practice that means simplicio run, simplicio serve --mcp --stdio, and assistant adapters reuse the same evidence-gated converge/drain model, durable run journal, and worker coordination pattern instead of inventing a second execution contract.

---

Inference ownership (current release)

The Runtime is shipped in deterministic-only mode. It does not start a local LLM, DeepSeek, OpenRouter, or any other provider, even when a model file, llama.cpp binary, or provider environment variable is present. This keeps the Code → Agent → Loop → Runtime boundary explicit and fail-closed.

The future local backend remains prepared behind the optional in-process-llm feature and the explicit SIMPLICIO_RUNTIME_INFERENCE=local-experimental mode. That mode is not enabled by default and is not part of the current release contract.

Use an Agent/Loop provider outside the Runtime when inference is needed.

Loop-stack economy benchmark (honest)

How simplicio-loop (with Fast inside STRICT), Agent MCP, and host baseline trade tokens vs wall clock — measured across five agent issues (#9 → #711), five lanes.

PDF (pizza charts · bar charts · barramento diagram · full interpretation):
docs/evidence/loop_stack_economy_benchmark_report.pdf

Raw metrics: docs/evidence/multi_issue_lanes_metrics.json

Lane	Mean est. token savings vs host baseline	Wall (mean)	Role
loop (mapper + Fast)	~39% (up to ~83% on large baselines)	~50 s cold	Production STRICT path
loop + Agent MCP	~38%	~53 s	Bus/tools — not the main compressor
loop without Fast	~64%	~18 s	Diagnostic only — less work
mcp_only	~99%*	~11 s	Metadata only — not a survey

*High % without survey work is not a product win. Runtime MCP (simplicio serve --mcp) is the host tool surface; Agent MCP is a separate bus. Both are optional for the loop core (mapper + dev-cli; Fast when operational). Runtime is not mandatory for simplicio-loop.

Also mirrored in simplicio-loop.

Documentation

Doc	Purpose
docs/SUPER_RUNTIME.md	North star — the Simplicio Super Runtime product boundary, design pillars, and token economy
docs/evidence/loop_stack_economy_benchmark_report.pdf	Measured loop/MCP/Fast economy report (charts + interpretation)
INSTALL.md	Install on any platform
docs/SIMPLICIO_STACK.md	The whole ecosystem on one page — every repo's role, naming/alias policy, recommended path (simplicio ecosystem doctor), what it's not, migration notes
docs/QUICKSTART.md	First agent in 5 minutes
docs/UPGRADE.md	Upgrade paths for every method
docs/TROUBLESHOOTING.md	Common errors and fixes
docs/CAPABILITY_CURATION.md	What to own, call, promote, or avoid — capability curation + dedup policy (issue #35)
BUILDING.md	Build from source (developers)

---

Quick taste

# Map your repo to save tokens before reasoning
simplicio map --repo . --for-llm markdown

# Recall prior decisions instead of re-deriving them
simplicio memory "how does auth work" --repo . --json

# Run a governed task through the runtime-first task flow
simplicio run "fix the failing test" --repo . --evidence --json

# Standalone loop surface for the same evidence-gated task discipline
simplicio coding-loop "fix the failing test" --repo . --max-cycles 5

# Quality gate before declaring done
simplicio deliver certify --repo . --json

Run simplicio --help for the full command list.

Asolaria Subsystem (JesseBrown1980 integration)

The src/asolaria/ module ports the highest-value patterns from JesseBrown1980's Asolaria ecosystem into the Simplicio Runtime. Restored 2026-07-08 (ADR-2026-07-08-ASOLARIA-RESTORATION) and actively integrated 2026-07-09 (ADR-2026-07-09-ASOLARIA-INTEGRATION-SPRINT).

Wired and exercised (real code, tests passing):

• nest_prime.rs — N-Nest self-reflective agent nesting
• consolidator.rs — observation consolidation (decay/cluster passes)
• tiered_memory.rs — tiered memory store
• fedenv.rs / hookwall.rs — Federation-1024 policy + syscall-table stubs
• agent_state.rs — agent state persistence (SQLite)
• sealed_receipt.rs / cosign_chain → src/hbp/ shared ledger (sha256 hash-chain)
• wormhole_command.rs — holographic wormhole codec transport
• prism_bridge.rs / wormhole_bridge.rs — re-exports of dbbh-prism / wormhole-codec crates

Ports in progress (see ADR-2026-07-09):

• asolaria-hbi-hbp verify_chain → sealed_receipt.rs integrity
• ai-memory consolidation → consolidator.rs
• asolaria-federation-1024 council/lanes → fedenv.rs
• hbp::HbpInbox::append advisory lock (race fix — DONE)

Source repos cloned under ../jesse-imports/ for port reference.