Install · Login · MCP · Features · Benchmarks · Website
🌍 Languages:
🇬🇧 English |
🇧🇷 Português |
🇪🇸 Español |
🇫🇷 Français |
🇯🇵 日本語 |
🇰🇷 한국어 |
🇨🇳 简体中文 |
🇮🇹 Italiano |
🇷🇺 Русский |
🇵🇱 Polski |
🇮🇳 हिन्दी |
🇸🇦 العربية |
🇮🇱 עברית |
🇲🇾 Bahasa Melayu |
🇮🇩 Bahasa Indonesia
Simplicio is a terminal AI coding agent — a single binary that replaces your entire AI-assisted development workflow: chat, code generation, repository context, planning, local multi-agent orchestration (64 → 600 agents), and evidence-backed PR delivery.
Runs on your machine. Your code never leaves your control. Remote models are optional, not required.
🔥 Save up to 96% of tokens on controlled workloads. Simplicio records the baseline and proof type; the actual result depends on the task and model.
The official installers download one canonical asset from the latest Runtime release, verify its SHA256 checksum and Ed25519 signature, validate the Runtime release contract, and require an active Simplicio account. They do not clone sibling repositories, install the embedded Python projects with pip, or modify Codex configuration unless SIMPLICIO_INSTALL_CODEX=1 is explicitly set.
curl -fsSL https://raw.githubusercontent.com/wesleysimplicio/simplicio/master/install.sh | shpowershell -c "irm https://raw.githubusercontent.com/wesleysimplicio/simplicio/master/install.ps1 | iex"The default install location is ~/.local/bin/simplicio on macOS/Linux and
%USERPROFILE%\.local\bin\simplicio.exe on Windows. Add that directory to
your PATH if the installer prints a PATH warning, then open a new terminal.
The installer intentionally does not pin a release. Every normal installation
and update resolves GitHub's latest release, verifies it, and keeps the
existing user data. To use another install directory:
SIMPLICIO_BIN_DIR="$HOME/.local/bin" \
sh -c "$(curl -fsSL https://raw.githubusercontent.com/wesleysimplicio/simplicio/master/install.sh)"PowerShell supports the equivalent SIMPLICIO_BIN_DIR setting. Keep checksum
verification enabled. Only set
SIMPLICIO_ALLOW_UNVERIFIED=1 when you have deliberately accepted an
unverified artifact and understand the supply-chain risk.
The resolved latest release must contain the six Python projects in the binary, enable Google login, and ship the configured public key plus signed update artifacts. The installer refuses to finish when any of these requirements, checksums, or the release manifest is missing. A Runtime source build or a private candidate is not a substitute for a published, verifiable release.
Check the installation:
simplicio --version
simplicio version --json
simplicio ecosystem doctor --json
sh install.sh --doctor # when running from a checkoutMaintainers: the exact manual order for building, signing, tagging, publishing, and verifying a public release is documented in docs/RELEASE_RUNBOOK.md.
The doctor command is read-only. Uninstalling is idempotent; the default keep-data mode removes the installed binary and preserves ~/.simplicio:
sh install.sh --uninstall --keep-data # macOS/Linux
sh install.sh --uninstall --purge # removes Simplicio state; preserves ~/.simplicio/.envpwsh install.ps1 -Uninstall -KeepData # Windows
pwsh install.ps1 -Uninstall -Purge # removes Simplicio state; preserves .envFor non-interactive purge, set SIMPLICIO_CONFIRM_PURGE=1 explicitly. The
installer never edits PATH profiles or removes provider credentials from .simplicio/.env.
The Runtime is the intended distribution boundary. A compliant release embeds
the real Python source trees and a Runtime bridge for Mapper, Dev CLI, Loop,
Fast, Prompt, and Sprint. They remain Python projects; they are not rewritten
as Rust, and a normal installation must not download their repositories or
install them with pip.
Use simplicio version --json and simplicio ecosystem doctor --json after
every update to confirm that the resolved latest release contains the embedded
projects and active distribution contract.
Simplicio uses a Google-backed device login. The CLI receives revocable Simplicio tokens; your Google password is entered only on Google. Login is required before product commands, MCP, and the ecosystem integration can be used.
Public beta access may be free, but beta does not bypass the active-entitlement check. When beta access ends, the entitlement must come from an active subscription.
A completed login remains usable for 30 days through the rotating refresh token.
The Runtime stores that revocable state at ~/.simplicio/login.json, outside the
executable, so reinstalling or upgrading to another release does not require a
new Google login. The official installers preserve this file; an explicit
--purge is the only installer mode that removes it. To use another location,
set SIMPLICIO_AUTH_FILE consistently before logging in and before upgrading.
On a compatible release, the installer starts the login flow when no active session exists. To start it manually:
simplicio login googleThe CLI prints a verification URL and a short device code, then waits. Open the URL in a normal browser, choose Continue with Google, and finish the Google authentication or passkey prompt. Do not paste the device code, Google password, access token, refresh token, or client secret into an issue, chat, terminal log, or public repository.
For scripts that need machine-readable polling output:
simplicio login google --jsonThe website flow is also available at
simpleti.com.br/simplicio/login.
Confirm only the state, not the full credential payload:
simplicio auth status --jsonThe successful result must report an enabled identity, an active login state,
and an allowed entitlement. If it reports status: disabled or any inactive
state, the session is not usable. Do not treat a zero process exit code alone
as proof of authentication; inspect the structured fields.
To revoke the local session:
simplicio logout --jsonLogout removes the local session; it does not delete your Simplicio account or subscription.
MCP (Model Context Protocol) is the interface that lets an AI client discover and call Simplicio's governed local tools. The client supplies intent and structured arguments; the Simplicio Runtime performs repository mapping, memory recall, deterministic edits, validation, and execution under its authentication and safety gates. MCP is an invocation surface, not a second installation of Mapper, Loop, or the other projects.
The Runtime exposes these tools:
| Tool | Purpose |
|---|---|
simplicio_map |
Build a compact structural map of a repository |
simplicio_memory |
Recall indexed project memory (FTS/vector backends) |
simplicio_edit |
Apply a structured, deterministic file-edit plan |
simplicio_gate |
Check mission/effect gates before a mutation |
simplicio_validate |
Run contract-oriented validation for a task |
simplicio_run |
Execute a governed task through the Runtime |
simplicio_symbol |
Navigate symbols and declarations |
simplicio_search |
Search repository content semantically/structurally |
simplicio_read |
Read files through the compact Runtime surface |
simplicio_exec |
Run a supervised, compact external command |
The client should call tools/list at startup and use the returned schemas;
the table above is a quick orientation, not a substitute for live schemas.
Codex integration is opt-in. A normal installation does not modify Codex configuration or hooks. To enable the versioned, reversible integration:
SIMPLICIO_INSTALL_CODEX=1 sh install.shWhen enabled, the installer configures Codex to launch the installed binary directly:
[mcp_servers.simplicio]
command = "/path/to/simplicio"
args = ["serve", "--mcp", "--stdio"]This keeps MCP execution local and avoids the latency of the local HTTP daemon.
The Runtime still enforces Google login and entitlement for every MCP session.
The installer also merges Simplicio SessionStart, UserPromptSubmit,
SubagentStart, and PreToolUse hooks into ~/.codex/hooks.json; existing
Codex hooks are preserved and the Simplicio entries are updated idempotently.
The PreToolUse route is mandatory: native host reads, edits, shell commands,
and directory exploration are denied; use Simplicio MCP. Lifecycle events also
start a bounded map -> fast context warm-up in the background.
The managed hooks are versioned with the release, and repeated setup is
idempotent. Review the result in Settings → Hooks and verify the MCP command
with:
codex mcp listTo repair the integration, rerun the installer with
SIMPLICIO_INSTALL_CODEX=1. The managed integration has a separate
status/install/uninstall/repair helper in scripts/codex_integration.py; user
data remains separate from the integration. Original config.toml and
hooks.json files are kept in .simplicio.bak copies on the first managed
write. There is no environment-variable escape hatch; rerun the installer to
repair a missing or stale route.
For Claude Code, Cursor, VS Code, Cline, Continue, and similar clients, add a server entry using the installed binary:
{
"mcpServers": {
"simplicio": {
"command": "simplicio",
"args": ["serve", "--mcp", "--stdio"]
}
}
}Typical configuration locations are:
| Client | File |
|---|---|
| Claude Code | ~/.claude/settings.json |
| Cursor | ~/.cursor/mcp.json |
| VS Code | .vscode/mcp.json |
| Cline | ~/.config/cline/mcp_settings.json |
| Continue | ~/.continue/config.json |
Reload the client after saving its configuration. STDIO is local and does not need a manually copied bearer token, but the Runtime still requires an active Simplicio login.
Smoke-test the local server:
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \\
| simplicio serve --mcp --stdioThe response should contain the ten tool definitions. If the command says login is required, authenticate first; do not disable the gate or insert a token into a config file.
AI client → tools/list / tools/call
→ Simplicio Runtime auth + entitlement gate
→ map / memory / edit / validate / exec surface
→ structured result + evidence
For the complete client matrix and protocol notes, see
MCP-CONNECT.md.
This public repository also publishes the Simplicio Claude Code marketplace:
/plugin marketplace add wesleysimplicio/simplicio
/plugin install simplicio-loop@simplicio
/plugin install simplicio-prompt@simplicio
/plugin install simplicio-sprint@simplicio
The plugin bundle is documented in PLUGIN.md. These are optional
Claude Code skill surfaces; they are not proof that the Runtime binary contains
the ecosystem sources. When present, the skills call the Runtime through
simplicio serve --mcp --stdio.
The up to 96% figure is a headline maximum measured on controlled workloads that combine repository mapping, memory recall, deterministic edits, local routing, and local fan-out. It is not a promise that every task or model will save 96%. The component percentages below are directional measurements; they must not be added together.
| Mechanism | Reference result | What is measured |
|---|---|---|
| 🗺️ Repo map | ~70% less context | Compact structural context versus raw file reads |
| 🧠 Memory recall | ~80% less re-derivation | Reused indexed facts versus rediscovering them |
| ✏️ Deterministic edit | 100% LLM output avoided | Structured file mutation without a generation step |
| 🏠 Local routing | ~90% fewer remote tokens | Classification/low-risk work handled locally |
| 📡 Remote routing | ~85% fewer remote tokens | Remote models used for planning and hard decisions |
| 🔀 Local fan-out | ~95% fewer cloud-agent tokens | Local agents used before cloud escalation |
| Combined controlled workload | up to 96% | Baseline-to-Simplicio total token comparison |
Every measured run should report its proof type and its baseline:
saved = baseline_tokens - actual_tokens and
saving_percent = saved / baseline_tokens * 100.
All Runtime benchmark commands require an active login because they execute through the governed Runtime:
simplicio benchmark run --sample --json # deterministic fixture rows
simplicio benchmark run --json # measured Runtime timings
simplicio benchmark savings --json # savings-oriented summaryFor a real model/provider comparison, keep the task, repository snapshot, model, temperature, and cold/warm state constant. Record the baseline and the Simplicio run separately. Replace the example counts below with the actual provider-reported values:
simplicio savings record \
--spent 120 \
--baseline 300 \
--source codex \
--task "map, recall, edit, and validate a small change" \
--proof-kind measured
simplicio savings report --repo . --json
simplicio savings prove --repo . --jsonUse measured only when the provider reports actual usage. Use benchmark for
fixed fixture runs, replayed for a reproducible recorded run, and
estimated only for a heuristic. Never present an estimated result as a
measured benchmark. To compare a captured run with an explicit baseline:
simplicio savings compare \
--with-simplicio .simplicio/runs/<run-id> \
--without-simplicio baseline.json \
--proof-kind measuredThis public repository also benchmarks its release consistency checker. It is separate from AI token savings:
python3 scripts/bench_verify_distribution_consistency.pyThe reference run used for this README was 25 iterations on the maintainer's
macOS ARM64 machine: median 4.158 ms, versus the committed baseline of
11.625 ms, within the default +150% regression budget. Wall-clock values
vary by machine and CI runner; the command and pass/fail threshold are the
portable result.
The stricter distribution benchmark is:
python3 scripts/benchmark_distribution.py --repetitions 5It intentionally refuses to publish a metric when the distribution audit has warnings. A warning is a release-hygiene failure, not evidence of a token saving. Inspect the audit before retrying:
python3 scripts/verify_distribution_consistency.py| Command | Description | Cost/effect |
|---|---|---|
simplicio runtime map --repo . --for-llm markdown |
Maps a repository for an LLM | Compact context |
simplicio memory query "query" --json |
Recalls indexed project memory | Reuses known facts |
simplicio edit --plan plan.json --repo . |
Applies a deterministic edit plan | No generation step |
simplicio validate "task" --repo . |
Runs contract-oriented validation | Deterministic gates |
simplicio run "task" --repo . --agents N |
Runs a governed multi-agent task | Local-first routing |
simplicio sprint sprint.md --repo . --evidence |
Executes a sprint with evidence | Auditable delivery |
simplicio benchmark run --sample --json |
Runs fixed benchmark fixtures | Reproducible rows |
| 🪨 Caveman | 🔧 RTK | 🔥 Simplicio | |
|---|---|---|---|
| Approach | Output style compression | Shell command proxy | Full agent runtime |
| Published scope | Output-token reduction | Shell-command output reduction | End-to-end controlled workloads |
| Input compression | ❌ | ✅ (filtered) | ✅ Repo map + neural memory |
| Output compression | ✅ (caveman-speak) | ❌ | ✅ Zero-token deterministic edits |
| Local LLM | ❌ | ❌ | ✅ Built-in llama.cpp |
| Multi-agent | ❌ | ❌ | ✅ 64 → 600 local agents |
| Memory across sessions | ❌ | ❌ | ✅ FTS + vector recall |
| Evidence chain | ❌ | ❌ | ✅ sha256 sealed receipts |
| Language | JS/Python (skill) | Rust (binary) | Rust (single binary) |
| License | MIT | Apache 2.0 | Proprietary |
These tools measure different surfaces, so this repository does not claim an apples-to-apples Caveman/RTK benchmark. Caveman reduces how much an agent says; RTK reduces command output; Simplicio also reduces repeated context and deterministic mutation work. Use the reproducible commands in the benchmark section when comparing a real workload.
LLM (Claude/Codex/Gemini) Simplicio Runtime
| |
| 1. Orient | runtime map / MCP
| 2. Recall | memory query / MCP
| 3. Decide |
| 4. Edit ───────────────────────> | structured edit
| 5. Verify <───────────────────── | validate / evidence
| 6. Iterate | run / sprint
The LLM reasons. Simplicio executes deterministically.
- 🏠 Local-first — built-in llama.cpp, scales to remote only when needed
- 🪜 Tiered agents — 64 → 100 → 200 → 600 local agents before paid cloud
- 🔇 Shannon novelty gate — filters redundant outputs (zero tokens on dedup)
- 🔒 Sealed receipts — sha256 per artifact, tamper-proof evidence chain
- 🛡️ 5 delivery gates — acceptance, validation, run-verify, regression, self-review
- ⚡ Action gate — risk classification + blocklist for chat-initiated mutations
- 🔌 MCP/ACP — Model Context Protocol + Agent Client Protocol
- 🌐 Gateways — Telegram, Discord, Slack, WhatsApp
- 🧩 Skill system — loads and chains reusable capabilities
- 💾 Memory DB — persistent FTS + vector recall across sessions
- 🔀 LLM router — no LLM → local LLM → remote LLM automatically
- 🖥️ Cross-platform — macOS, Linux, Windows, single binary
Re-running the official installer is the simplest update path. It downloads
the latest release, verifies the SHA256 checksum and Ed25519 signature, validates
the Runtime release contract, preserves ~/.simplicio/login.json, and keeps
the remaining ~/.simplicio user data. Re-running the
installer keeps the installation on GitHub's latest release. The installer refuses
to replace a working binary with a release that lacks the embedded bundle,
Google login activation, a configured update key, or a verifiable signature.
When the Runtime's background update checks are enabled, it checks in its scheduled windows, notifies once per release, stages the verified asset, and applies it on the next session. The current release channel is checksum verified. If the latest executable reports a missing public update key or an unsigned channel, that mismatch is a release blocker, not a reason to disable verification.
The Runtime also exposes an authenticated update surface:
simplicio update check --json
simplicio update apply --json
simplicio update status --json
simplicio update rollback --jsonUse rollback only when you have a verified previous release and understand
the compatibility trade-off. After any update, repeat:
simplicio --version
simplicio version --json
simplicio ecosystem doctor --json
simplicio auth status --json
codex mcp listCommon failures:
| Symptom | Resolution |
|---|---|
login required |
Run simplicio login google; confirm active: true. |
| Codex does not show Simplicio tools | Restart Codex, inspect Settings → Hooks, and verify codex mcp list points to serve --mcp --stdio. |
tools/list is empty or stale |
Restart/reload the MCP host and verify its command resolves to the intended simplicio binary. |
| Runtime release contract fails | Wait for a release with embedded sources, enabled Google login, and a configured public update key; do not bypass the gate. |
| Google says the browser is not secure | Use a normal Safari/Chrome window for the Google step, not an embedded webview; never disable the account security gate. |
| A command behaves differently across terminals | Run which simplicio, simplicio --version, and inspect PATH for an older binary. |
Useful diagnostic commands:
simplicio doctor --json
simplicio self-test --json
simplicio status --json
simplicio security --jsonWhen reporting a problem, include the operating system, architecture,
simplicio --version, the redacted output of simplicio auth status --json,
and simplicio version --json plus simplicio ecosystem doctor --json.
Remove email addresses, device codes,
authorization headers, and every credential before sharing logs.
Deterministic commands are FREE forever:
map, validate, edit, deliver, checkpoint
AI features may be free while the public beta flag is active. Login and an active entitlement are still required; when beta access ends, the entitlement must come from an active subscription.
simplicio license status| Requirement | Minimum | Recommended |
|---|---|---|
| RAM | 8 GB | 16 GB+ |
| Storage | ~35–50 MB for the release binary | 1.5 GB+ with a local LLM |
| OS | macOS Apple Silicon and Intel, Linux x64, Windows x64 | macOS ARM64 and x64 |
| Python | Not required for the embedded Runtime projects | Current CPython 3 for optional external adapters |
| Browser | Safari, Chrome, or another supported browser for Google login | Current Safari/Chrome |
| Terminal | any modern terminal | WezTerm / Alacritty / Ghostty |
This repo ships committed release binaries plus the packaging/tooling around them (npm/PyPI wrappers, install scripts, a distribution-consistency checker). The official command to run that tooling's unit test suite:
pip install -r requirements-dev.txt
python -m pytest tests/unit -v --cov=scripts --cov-report=term-missing --cov-fail-under=85
python3 scripts/bench_verify_distribution_consistency.py
python3 scripts/verify_distribution_consistency.pySee docs/testing-strategy.md for what's covered,
what's intentionally out of scope, and the plan for the rest of the testing
epic. The consistency audit may report release-hygiene warnings even when the
unit suite is green; resolve all release warnings before treating the stricter
benchmark_distribution.py gate as a release pass. See also
CONTRIBUTING.md.
The root Runtime distribution and its release artifacts are proprietary. The binary is free to download and use during the public beta; AI feature access still requires an active Simplicio entitlement. Plugin subdirectories may carry their own license files and terms.
- Discord — chat, support, early access
- GitHub Issues — bugs and feature requests
🔥 Simplicio — Your code, your machine, up to 96% fewer tokens on controlled workloads. 🔥