Getting Started¶

This guide walks through installation, first chat, and first agent run.

Prerequisites¶

System Requirements¶

Component	Requirement
Operating System	Linux, macOS, or Windows
Rust Toolchain	Rust 1.82.0 or later
Terminal	Any modern terminal emulator with UTF-8 support
Network	Required for cloud LLM API calls (not needed for Ollama)

API Keys¶

You need an API key from at least one provider. Set it as an environment variable and Perspt will auto-detect the provider:

# Pick one — Perspt auto-detects from the environment
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GEMINI_API_KEY="..."

# Ollama needs no key — just run: ollama serve

Note

Auto-detection priority: OpenAI > Anthropic > Gemini > Groq > Cohere > XAI > DeepSeek > Ollama.

Quick Installation¶

From Source (Recommended)

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

Cargo Install

cargo install perspt
perspt --version

Binary Download

curl -L https://github.com/eonseed/perspt/releases/latest/download/perspt-linux-x86_64.tar.gz | tar xz
chmod +x perspt && sudo mv perspt /usr/local/bin/

Your First Chat¶

TUI mode (default) provides a rich terminal interface with markdown rendering:

export GEMINI_API_KEY="your-key"
perspt

You will see a chat interface. Type a message and press Enter. Perspt streams the response in real time with markdown formatting. Press Esc to exit.

Simple CLI mode is a minimal text interface suitable for scripting:

perspt simple-chat
# Or with logging
perspt simple-chat --log-file session.txt

Type your question, get a streamed answer. Type exit or press Ctrl+D to quit.

Your First Agent Run¶

Agent mode (experimental) lets the SRBN engine plan and write multi-file projects autonomously:

# Create a new Python package
perspt agent -w ./demo-calc \
  "Create a Python calculator package with add, subtract, multiply, divide.
   Include type hints, a pyproject.toml, and pytest tests."

What happens:

Detection — Perspt identifies Python from the task description, selects the python plugin (ty LSP, pytest runner, uv init --lib).
Planning — The Architect model decomposes the task into a DAG of nodes, each owning specific output files (ownership closure rule).
Execution — Nodes execute in topological order. For each node, the Actuator generates a multi-file artifact bundle (writes, diffs, commands).
Verification — LSP diagnostics compute V_syn, pytest computes V_log, and bootstrap commands compute V_boot. Total energy V(x) is checked.
Review — In interactive mode, a diff viewer presents changes for approval. In headless mode (--yes), all changes are auto-approved.
Commit — Stable nodes are recorded in the Merkle ledger.

After completion, inspect the output:

ls demo-calc/
# pyproject.toml  src/  tests/  uv.lock

cd demo-calc && uv run pytest -v

Headless Mode¶

For CI/CD or batch workflows, use --yes to skip all interactive prompts:

perspt agent --yes -w ./output "Build a Rust CLI that converts CSV to JSON"

Combine with --defer-tests for faster iteration (skips V_log during coding, only runs tests at the final sheaf validation stage):

perspt agent --yes --defer-tests -w ./output "Build a data pipeline"

Switching Models¶

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

# Agent with per-tier models
perspt agent \
  --architect-model gemini-pro-latest \
  --actuator-model gemini-3.1-flash-lite-preview \
  --verifier-model gemini-pro-latest \
  --speculator-model gemini-3.1-flash-lite-preview \
  "Build a web scraper"