What is Peri?

Peri is a terminal AI Agent written in Rust — not an API gateway, not a chatbot, but a complete programming assistant that reads files, runs commands, searches code, and spawns sub-agents.

What It Does

Peri runs on a ReAct loop: receive your question → think → call tools → observe results → keep thinking, until the task is done.

12 core tools are always visible to the LLM:

Tool	Purpose
Read / Write / Edit	Read, write, and precisely replace files
Glob / Grep	Find files by pattern, search content by regex
folder_operations	Create, list, and check directories
Bash	Execute terminal commands
WebFetch / WebSearch	Fetch web pages, search the internet
Agent	Spawn sub-agents for sub-tasks
AskUserQuestion / TodoWrite	Ask the user questions, maintain task lists

Additionally, MCP tools, Cron tools, and others are loaded on-demand via Tool Search, keeping the LLM context lean.

Relationship with Claude Code

Peri is compatible with the .claude/ directory structure. If you're already using Claude Code:

File/Directory	Peri's Handling
.claude/agents/*.md	Auto-scanned as available Agent definitions
.claude/skills/*.md	Progressively injected into the system prompt
.claude/settings.json	Permissions and MCP config read
CLAUDE.md / AGENTS.md	Injected as project-level guidance

This means you can use Peri in existing Claude Code projects without modifying any configuration.

Comparison with Other Terminal Agents

	Peri	Claude Code	Aider
Language	Rust	TypeScript	Python
Memory Usage	~50MB	~200MB	~100MB
.claude/ Compatible	✅	✅	❌
Sub-Agents	✅ fork + background	✅	❌
Middleware System	✅ Programmable	❌	❌
LLM Support	OpenAI + Anthropic	Anthropic	Multiple
TUI Interface	✅ Ratatui	✅ Ink	❌
IDE Integration	✅ ACP Protocol	✅ LSP	❌

Project Structure

peri/
├── peri-agent/        # Core: ReAct loop, middleware chain, LLM interface, Thread persistence
├── peri-middlewares/   # Built-in middleware: filesystem, terminal, web, sub-agent, Tool Search, etc.
├── peri-tui/          # TUI application, CLI entry point
├── peri-acp/          # ACP service layer: SessionManager, Langfuse tracing
├── peri-widgets/      # TUI component library
├── peri-lsp/          # LSP client
└── langfuse-client/   # Langfuse observability client

System Requirements

• OS: macOS (Apple Silicon / Intel), Linux (x86_64 / aarch64 / riscv64), Windows (x86_64)
• Network: Access to LLM API endpoints (OpenAI-compatible or Anthropic)
• Optional: MCP servers, Langfuse instance, LSP server

Next Steps

• Quick Start — Install, configure, and start using in 5 minutes
• Extending with Middleware — Understand Peri's extension mechanism