PARI — Next-Generation Terminal Coding Agent

A Synthesis Architecture That Surpasses Claude Code, OpenAI Codex, OpenCode, Pi, Aider, Cursor, and Google Antigravity.
(Named by a college friend, built for world-class systems engineering performance.)

⚡ The Core Thesis

$$\text{\bf Agent failure is a systems engineering failure, not a reasoning failure.}$$

The exact same frontier reasoning model (Claude 3.7 Sonnet, GPT-4o) demonstrates a 15% pass rate in a naive loop, but achieves a 50–55% pass rate inside an engineered harness. The 35% delta is not model intelligence; it is accounted for by six fatal systems failure modes:

1. Unbounded stdout poisoning $\rightarrow$ Solved by Layer 7 (50KB/2k-line disk spooler + balanced head/tail extraction).
2. Mid-stream token truncation $\rightarrow$ Solved by Layer 4 (Strict stop_reason == "length" rejection guard).
3. File write race conditions $\rightarrow$ Solved by Layer 6 (FileMutationQueue canonical realpath serialization).
4. KV cache invalidation cascades $\rightarrow$ Solved by Layer 2 (Immutable Baseline Epochs freezing Tiers 1–4).
5. Blind file traversal loops $\rightarrow$ Solved by Layer 3 (v1: Fast substring ripgrep & globbing / v2: Tree-sitter AST fallback).
6. Unsandboxed host execution $\rightarrow$ Solved by Layer 0 (Multi-platform kernel isolation: bwrap, Seatbelt, E2B MicroVMs).

🏗️ 11-Layer Architecture Topology

+-----------------------------------------------------------------------------------+
|                              PARI -- SYSTEM TOPOLOGY                              |
+-----------------------------------------------------------------------------------+
|  Layer 9:  TERMINAL INTERFACE (Rich / Textual differential rendering TUI)         |
|                                          |                                        |
|  Layer 8:  DUAL-MODEL ROUTER (Architect -> Planner / Editor -> Fast Model)        |
|                                          |                                        |
|  Layer 7:  OUTPUT HYGIENE (50KB/2k-line disk spooler + head/tail extraction)     |
|                                          |                                        |
|  Layer 6:  CONCURRENCY SAFETY (asyncio.TaskGroup + realpath FileMutationQueue)   |
|                                          |                                        |
|  Layer 5:  EDIT ENGINE (Exact -> Git OSR -> DMP -> Prefill Continue)             |
|                                          |                                        |
|  Layer 4:  AGENT EXECUTION LOOP (Double-while + stop_reason guard + tools)       |
|                                          |                                        |
|  Layer 3:  NAVIGATION (v1: Substring Grep & Globbing / v2: Tree-sitter Fallback)  |
|                                          |                                        |
|  Layer 2:  CONTEXT & CACHE (Immutable Epoch + mid-session updates + Warmer)      |
|                                          |                                        |
|  Layer 1:  DURABLE SESSION (Append-only JSONL Merkle DAG + Checkpoint Index)     |
|                                          |                                        |
|  Layer 0:  SANDBOX (bwrap on Linux/WSL2 + Seatbelt on macOS + E2B Cloud)         |
+-----------------------------------------------------------------------------------+

📚 Complete Documentation Suite

All system documentation has been modularized and organized inside the docs/ directory:

Architecture Deep Dives

• Architecture Overview — System topology, execution lifecycle, and core thesis.
• Failure Mode Atlas — Verified weaknesses across 7 production systems.
• The Trade-Off Framework — The 12 design trade-off axes and what PARI sacrifices.
• Cross-System Decision Matrix — Harvested innovations vs. discarded anti-patterns.

Layer Specifications

• Layer 0: Sandboxing Engine — Multi-platform kernel isolation (bwrap, Seatbelt, E2B).

• Layer 1: Durable Session Engine — Append-only JSONL Merkle DAG with $O(K)$ checkpoints.

• Layer 2: Context & Cache Architecture — Immutable Baseline Epochs & Economic Warmer.

• Layer 3: Codebase Intelligence & Navigation — v1 ripgrep & globbing / v2 Tree-sitter AST fallback.

• Layer 4: Agent Execution Loop — Double-while state machine & PTY daemon detection.

• Layer 5: Multi-Tier Fuzzy Edit Engine — 4-tier diff cascade (Exact $\rightarrow$ Git OSR $\rightarrow$ DMP $\rightarrow$ Prefill).

• Layer 6: Concurrency & File Safety — FileMutationQueue realpath locks & shadow worktrees.

• Layer 7: Output Hygiene — 50KB/2k-line spooler & structured traceback parsing.

• Layer 8: Dual-Model Routing Engine — Architect vs. Editor decoupling (85% cost reduction).

• Layer 9: Terminal Interface & TUI — Rich differential streaming & zero idle CPU drain.

• Layer 10: Evaluation & Observability — Local micro-eval suite & Cross-Model Verification.

Developer Guides

• Developer Pain Points & Solutions — Real developer frustrations and PARI's direct fixes.
• Getting Started Guide — Installation, environment setup, and running locally.
• Phased Build Roadmap — 12-week implementation timeline across four phases.

🚀 Installation & Quick Start

Choose your platform's one-line install command:

1. macOS & Linux (curl)

curl -fsSL https://raw.githubusercontent.com/MdTanwer/pari/main/install.sh | bash

2. Windows (irm in PowerShell)

irm https://raw.githubusercontent.com/MdTanwer/pari/main/install.ps1 | iex

3. Via pip / pipx / uv

# Recommended (isolated CLI)
pipx install pari-cli

# Fast via uv
uv tool install pari-cli

# Standard pip
pip install pari-cli

💻 Launch Interactive Session

# Export your API key
export ANTHROPIC_API_KEY="sk-ant-..."

# Launch PARI anywhere in your project workspace
pari

⚖️ License

MIT License. See LICENSE for details.