Simplicio Architecture & Developer Documentation

⚡ What is Simplicio?

Traditional AI coding assistants dump entire directory trees and raw source files directly into model prompts. This burns hundreds of thousands of tokens, saturates LLM context windows with hallucination-inducing noise, and runs slow external Python scripts that risk corrupting files during uncoordinated multi-agent tasks.

Simplicio fundamentally redesigns AI software engineering:

📦 Fast Installation

Install the verified standalone native binary with a single terminal command:

$ curl -fsSL https://simpleti.com.br/simplicio/install.sh | sh

PS> irm https://simpleti.com.br/simplicio/install.ps1 | iex

$ python3 -m pip install --upgrade simplicio-installer
$ simplicio install

⏱️ First 60 Seconds

Get your first task running in under a minute:

# 1. Verify your installation
$ simplicio version

# 2. Orient and index your repository
$ cd my-project
$ simplicio onboard

# 3. Connect Simplicio MCP to your editors (Claude, Cursor, VS Code, Zed)
$ simplicio mcp register

# 4. Launch the local interactive assistant
$ simplicio

🔄 The 6-Stage Deterministic Pipeline

Every user request traverses a strictly governed, contract-enforced pipeline designed to prevent hallucination, token exhaustion, and unsafe file writes:

🗺️ simplicio map: Zero-Bloat Orientation

Instead of streaming raw file contents into model context, simplicio map scans the repository in milliseconds using native multi-threaded file traversal, parses public symbol definitions, and compiles an import dependency graph.

# Generate a structured JSON map for LLM consumption
$ simplicio map --repo . --json

# Query symbol dependencies in high-performance graph
$ simplicio map query "AuthService" --repo .

What this gives you: The coordinating model receives the structural architectural blueprint of your project in ~1.5k tokens rather than blowing through 120k tokens of raw text.

🎯 simplicio context: Prompt Budgeting

Once target files or functions are identified, simplicio context packages only the necessary AST snippets, bounded strictly by the configured model capacity.

# Retrieve mathematically bounded context for a query
$ simplicio context "billing checkout webhook" --json

✍️ simplicio edit: Zero-Hallucination Edits

One of the biggest failure modes in AI coding is the "rewrite whole file" or "fuzzy diff" failure. Simplicio enforces mechanical atomicity:

• Exact Replacements: Target text must match the source file byte-for-byte.
• Relative Inserts: Precision insert_before and insert_after anchors.
• Atomic Deletions: Clean deletion of obsolete code blocks without collateral damage.
• Pre-Image Verification: The target file's SHA-256 is checked before any byte is modified. If the file was changed concurrently, the patch fails closed and rolls back instantly.

# Execute an atomic multi-file plan with rollback safety
$ simplicio edit --plan plan.json --review

🌊 simplicio loop: Wave DAG Orchestrator

For complex multi-step sprints and batch tasks (>3 items), Simplicio executes the native WaveOrchestrator:

• Stratified Wave Planning: The task dependency DAG is stratified into sequential waves of concurrent stages.
• Tokio JoinSet Dispatcher: Independent read and test stages run in parallel bounded by semaphore permits.
• Deterministic Reconciliation Barrier: As asynchronous tasks complete, results and audit journals are reduced in monotonic, sorted Stage ID order.
• Lease Management: Stages hold exclusive leases during execution, with automatic timeout and retry budget classification.

⚡ Hardware Governor & CPUExecutor

Unlike unmanaged agent frameworks that trigger fork bombs and freeze your workstation, Simplicio operates under an Adaptive Capacity Governor:

$ simplicio parallelism --json

🤖 Multi-Agent Flow: Governed Elasticity

Simplicio introduces the CPU-First Agent Policy:

• Single Coordinator Default: Tasks execute under 1 primary coordinator. No uncontrolled fan-out.
• VirtualPointer Efficiency: Over 95% of delegated subagents operate as lightweight in-process asynchronous tasks (Tokio pointers) rather than heavy OS subprocesses. Consumes ~3MB RAM instead of 300MB.
• Elastic Scale up to 32 Agents: If the model explicitly requests subagents, capacity expands elastically up to 32 logical agents, subject to host CPU and memory headroom.
• Dynamic Backpressure: If host CPU load exceeds 80% or RAM exceeds 85%, new subagents are enqueued (queued) rather than spawned, keeping the machine fluid and responsive.

🔌 Model Context Protocol (MCP) Integration

Simplicio integrates natively as an MCP server with Claude Code, Cursor, VS Code, Zed, and JetBrains:

$ simplicio mcp register

Manual Configuration (claude_desktop_config.json / settings.json)

{
  "mcpServers": {
    "simplicio": {
      "command": "simplicio",
      "args": ["serve", "--mcp", "--stdio"]
    }
  }
}

Exposed Native Tools:

• simplicio_map: Bounded structural orientation.
• simplicio_context: Token-budgeted snippet retrieval.
• simplicio_edit: Atomic mechanical patch applicator.
• simplicio_loop: Wave orchestrator driver for multi-file sprints.
• simplicio_parallel: Real-time governor metrics and capacity inspection.

💻 Canonical CLI Reference

🔐 Local-First Security & Enterprise Privacy

• No Silent Exfiltration: Only explicitly bounded prompt fragments chosen by your workflow are transmitted to your configured model provider.
• Audit Receipts: Every mechanical patch outputs a JSON receipt with SHA-256 pre and post hashes, execution time, and process logs.
• Air-Gapped Ready: Simplicio functions completely offline with local models (llama.cpp / Ollama) without internet connectivity.

❓ Frequently Asked Questions