Introduction to Perspt

Perspt is an interface designed to bring the capabilities of Large Language Models (LLMs) directly and reliably into your terminal. Rather than treating artificial intelligence as a disconnected web service, Perspt integrates LLMs into your daily development workflow, offering three distinct interaction surfaces: Simple Chat, TUI, and Agent.

Whether you need to quickly ask a question using command-line pipelines, converse interactively in a rich terminal interface, or delegate complex multi-file engineering tasks to a team of specialized agents, Perspt provides a unified, structured, and stable environment for developer-AI collaboration.

The Three Surfaces of Perspt

Perspt operates across three primary surfaces, each designed for a different type of developer workflow:

1. Simple Chat Mode (``simple-chat``): A lightweight, streamable command-line interface. It is designed to converse with an LLM and integrate seamlessly with Unix bash pipelines. You can quickly pipe files, logs, or command outputs directly into the model to request a response, and redirect the LLM’s output to other command-line utilities. This makes it an ideal tool for shell scripting, fast code analysis, and automated diagnostics.

2. Interactive TUI Mode (``chat``): A rich, full-screen Terminal User Interface (TUI) built on ratatui. It provides an interactive conversational interface with the LLM right on your terminal. The TUI supports real-time streaming, markdown rendering with syntax highlighting, inline LaTeX math equations, keyboard-driven navigation, and prompt history. It allows you to explore ideas, ask code questions, and interactively write code without leaving your terminal workspace.

3. Agent Mode (``agent``): A governed tool loop in which an actuator model proposes typed tool calls, optionally assisted by a cheaper read-only explorer and a no-tool diff adjudicator, to solve complex software engineering and coding jobs. It models development tasks as work graphs and uses the Stabilized Recursive Barrier Network (SRBN) framework to ensure reliability and workflow stability. By integrating with local tests, compilers, and linters, Agent Mode automatically detects, corrects, and verifies code updates, ensuring the repository moves systematically toward a clean, working state.

The Problem of Guessing (Reliability via Verification)

To understand why Perspt is designed this way, consider the challenge of writing complex code. Every time a language model suggests code, it is making a guess. Because language models are non-deterministic and lack internal verification loops, even a tiny error in a single guess can propagate across files. Left to run on its own without external guidance, an agentic system will quickly drift away from a working codebase, culminating in compilation failures and broken tests.

In the spirit of Leslie Lamport’s work on distributed systems, where consensus must be reached among potentially faulty or unpredictable nodes, Perspt does not trust the model to self-verify. Instead, it wraps the model in a deterministic control loop. The system:

• Validates every proposed change using local type-checkers, compilers, and test suites.

• Measures errors as a scalar value (the Lyapunov energy).

• Feeds specific compiler and test diagnostics back to the LLM to guide corrections.

• Commits changes to the code repository only when the workspace is stable and error-free.

Perspt implements this discipline through the SRBN orchestrator.

Core System Features

We summarize the capabilities of the system in terms of their operational invariants:

Invariant	Operational Specification
Multi-Provider Hub	Establishes unified client communication with OpenAI, Anthropic, Gemini, Groq, Cohere, XAI, DeepSeek, Vertex AI, and local Ollama instances.
LSP Verification	Connects directly to language-server protocols (including rust-analyzer, pyright, and typescript-language-server) to extract syntactic diagnostics.
Test Automation	Integrates with local test runtimes (such as pytest and Cargo) to compute logic error metrics.
Role Specialization	Routes model calls by role: the Actuator proposes governed tool calls, an optional Explorer performs read-only repository lookahead, and an optional Adjudicator vetoes diffs without tools; the [models] table additionally routes architect, verifier, and speculator turns.
Policy Sandbox	Restricts process execution via a Starlark-based policy engine, preventing command execution or file mutation outside the workspace boundaries.
Resource Budgeting	Halts execution when the token count, USD cost, or round count exceeds strict safety bounds.
Terminal Interface (TUI)	Renders unified diff views, hierarchical task trees, and live telemetry dashboards within a terminal-based interface.
Web Telemetry	Streams real-time heatmaps, state-graph topologies, and LLM diagnostics to a browser-based visualization dashboard.

Theoretical Foundation of SRBN

The Stabilized Recursive Barrier Network (SRBN) is derived from the Stability is All You Need paper series. The framework treats LLM-based software modification as a trajectory stabilization problem. By wrapping the generative model inside a deterministic verification barrier, we convert an unconstrained random walk into a guided descent toward a stable state.

Key theoretical results from the papers include:

• Input-to-State Stability (ISS): Mathematical proofs demonstrating that bounded reasoning errors from the model result in bounded deviations in the system state.

• Flow Matching Barriers: Projection operators that take a diverging, erroneous state trajectory and map it back onto the safe manifold.

• Logarithmic Reliability Scaling: A prediction that the expected number of correction attempts scales logarithmically (\(O(\log N)\)) with the size of the target codebase \(N\), rather than decaying exponentially as in unbarriered systems.

The chart below illustrates this conceptual scaling difference:

Conceptual error accumulation: unbarriered random walk vs. SRBN logarithmic bound.

The operational execution of this control loop is represented as follows:

SRBN Control Flow

System Architecture

The Perspt system is constructed as a workspace of fourteen crates. The dependencies and responsibilities are partitioned as follows:

• The User Interface: Handled by perspt-cli (command parsing) and perspt-tui (terminal rendering).

• The Core Engine: Handled by perspt-core (provider abstractions and types), perspt-agent (the orchestration loop), and perspt-store (session databases).

• The Security Envelope: Handled by perspt-policy (Starlark checks) and perspt-sandbox (isolated execution environments).

• The Monitoring Plane: Handled by perspt-dashboard (web interface).

• The Reusable SDK: Handled by perspt-sdk, perspt-coding, perspt-research, and perspt-prompt-macros (compile-time typed prompt sections).

• The Evaluation Harness: Handled by perspt-benchmark (optional, feature-gated, run manually only).

The separation between perspt-sdk and domain packages (like perspt-coding) ensures that the mathematical control loop remains independent of specific execution environments. The same SDK stabilizes both code repositories and academic research projects.

The current implementation executes the PSP-9 governed tool loop end to end: every model-issued tool call is a proposal decided by the deterministic kernel, and the measured acceptance gate reads the re-measured candidate. No legacy orchestrator remains.

System Command Index

The application interface is accessed via the following commands:

Command	Function	Invocation Example
chat	Launches the interactive terminal UI (default).	perspt chat --model gemini-3.1-pro
simple-chat	Launches a streamable CLI interface without terminal styling.	perspt simple-chat
agent	Launches autonomous agent mode.	perspt agent "Create a parser in Rust"
init	Instantiates memory files and policy rule structures.	perspt init --memory --rules
config	Displays or writes configuration values.	perspt config --show
ledger	Queries the Merkle state history.	perspt ledger --recent
status	Returns session metrics and active energy values.	perspt status
abort	Signals an active agent session to terminate.	perspt abort
resume	Resumes the most recently interrupted session.	perspt resume --last
audit	Ingests delayed audit labels for conformal calibration.	perspt audit <sample> --safe
providers	Prints the provider capability matrix, optionally live-probed.	perspt providers --probe
replay	Replays a session’s audit record deterministically, without credentials.	perspt replay <session-id>
db repair	Quarantines a poisoned DuckDB WAL after durable backups.	perspt db repair --db-path perspt.db --discard-wal
prompts	Inspects and maintains the compiled prompt section libraries.	perspt prompts list
context	Explains a session’s recorded resident-context events.	perspt context explain-turn --db-path perspt.db <session-id>
benchmark	Runs the optional evaluation suites (feature-gated; manual only).	perspt benchmark run --suite smoke
dashboard	Launches the web monitoring server.	perspt dashboard

Supported Oracles and Providers

The client library accepts nine provider identifiers through the genai transport; OpenAI-compatible endpoints (including Azure and local servers) route through the openai adapter with a custom base URL:

Provider / Adapter ID	Target Env Variable	Reference Models
OpenAI / compatible (openai)	OPENAI_API_KEY (+ OPENAI_BASE_URL)	gpt-4o-mini, custom-model
Anthropic (anthropic)	ANTHROPIC_API_KEY	claude-3-5-sonnet-20241022
Google Gemini (gemini/google)	GEMINI_API_KEY	gemini-3.1-flash-lite-preview, gemini-3.1-pro
Google Vertex AI (vertex)	GCP ADC (VERTEX_PROJECT_ID)	vertex::gemini-2.5-flash, vertex::gemini-3.5-flash-lite
Groq (groq)	GROQ_API_KEY	llama-3.1-8b-instant
Cohere (cohere)	COHERE_API_KEY	command-r-plus
xAI (xai)	XAI_API_KEY	grok-beta
DeepSeek (deepseek)	DEEPSEEK_API_KEY	deepseek-chat
Ollama (ollama)	None (local port)	llama3.2, qwen2.5-coder

Any other provider string is rejected as unsupported. For detailed setup guides and provider-specific details, please see Providers.

System Philosophy

The keyboard hums, the screen aglow,

AI’s wisdom, a steady flow.

Through SRBN’s loop, stability we find,

Code that works, refined and aligned.

—The Perspt Manifesto

Perspt is built upon five design principles:

• Accessibility: A single command must establish communication with any supported model.

• Verification: Code is not committed until it passes deterministic verification checks.

• Determinism: Transitions and rollback events must be event-sourced to ensure reproducibility.

• Safety: Execution limits must be enforced via sandboxes and policy modules.

• Modularity: The engine components must remain separated into reusable crates.