Quick Start¶

Get Perspt running in 5 minutes.

Prerequisites¶

Rust 1.82+	rustup.rs for building from source
API Key	From any provider (OpenAI, Anthropic, Google, etc.) OR Ollama for local models

Installation¶

From Source (Recommended)

git clone https://github.com/eonseed/perspt.git
cd perspt
cargo build --release

Cargo Install

cargo install perspt

With Ollama (No API Key)

# Install Ollama
brew install ollama  # macOS

# Start and pull a model
ollama serve
ollama pull llama3.2

Set Your API Key¶

# Choose your provider
export OPENAI_API_KEY="sk-..."        # OpenAI
export ANTHROPIC_API_KEY="sk-ant-..." # Anthropic
export GEMINI_API_KEY="..."           # Google Gemini

Run Your First Chat¶

# Start the TUI (auto-detects provider from env)
./target/release/perspt

# Or with a specific model
perspt chat --model gemini-pro-latest

Type your message and press Enter. Press Esc to exit.

Try Agent Mode¶

Let the experimental SRBN agent autonomously plan and build multi-file projects:

# Create a project in a new directory
perspt agent -w ./my-calculator "Create a Python calculator package with
add, subtract, multiply, divide. Include type hints and pytest tests."

# Auto-approve all changes (headless)
perspt agent -y -w ./my-api "Build a REST API in Rust with Axum"

# Use specific models per tier
perspt agent \
  --architect-model gemini-pro-latest \
  --actuator-model gemini-3.1-flash-lite-preview \
  -w ./project "Create an ETL pipeline in Python"

The SRBN engine will:

Detect — Identify language plugins and workspace state
Plan — Architect decomposes task into a DAG with ownership closure
Generate — Actuator emits multi-file artifact bundles per node
Verify — LSP diagnostics + tests compute Lyapunov energy V(x)
Converge — Retry with grounded error feedback until V(x) < epsilon
Sheaf Check — Validate cross-node consistency
Commit — Record stable state in Merkle ledger

Choose Your Mode¶

Mode	Command	Best For
Chat TUI	`perspt` or `perspt chat`	Interactive conversations with markdown rendering
Agent	`perspt agent "<task>"`	Autonomous multi-file code generation (experimental)
Simple Chat	`perspt simple-chat`	Scripting, pipelines, no TUI
Status	`perspt status`	Check current agent session

Essential Commands¶

# Configuration
perspt config --show           # View current config
perspt config --edit           # Edit in $EDITOR
perspt init --memory --rules   # Initialize project

# Agent management
perspt status                  # Current session status
perspt abort                   # Cancel current session
perspt resume --last           # Resume last interrupted session

# Change tracking
perspt ledger --recent         # View recent changes
perspt ledger --rollback abc   # Rollback to commit
perspt ledger --stats          # Session statistics

# Debugging
perspt logs --tui              # Interactive log viewer
perspt logs --last             # Most recent session
perspt logs --stats            # Usage statistics