# AISniff

[![npm version](https://img.shields.io/npm/v/aisniff.svg)](https://www.npmjs.com/package/aisniff)
[![license](https://img.shields.io/npm/l/aisniff.svg)](https://github.com/user/aisniff/blob/main/LICENSE)

> **See what your AI coding agents are actually doing.**

AISniff is a lightweight LLM API proxy that gives you real-time visibility into every request your AI coding tools send — payloads, SSE streams, token usage, cache metrics, tool calls, and multi-turn loops — all in a live web dashboard.

**One command to start. Zero config to sniff.**

```bash
npm install -g aisniff
aisniff                  # proxy on :8088, dashboard auto-opens
```

## Why AISniff?

When you use Claude Code, OpenCode, Codex, or Cline, you're sending prompts, code, and API keys to remote LLM services — with almost zero visibility into what's happening. AISniff fixes that:

- **No more blind API calls** — see full request/response payloads live
- **Track your spend** — token usage + cache metrics per call and per conversation loop
- **Debug agent behavior** — watch thinking, tool calls, and multi-turn loops as they happen
- **Auth stays safe** — API keys are forwarded but redacted in logs and dashboard
- **Works with any provider** — Anthropic, OpenAI, Gemini, Dashscope, or any HTTPS endpoint

## How It Works

```
  AI Coding Tools ──► AISniff (:8088) ──► LLM Services
 ┌───────────┐   ┌──────────────┐   ┌───────────────────┐
 │Claude Code│──►│              │──►│api.anthropic.com  │
 │ OpenCode  │──►│  proxy +     │──►│api.openai.com     │
 │  Codex    │──►│  dashboard   │──►│gemini.googleapis  │
 │  Cline    │──►│              │──►│dashscope / others │
 └───────────┘   └──────────────┘   └───────────────────┘
                     │
                     ▼
               /__dashboard
            (visualize logs & SSE)
```

AISniff sits between your AI tool and the LLM endpoint. It forwards requests unchanged while parsing SSE streams in-flight, logging structured data, and feeding a real-time web dashboard.

```
http://localhost:8088/anthropic/v1/messages      →  https://api.anthropic.com/v1/messages
http://localhost:8088/openai/v1/chat/completions  →  https://api.openai.com/v1/chat/completions
```

## Features

### Real-Time Dashboard

Open `http://localhost:8088/` (auto-opens on startup):

- **Full payloads** — every request and response, structured and searchable
- **Parsed SSE output** — not raw chunks; text, thinking, tool calls reconstructed into readable turns
- **Token tracking** — input/output tokens with cache creation and read metrics
- **Loop detection** — multi-turn conversations grouped with unique IDs
- **Route management** — add, edit, or delete routes from the dashboard with hot-reload

### Smart SSE Parsers

| Provider | API | What's Parsed |
|----------|-----|---------------|
| **Anthropic** | Messages SSE | Text, thinking (with signatures), tool_use/result, usage + cache metrics |
| **OpenAI** | Chat Completions SSE | Choices, content, usage |
| **OpenAI** | Responses SSE | Content, reasoning summaries, usage, error/cancelled |
| **Any endpoint** | Generic passthrough | JSON body logging, error summaries |

### Auto-Config for AI Tools

One click from the dashboard — no manual env vars needed:

| Tool | What It Configures |
|------|-------------------|
| **Claude Code** | `ANTHROPIC_BASE_URL` in `~/.claude/settings.json` |
| **OpenCode** | `baseURL` in `~/.opencode/opencode.json` |
| **Codex** | `base_url` in `~/.codex/config.toml` |
| **Cline** | `claude.apiEndpoint` in VS Code settings |

Click to wire, click again to restore the original endpoint.

## CLI

```bash
aisniff [options]          # full command
as [options]               # shortcut alias
```

| Flag | Description |
|------|-------------|
| `-p, --port <port>` | Port to listen on (default: 8088) |
| `--prefix <prefix>` | Route prefix (must start with `/`) |
| `--baseurl <url>` | Target base URL (pairs with preceding `--prefix`) |

```bash
aisniff                                                    # defaults, auto-open dashboard
aisniff -p 9090                                            # custom port
as --prefix /anthropic --baseurl https://api.anthropic.com  # single route
as --prefix /anthropic --baseurl https://api.anthropic.com \
   --prefix /openai --baseurl https://api.openai.com       # multi-route
```

CLI routes persist to `~/.aisniff/config.json` and survive restarts.

## Config & Logs

`~/.aisniff/config.json` is auto-created on first start. Routes are stored separately for auto-configured and manually added entries.

**Log files:**

- **Dev mode** (no config): `./logs/` next to the project
- **Published mode**: `~/.aisniff/logs/`
- Configurable via `logsDir` setting

Logs are NDJSON organized by route prefix, with an `index.json` per prefix tracking loop IDs, turn counts, token usage, and model names.

## License

MIT