# Clawdsight

*Oversight your agent can run.*

The OpenRouter companion for AI coding agents. Connect in one click with **Sign in with OpenRouter**, then ask your agent:

- *"Is this activity mine?"*: per-request verdicts, matched against your local agent sessions.
- *"Is Claude Code on my subscription or my API key?"*: the real billing route for each agent.
- *"Any keys I should revoke?"*: key audit, reminders and spending.
- *"Top coding models this week?"*: models, benchmarks, rankings, apps and setup guides, live.

Your key never leaves your machine.

## Quickstart (60 seconds)

You need Claude Code and Node 22.12 or later, with npm on your PATH.

**1. Install the plugin.** In a terminal:

```bash
claude plugin marketplace add DVRK-ORG/clawdsight
```

```bash
claude plugin install clawdsight@clawdsight
```

Or from inside Claude Code: `/plugin marketplace add DVRK-ORG/clawdsight`, then `/plugin install clawdsight@clawdsight`. From a local clone, pass the clone's folder instead: `claude plugin marketplace add ./clawdsight`.

**2. Restart Claude Code** (or run `/reload-plugins`). Nothing to build, no key to paste.

**3. Ask.** Try `/clawdsight:route` to see which billing route each part of Claude Code uses. The first question that needs your account opens **Sign in with OpenRouter** in your browser. Approve it, and the key goes straight into your OS credential store.

| Command | What it does |
|---|---|
| `/clawdsight:triage [csv, gen-… IDs or a time range]` | Is this OpenRouter activity mine? Verdicts with evidence. |
| `/clawdsight:route` | Which billing route each part of Claude Code uses, and the fix. |
| `/clawdsight:keys` | Key audit and reminders, and limits, disabling or deleting after you approve. |
| `/clawdsight:models [what you need]` | Models for a job, live: context, price, benchmarks, Zero Data Retention. |

You don't need the commands. The plugin's `openrouter` skill tells Claude which Clawdsight tool answers which OpenRouter question, so plain questions work too.

If you registered Clawdsight by hand before (`claude mcp add … clawdsight-openrouter`), remove that entry after installing the plugin, so its tools don't appear twice: `claude mcp remove --scope user clawdsight-openrouter`. Your saved keys stay where they are.

## Why it exists: the 4 November incident

On the night of 4 November 2026, the developer of Clawdsight found 14 requests on their OpenRouter key, labelled *Claude Code*, for `claude-4.5-haiku`, a model they had never picked. They had worked in Opus all day. They revoked the key, then tried to find out what had happened. OpenRouter's export showed only headline fields, every request had to be looked up on its own, and nothing could answer the one question that mattered: **was this me?**

A script written that night pulled each request's full metadata from OpenRouter and matched it against their local Claude Code sessions. It settled the case in minutes:

- All 14 came from their own Claude desktop app: user-agent `claude-cli/… (external, sdk-cli, agent-sdk/…)`, origin `https://claude.ai/code`.
- They were the app's short background helper jobs, run inside their own working sessions: large inputs, outputs of 1 to 124 tokens.
- **The cause:** an `env` block in `~/.claude/settings.json`. The app's helper processes read it and billed OpenRouter, while the main conversation stayed on the Claude subscription. One app, two billing routes.
- **The fix:** remove the block and restart the app.

Clawdsight is that script made into a product. The incident stays in the test suite for good: Clawdsight must classify all 14 requests as *Mine (background job)* and name the `env` block as the cause.

## Security principles

1. **Local-first.** The server runs on your machine, as a child process of Claude Code. There is no Clawdsight service, and nobody but you and OpenRouter ever holds your key.
2. **Keys live only in your OS credential store:** Windows Credential Manager, macOS Keychain, or Linux Secret Service. Never in a plain file, a log or tool output. Every tool masks keys by default.
3. **Nothing changes without your approval.** Changing or deleting keys and fixing a billing route are separate tools. Each first shows you the exact change and changes nothing. It returns a one-time code, and the change runs only with that code, for exactly that change, within 10 minutes. The code proves a preview ran for that change; it reaches the agent, so your approval still rests on the agent showing you the preview and on Claude Code's tool permission prompt. Keep that prompt on for `update_key`, `delete_key` and `routing_fix`. Settings files are backed up before they're written.
4. **Evidence with every verdict.** Every finding shows the fields and the matching local session behind it, so you can check it yourself.
5. **Read only what's needed.** Session matching reads metadata (times, session IDs, entry points), not your conversations. The stored-prompt check in `inspect_generation` runs only when you ask for it.

## Privacy

- **No telemetry.** Clawdsight collects nothing: no usage data, no prompts, no keys, no file paths. It has no analytics code and no server of its own.
- **Where it connects:** `openrouter.ai` only, to answer the question you asked (your requests, keys, spending, models, rankings and docs). Requests to OpenRouter carry `X-Title: Clawdsight` so they're labelled as Clawdsight in your OpenRouter activity. Sign-in uses a one-time callback on `127.0.0.1`.
- **The plugin's one-time setup:** the server ships as one bundled file. Its only native part, the credential-store module `@napi-rs/keyring` (pinned to an exact version), is installed from the npm registry. Claude Code does this when it installs the plugin; otherwise Clawdsight does it on first start, into the plugin's data folder (`~/.claude/plugins/data/…`), with install scripts disabled.
- **What stays local:** your Claude Code settings and session logs are read on your machine and never sent anywhere. Tool replies go only to the agent you're talking to.

## Using it

Ask your agent anything that needs OpenRouter, or call `connect`. The first time, Clawdsight opens **Sign in with OpenRouter** in your browser. Approve it, and the new key (labelled "Clawdsight") goes straight into your OS credential store. You never copy or paste a key.

Then ask:

| Ask | Tool | Tier |
|---|---|---|
| *"Are the requests in openrouter_activity.csv mine?"* | `triage_activity` | Standard |
| *"Was anything on my key last night when I wasn't working?"* | `triage_activity` with a time range | Admin |
| *"Inspect gen-…"* (add *"and check the stored prompt"* for the Claude Code fingerprint) | `inspect_generation` | Standard |
| *"Which route is Claude Code billing?"* | `routing_check` | none |
| *"Put Claude Code back on my subscription."* | `routing_fix` (shows the change, acts after you approve) | none |
| *"Any keys that are old, unused or have no limit?"* | `audit_keys`, `key_reminders` | Admin |
| *"Put a $5 monthly limit on my old laptop key."* / *"Delete these 10 unused keys."* | `update_key`, `delete_key` (one preview and one approval for up to 50 keys; refer to keys by name, hash, or a 12-character hash prefix) | Admin |
| *"Where did my credits go this week?"* / *"…yesterday?"* | `spend_report` (balance on Standard, breakdown on Admin; exact windows with `from`/`to`) | Standard / Admin |
| *"Top coding models with vision and a 1M context?"* | `find_models`, `top_models` | Standard |
| *"Which coding models offer Zero Data Retention, and through which providers?"* | `find_models` with `zdr: true`, `zdr_endpoints` | Standard |
| *"Which coding agents are trending?"* | `top_apps` | Standard |
| *"How do I set up Codex with OpenRouter?"* | `setup_guide` | Standard |
| *"How does OpenRouter's prompt caching work?"* | `search_docs`, `read_doc` (with `section` to jump to one part of a page) | Standard |
| *"Am I connected?"* | `status` | none |

**Standard** is Sign in with OpenRouter. **Admin** adds a management key, which can see every key and the account's spending. From a clone, add it with `node dist/index.js key set --admin`.

## Development

Requires Node 22.12+ (24 LTS recommended).

```bash
npm ci
npm run check   # lint + typecheck + tests
npm run build   # compile to dist/
```

The plugin's server is one bundled file, committed at `plugin/server/clawdsight.mjs` so the plugin installs with no build step. After changing `src/`, rebuild and commit it with the rest:

```bash
npm run build:plugin
```

CI runs `npm run check:plugin` and fails if the committed bundle is out of date. The build also keeps `plugin/package.json` and `plugin/.claude-plugin/plugin.json` on the root version, pins `@napi-rs/keyring` to the root lockfile's version, and writes `plugin/server/THIRD-PARTY-NOTICES.md`. If the keyring version changes, also refresh the plugin's lockfile (`cd plugin`, then `npm install --package-lock-only --ignore-scripts`). To check the plugin against Claude Code's format: `claude plugin validate ./plugin` and `claude plugin validate .`.

To run the server from a clone without the plugin, the repo ships a project `.mcp.json`: after `npm run build`, a Claude Code session opened in this folder can approve `clawdsight-openrouter`. Or register it once at user scope:

```bash
claude mcp add --scope user clawdsight-openrouter -- node "<path to this repo>/dist/index.js"
```

Keep the name `clawdsight-openrouter`. Claude Code prefixes every tool with the server name (`mcp__clawdsight-openrouter__triage_activity`, or `mcp__plugin_clawdsight_clawdsight-openrouter__…` in the plugin). With many MCP servers connected, the model chooses tools by name before it reads their descriptions, and "openrouter" in the name is how it knows these tools answer OpenRouter questions.

From a terminal:

```bash
node dist/index.js login
```

- Over SSH or in a container, use `login --headless`: open the link on any device, then paste the code it shows.
- `node dist/index.js logout` removes the saved key.
- `node dist/index.js key set --admin` adds an optional management key, which unlocks the Admin tier.
- `node dist/index.js --help` lists every command.
- For isolated tests, `CLAWDSIGHT_KEYRING_SERVICE=<name>` makes Clawdsight use its own credential-store entries instead of your real ones.

## Changelog

See [CHANGELOG.md](CHANGELOG.md).

## License

[MIT](LICENSE)