Patina

A high-performance terminal client for the Claude API, written in Rust. Designed for developers who want a fast, secure, and extensible AI assistant in their terminal.

Highlights

• Sub-millisecond rendering - Full 100-message redraw in <1ms
• Multi-provider LLM support - Claude (Anthropic) and OpenRouter-compatible models with automatic failover
• Parallel tool execution - 5x+ speedup on multi-file operations
• Full MCP support - Connect any MCP server via stdio, streamable HTTP, or legacy SSE transports
• Autonomous agent orchestration - Spawn parallel sub-agents in isolated git worktrees
• Continuous coding loop - Run tasks autonomously with stagnation detection and quality gates
• 5,000+ tests with 85%+ code coverage
• Zero unsafe code - Pure safe Rust (~139,000 LOC)
• Cross-platform - Linux, macOS, Windows
• Security-first - Defense-in-depth with command filtering, path validation, and session integrity

Features

Core Capabilities

Autonomous Agents

Built-in Tools (25)

Extensibility

Developer Experience

Installation

From Source

git clone https://github.com/postrv/patina.git
cd patina
cargo install --path .

Quick Start

# Set your API key
export ANTHROPIC_API_KEY="your-api-key"

# Run patina
patina

# With an initial prompt
patina "Explain this codebase"

# Print mode (non-interactive)
patina -p "What is 2+2?"

# Resume last session
patina -c

# List saved sessions
patina --list-sessions

# Use OpenRouter instead of Anthropic
patina --provider openrouter --model anthropic/claude-sonnet-4

# Use AWS Bedrock
patina --provider bedrock --model claude-sonnet-4-20250514

# Use Google Vertex AI
patina --provider vertex --model claude-sonnet-4-20250514

Command Line Options

Key Bindings

Terminal-specific shortcuts:

Permission Prompts:

Plan Review (when model proposes a plan):

Question Prompt (when model asks a question):

Slash Commands (32)

All commands support tab completion -- start typing / and press Tab to see options.

MCP Support

Patina implements the Model Context Protocol for connecting external tool servers, built on the rmcp SDK for full spec compliance.

Transports

Configuration

MCP servers are configured via .mcp.json in your project root (compatible with Claude Code format):

{
  "mcpServers": {
    "narsil": {
      "command": "narsil-mcp",
      "args": ["--repo", "."],
      "env": {}
    },
    "jetbrains": {
      "type": "sse",
      "url": "http://localhost:63342/api/mcp/sse"
    },
    "remote-server": {
      "url": "https://example.com/mcp"
    }
  }
}

Global servers can be configured in ~/.claude.json under "mcpServers".

Transport Detection

• stdio: Entries with a command field spawn a child process
• Legacy SSE: Entries with "type": "sse" or a URL ending in /sse
• Streamable HTTP: Entries with a url field (default for HTTP)

Features

• Namespaced tools: Each server's tools are prefixed with servername__ to avoid collisions
• Parallel startup: All servers connect concurrently
• Auto-discovery: Tools from connected servers are automatically available to Claude
• OAuth & Bearer auth: Bearer token from environment variables, OAuth with token refresh and caching
• Security: Command validation and interpreter path requirements for stdio servers
• Trust management: Content-hash verification for project-level MCP configs
• Graceful degradation: Failed servers don't block startup; other servers continue normally

Security

Patina implements defense-in-depth security controls:

See SECURITY.md for security policy and reporting vulnerabilities.

Configuration

Configuration directories:

• Linux/macOS: ~/.config/patina/

Project Context (CLAUDE.md)

Place a CLAUDE.md file in your project root to provide project-specific instructions. Patina automatically discovers:

• CLAUDE.md (project root)
• .patina/CLAUDE.md (framework config)
• */CLAUDE.md (subdirectories)

Plugins

Plugins extend Patina with custom tools, commands, skills, and hooks.

Plugin Management CLI:

# Install from local directory
patina plugin install ./my-plugin

# List installed plugins
patina plugin list

# Update all plugins
patina plugin update

# Remove a plugin
patina plugin remove my-plugin

Example Plugin Manifest:

# rct-plugin.toml
name = "my-plugin"
version = "1.0.0"
description = "My custom plugin"
author = "Your Name"

[capabilities]
commands = true   # Provides slash commands
skills = true     # Provides skills
tools = true      # Provides tools for the agent
hooks = false     # No lifecycle hooks
mcp = false       # No MCP server

See plugins/template/ for a minimal plugin template to get started.

Performance

Benchmarks (Criterion, 120x40 terminal):

Parallel Tool Execution

Tools are classified by safety:

• ReadOnly: read_file, glob, grep, web_fetch, web_search (parallelized)
• Mutating: write_file, edit (sequential)
• Unknown: bash, MCP tools (sequential by default)

cargo bench
# HTML reports in target/criterion/

Architecture

Patina uses an event-driven architecture with a priority-ordered handler dispatch system:

src/
├── main.rs           # CLI entry point
├── app/              # Event loop, dispatcher, and handlers
│   ├── state.rs      # Application state
│   ├── context.rs    # Handler context (shared state bundle)
│   ├── dispatch.rs   # Priority-ordered event dispatcher
│   └── handlers/     # Focused event handlers (9 + 1 observer)
│       ├── permission# Tool approval prompts
│       ├── plan      # Interactive plan review
│       ├── question  # User question prompts
│       ├── completion# Slash command tab-completion
│       ├── keyboard  # Input, copy/paste, selection
│       ├── stream    # API streaming events
│       ├── agent     # Sub-agent lifecycle
│       ├── continuous# Autonomous loop control
│       ├── tick      # UI refresh, throbber animation
│       └── session   # Session persistence (observer)
├── api/              # LLM providers (Anthropic, OpenRouter, Bedrock, Vertex, fallback)
├── tui/              # Terminal UI (ratatui), image display, transcript search
├── tools/            # Tool execution, security, parallel execution, sandbox
├── mcp/              # MCP client (rmcp SDK): config, connection, manager
├── hooks/            # Lifecycle events
├── skills/           # Context-aware suggestions
├── commands/         # Slash command parsing
├── agents/           # Worktree-based agent orchestration
├── plugins/          # Plugin system
├── session/          # Session persistence
├── context/          # Context management, compression, token budgeting
├── worktree/         # Git worktree management
├── permissions/      # Permission management
├── auth/             # Authentication (API key, optional OAuth)
├── enterprise/       # Audit logging, cost tracking, managed settings
├── update/           # Auto-update checking
└── types/            # Core types

Development

# Run tests
cargo test

# Run clippy
cargo clippy --all-targets -- -D warnings

# Check formatting
cargo fmt -- --check

# Run with coverage
cargo tarpaulin --out Html

# View debug logs (TUI mode writes to file)
tail -f /tmp/patina.log

Technical Details

Key Dependencies

Library API

Patina can be used as a Rust library for building custom AI-powered tools.

Available Modules

Example: Custom Tool Loop

use patina::api::AnthropicClient;
use patina::types::{Message, Role, StreamEvent};
use secrecy::SecretString;

#[tokio::main]
async fn main() {
    let client = AnthropicClient::new(
        SecretString::from("your-api-key"),
        "claude-sonnet-4-20250514",
    );

    let (tx, mut rx) = tokio::sync::mpsc::channel(100);
    let messages = vec![Message {
        role: Role::User,
        content: "Hello!".to_string(),
    }];

    client.stream_message(&messages, tx).await.unwrap();

    while let Some(event) = rx.recv().await {
        match event {
            StreamEvent::ContentDelta(text) => print!("{}", text),
            StreamEvent::MessageStop => break,
            _ => {}
        }
    }
}

Documentation

• Architecture - System design and data flow
• API Reference - API client documentation
• Plugin API - Plugin development guide
• Security Model - Security architecture
• User Guide - Usage documentation

Contributing

1. Fork the repository
2. Create a feature branch
3. Ensure all quality gates pass (cargo test, cargo clippy, cargo fmt)
4. Submit a pull request

See CONTRIBUTING.md for detailed guidelines.

License

MIT OR Apache-2.0

Copyright (c) 2026 Laurence Avent

Author

Laurence Avent (@postrv)