🔥 Simplicio — The AI Agent That SAVES UP TO 96% OF YOUR TOKENS

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 the latest Runtime release from this repository, verify the published SHA256 manifest, validate the embedded Python bundle, require an active Simplicio account, and attempt to register the local MCP endpoint. They do not clone or download the simplicio-* sibling repositories.

curl -fsSL https://raw.githubusercontent.com/wesleysimplicio/simplicio/master/install.sh | sh

powershell -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.

To pin a release or use another install directory:

SIMPLICIO_VERSION=v3.8.11 \
SIMPLICIO_BIN_DIR="$HOME/.local/bin" \
  sh -c "$(curl -fsSL https://raw.githubusercontent.com/wesleysimplicio/simplicio/master/install.sh)"

PowerShell equivalents are available through SIMPLICIO_VERSION and SIMPLICIO_BIN_DIR. Keep checksum verification enabled. Only set SIMPLICIO_ALLOW_UNVERIFIED=1 when you have deliberately accepted an unverified artifact and understand the supply-chain risk.

Check the installation:

simplicio --version
simplicio ecosystem verify --json
sh install.sh --doctor                 # when running from a checkout

The doctor command is read-only. Uninstalling is idempotent and preserves user data under ~/.simplicio:

sh install.sh --uninstall              # macOS/Linux
pwsh install.ps1 -Uninstall             # Windows

The Runtime is the distribution boundary. Each 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 does not download their repositories or install them with pip. The Runtime may use an available Python 3 interpreter to execute those embedded sources.

simplicio ecosystem verify --json reports the embedded component versions, source archive digest, provenance commits, and compatibility status. Run it after every update and attach its JSON to a bug report when an embedded component looks stale.

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 embedded ecosystem 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.

The installer starts the login flow when no active session exists. To start it manually:

simplicio login google

The 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 --json

The website flow is also available at simpleti.com.br/simplicio/login.

Confirm only the state, not the full credential payload:

simplicio auth status --json

The successful result must report active: true. If it reports active: false, the session may be missing, expired, revoked, or associated with an account without an active entitlement. Run simplicio login google again and confirm that the browser completed the same device flow. simplicio auth login is kept as a compatibility alias by installer-era builds.

To revoke the local session:

simplicio logout --json

Logout 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 embedded projects.

The Runtime exposes these tools:

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.

The installer runs simplicio mcp register, which registers the local Streamable HTTP endpoint used by Codex: http://127.0.0.1:8787/mcp.

1. Complete simplicio login google first.
2. Open Codex Settings → MCP.
3. Find the simplicio server and click Authenticate.
4. Complete the Google-backed Simplicio login in the browser.
5. Reload the MCP settings or restart the host if the tool list was already cached.

If the row is missing, register it again and reload Codex:

simplicio mcp register

The Runtime validates the bearer token and active entitlement on every MCP request. A visible Authenticate button is therefore expected for the OAuth-capable Codex server; it is not a replacement for the CLI login.

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:

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 --stdio

The 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 required to obtain the Runtime's embedded ecosystem. 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.

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 summary

For 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 . --json

Use 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 measured

This public repository also benchmarks its release consistency checker. It is separate from AI token savings:

python3 scripts/bench_verify_distribution_consistency.py

The 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 5

It 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

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 is idempotent: it downloads the latest release, verifies the checksum, validates the embedded bundle, and keeps ~/.simplicio user data. A pinned installer command updates only when you intentionally choose that version.

The Runtime also exposes an authenticated update surface:

simplicio update check --json
simplicio update apply --json
simplicio update status --json
simplicio update rollback --json

Use rollback only when you have a verified previous release and understand the compatibility trade-off. After any update, repeat:

simplicio --version
simplicio ecosystem verify --json
simplicio auth status --json
simplicio mcp register

Common failures:

Useful diagnostic commands:

simplicio doctor --json
simplicio self-test --json
simplicio status --json
simplicio security --json

When reporting a problem, include the operating system, architecture, simplicio --version, the redacted output of simplicio auth status --json, and simplicio ecosystem verify --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

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.py

See 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 those warnings before treating the stricter benchmark_distribution.py gate as a release pass. See also CONTRIBUTING.md.

• Website — product overview, benchmarks, install
• Discord — community and support

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. 🔥