Observability proxy for Claude Code — see what's happening between Claude and the Anthropic API.

What is Aspy?

Aspy sits between Claude Code and the Anthropic API, intercepting all traffic and giving you visibility into tool calls, thinking blocks, token usage, and costs. Run it as a TUI proxy, integrate via MCP, or install the Claude Code plugin.

What It Does

• Real-time TUI — Watch tool calls, thinking blocks, and API responses as they stream
• Token & cost tracking — Cumulative session statistics with per-model pricing
• Thinking capture — Dedicated panel showing Claude's reasoning in real-time
• Structured logs — JSON Lines format for analysis with jq
• Multi-client routing — Track multiple Claude Code instances through one proxy
• REST API & MCP — Programmatic access to session data

Get Started

Option 1: TUI Proxy (Binary)

Download from GitHub Releases or build from source:

cargo install --git https://github.com/omgpointless/aspy

Run the proxy:

# Windows
.\aspy.exe

# macOS/Linux
./aspy

Point Claude Code at it:

# In a new terminal
export ANTHROPIC_BASE_URL=http://127.0.0.1:8080
claude

Optionally: MCP Server

Add aspy to Claude Code's MCP servers:

claude mcp add aspy -- npx -y aspy-mcp

This gives Claude Code access to:

• Current session: aspy_stats, aspy_events, aspy_context
• Lifetime history: aspy_recall, aspy_lifetime (semantic + keyword search)
• Context recovery: Search past thinking blocks, prompts, and responses across all sessions

Note: Requires the TUI proxy running to collect data.

Optionally: Claude Code Plugin

Install the plugin for slash commands:

/plugin marketplace add omgpointless/aspy

After restarting Claude Code, use /aspy:stats to query session metrics. The plugin also includes automatic cargo fmt hooks for Rust projects.

Demo Mode

Try the TUI without Claude Code:

ASPY_DEMO=1 ./aspy

Generates mock events to showcase the interface.

Documentation

Topic	Description
Features	Deep dive into all capabilities
Quick Start	Step-by-step setup walkthrough
CLI Reference	Commands, config options, env vars
Log Analysis	jq queries for session profiling
Themes	32 bundled themes + custom TOML
Multi-Client Routing	Track multiple Claude instances
REST API	Programmatic endpoints
Semantic Search	Configure embeddings for hybrid search
Request Transformers	Edit XML tags, inject context conditionally
API Translation	Use Claude Code with any OpenAI-compatible backend
Architecture	For contributors

Package Managers

Homebrew, Scoop, and Chocolatey packages will be available when the project stabilizes.

About

Maintainer's first Rust project. Learning journey together with Claude Code which is the whole reason I built this tool to start with.

License

MIT