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 native Simplicio Desktop is being built publicly in
apps/desktop. It uses Tauri 2 as a thin, capability-scoped
shell around the separately supervised Simplicio Runtime. The first public
Desktop download will replace the existing Desktop channel only after signed
macOS and Windows artifacts pass the clean-machine, entitlement, provider,
update and rollback gates. Until that cutover, the current download entrypoint
remains unchanged.
See the Desktop architecture decision, product states, and provider contract.
If you use Codex, you can install Simplicio as a plugin. Add the public marketplace, install the plugin, and start a new Codex session; the plugin installs and bootstraps the Simplicio Runtime and exposes its skills and MCP tools.
codex plugin marketplace add wesleysimplicio/simplicio --ref master
codex plugin add simplicio@simplicio-codexThe official installers download one canonical asset from the latest Runtime release, verify its SHA256 checksum and Ed25519 signature, validate the Runtime release contract, and register MCP hosts to launch the installed binary directly. They do not clone sibling repositories or install the embedded Python projects with pip. Login can be completed after installation; MCP tool calls remain fail-closed until the account is active.
macOS / Linux:
python3 -m pip install --upgrade simplicio-installer
simplicio installWindows (PowerShell):
py -m pip install --upgrade simplicio-installer
simplicio installmacOS / Linux:
curl -fsSL https://raw.githubusercontent.com/wesleysimplicio/simplicio/master/install.sh | shWindows (PowerShell):
irm https://raw.githubusercontent.com/wesleysimplicio/simplicio/master/install.ps1 | iexThe PyPI package is the recommended bootstrap. It installs the launcher from PyPI, verifies the signed SHA256/Ed25519 Runtime release, and then installs the platform binary. It does not place a secret or token in the repository.
The PyPI launcher command is installed into Python's script directory. The
verified Runtime is placed at ~/.local/bin/simplicio on macOS/Linux or
%USERPROFILE%\.local\bin\simplicio.exe on Windows. Ensure the Python script
and managed Runtime directories are on PATH; the launcher does not edit shell
profiles.
The launcher resolves the release required by its package version, verifies the signed manifest and asset checksum, and preserves existing user data.
Known installer incidents and their regression sentinels are tracked in docs/INSTALL_ERROR_REGISTRY.md.
The PyPI launcher has no unverified-artifact bypass. The selected Runtime release must contain the signed manifest and a canonical asset for the host; the launcher aborts when either is missing or its checksum does not match. A Runtime source build or a private candidate is not a substitute for a published, verifiable release.
Check the installation:
simplicio version
simplicio auth login
simplicio auth status --json
simplicio ecosystem verify --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 auth loginThe 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 auth login --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.
A normal installation now invokes the installed Runtime's host registrar automatically. No opt-in environment variable or separately downloaded hook is required. The Runtime detects supported clients, writes the absolute managed binary path, preserves existing user configuration, and installs native hooks only on clients whose hook surface is implemented and verified.
Registration does not require an active Google session. Authentication is still validated when an MCP session uses protected Runtime capabilities. Restart each open client after installation so it reloads its MCP server and hook files.
MCP clients launch command directly, so do not use ~ and do not expect
shell expansion. The generated registration uses the following local STDIO MCP
shape for the current operating system.
Use forward slashes in TOML. Windows accepts them, and they avoid invalid TOML
escapes such as \\U in C:\\Users\\....
[mcp_servers.simplicio]
command = "C:/Users/YourName/.simplicio/bin/simplicio.exe"
args = ["serve", "--mcp", "--stdio"]
[mcp_servers.simplicio.env]
SIMPLICIO_MCP_URL = "http://127.0.0.1:8787/mcp"[mcp_servers.simplicio]
command = "/Users/your-name/.simplicio/bin/simplicio"
args = ["serve", "--mcp", "--stdio"]
[mcp_servers.simplicio.env]
SIMPLICIO_MCP_URL = "http://127.0.0.1:8787/mcp"[mcp_servers.simplicio]
command = "/home/your-name/.simplicio/bin/simplicio"
args = ["serve", "--mcp", "--stdio"]
[mcp_servers.simplicio.env]
SIMPLICIO_MCP_URL = "http://127.0.0.1:8787/mcp"The Runtime currently registers supported configurations for Codex, Claude Code/Desktop, Hermes, Cursor, Windsurf/Next, Kiro, Gemini, Trae, Antigravity, Junie, Cline, VS Code, Zed, and OpenCode. Existing files are merged idempotently. Codex and Claude receive their verified Runtime-owned native hook routes; other clients receive the supported MCP/rules integration.
To inspect or repair every detected integration manually, run:
simplicio mcp register --binary "$(command -v simplicio)" --jsonA failed automatic registration makes the installer fail clearly instead of claiming success. Clients not reported by the JSON result are not silently treated as configured.
The installer also writes the redacted multi-host detection/registration
receipt to simplicio-host-integrations.json beside the managed binary. See
docs/HOST_INTEGRATIONS.md for the supported
matrix, exact-probe policy, opt-outs, and receipt schema.
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, points at the
installed ~/.simplicio/bin/simplicio binary, and does not need a manually
copied bearer token. 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/bin/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
/plugin install simplicio-hermes@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 auth login; 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. 🔥