---
slug: "aspy"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/omgpointless/aspy@main/README.md"
repo: "https://github.com/omgpointless/aspy"
source_file: "README.md"
branch: "main"
---
![Aspy (Anthropic Spy)](https://github.com/omgpointless/aspy/raw/HEAD/docs/images/aspy-logo-v4.png)

[![CI](https://github.com/omgpointless/aspy/actions/workflows/ci.yml/badge.svg)](https://github.com/omgpointless/aspy/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/omgpointless/aspy?include_prereleases)](https://github.com/omgpointless/aspy/releases)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![npm](https://img.shields.io/npm/v/aspy-mcp)](https://www.npmjs.com/package/aspy-mcp)

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

![Demo](https://github.com/omgpointless/aspy/raw/HEAD/demo.gif)

## 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](https://github.com/omgpointless/aspy/releases) or build from source:

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

Run the proxy:
```bash
# Windows
.\aspy.exe

# macOS/Linux
./aspy
```

Point Claude Code at it:
```bash
# 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:

```bash
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:

```bash
/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:

```bash
ASPY_DEMO=1 ./aspy
```

Generates mock events to showcase the interface.

## Documentation

| Topic | Description |
|-------|-------------|
| [Features](https://github.com/omgpointless/aspy/blob/HEAD/docs/features.md) | Deep dive into all capabilities |
| [Quick Start](https://github.com/omgpointless/aspy/blob/HEAD/QUICKSTART.md) | Step-by-step setup walkthrough |
| [CLI Reference](https://github.com/omgpointless/aspy/blob/HEAD/docs/cli-reference.md) | Commands, config options, env vars |
| [Log Analysis](https://github.com/omgpointless/aspy/blob/HEAD/docs/log-analysis.md) | jq queries for session profiling |
| [Themes](https://github.com/omgpointless/aspy/blob/HEAD/docs/themes.md) | 32 bundled themes + custom TOML |
| [Multi-Client Routing](https://github.com/omgpointless/aspy/blob/HEAD/docs/sessions.md) | Track multiple Claude instances |
| [REST API](https://github.com/omgpointless/aspy/blob/HEAD/docs/api-reference.md) | Programmatic endpoints |
| [Semantic Search](https://github.com/omgpointless/aspy/blob/HEAD/docs/semantic-search-guide.md) | Configure embeddings for hybrid search |
| [Request Transformers](https://github.com/omgpointless/aspy/blob/HEAD/docs/transformers.md) | Edit XML tags, inject context conditionally |
| [API Translation](https://github.com/omgpointless/aspy/blob/HEAD/docs/api-translation-guide.md) | Use Claude Code with any OpenAI-compatible backend |
| [Architecture](https://github.com/omgpointless/aspy/blob/HEAD/docs/architecture.md) | 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