Scopeon

◈  ╔═╗╔═╗╔═╗╔═╗╔═╗╔═╗╔╗╔
   ╚═╗║  ║ ║╠═╝║╣ ║ ║║║║
   ╚═╝╚═╝╚═╝╩  ╚═╝╚═╝╝╚╝
   AI Context Observability
   for Claude Code & friends

The AI context observatory — for every coding agent, every token, every dollar.

Install · Quick Start · Docs · Contributing

You fire up Claude Code and start building. An hour later: "Context window full." You have no idea what burned it — was it the MCP tools? The thinking budget? Yesterday's file edits? You're flying blind on a meter that costs real money.

Scopeon gives you the instrument panel.

Why Scopeon?

What you get

🔬 X-ray vision into every token — see exactly what burned your context: input, cache reads/writes, thinking budget, output, MCP calls — broken down turn by turn. No more guessing.

💸 Know your real cost before the bill arrives — live USD per turn, per session, per project, per day. Set budgets with actual alerts, not surprises.

⚡ Prompt cache that actually tells you if it's working — hit-rate gauge, dollars saved vs. uncached baseline. Know in seconds whether your cache setup is doing anything.

⏳ "You have ~12 turns left" — Scopeon tracks context fill rate over time and tells you how many turns remain before the wall. Stop being blindsided mid-task.

🔔 Context advisory before the crisis — compaction advisory fires at 55–79% fill when context is accelerating, so you compact at the optimal moment — not after it's too late.

📡 Zero-token ambient awareness — every 30 s the MCP server pushes a free status heartbeat to the agent. No polling, no token spend, just continuous situational awareness.

🧭 See what the agent actually did — provenance-aware history shows which skills, MCPs, hooks, tasks, and subagents were involved, with exact vs. estimated support called out per provider.

🤖 Your AI agent monitors itself — 17 MCP tools let Claude Code query its own token stats, provenance history, trigger alerts, and compare sessions — without you doing anything.

🚦 Fail PRs on AI cost spikes — one command in CI, zero config. scopeon ci report --fail-on-cost-delta 50 catches runaway cost before it merges.

🌐 Live browser dashboard + IDE stream — scopeon serve → WebSocket-powered charts at localhost:7771 and a GET /sse/v1/status SSE feed for IDE extensions. No npm, no Node, just Rust.

👥 Team cost from git history — scopeon team reads AI-Cost: trailers from git log and prints a per-author cost table. No server, no cloud, works from any machine.

🐚 Cost follows you everywhere — in your shell prompt, in every git commit as an AI-Cost: trailer, in Slack via digest webhooks.

🔒 Fully local, forever — no cloud backend, no account, no telemetry. Your prompts never leave the machine. Ever.

→ Full feature list

Screenshots

Sessions — full session list with per-turn cost, cache %, MCP call count

Insights — health score, waste signals, cache ROI & optimization tips

Budget — daily/weekly/monthly spend, by model, by project, 14-day chart

Providers — auto-detected agents with data path & session stats

Installation

Fastest: cargo binstall (pre-built binary)

cargo install cargo-binstall   # one-time
cargo binstall scopeon

curl one-liner (macOS & Linux)

curl -fsSL https://raw.githubusercontent.com/sorunokoe/Scopeon/main/install.sh | sh

From source

cargo install --git https://github.com/sorunokoe/Scopeon

Requirements: Rust 1.88+ · macOS 12+ or Linux (glibc 2.31+) · Windows 10+

Pre-built binaries

Download from GitHub Releases:

Quick Start

scopeon onboard    # auto-detect AI tools, configure MCP + shell integration
scopeon            # open the TUI dashboard
scopeon serve      # browser dashboard → http://localhost:7771
scopeon status     # quick inline stats, no TUI
scopeon doctor     # health diagnostics

Connect to Claude Code (MCP)

scopeon init
# → writes MCP server config to ~/.claude/settings.json
# Claude Code now has 17 Scopeon tools + proactive push alerts

All commands

scopeon [start]                # daemon + TUI (default)
scopeon tui                    # TUI only (no file watching)
scopeon mcp                    # MCP server over stdio
scopeon status                 # inline stats
scopeon serve [--port N] [--tier 0-3]

scopeon tag set <id> feature   # tag sessions for cost attribution
scopeon export --format csv --days 30
scopeon reprice                # recalculate costs after a price change

scopeon digest [--days N] [--post-to-slack <url>]
scopeon badge [--format markdown|url|html]
scopeon ci snapshot --output baseline.json
scopeon ci report  --baseline baseline.json [--fail-on-cost-delta 50]

scopeon shell-hook             # emit shell prompt hook (bash/zsh/fish)
scopeon git-hook install       # add AI-Cost trailer to commits
scopeon onboard                # interactive setup wizard
scopeon doctor                 # health diagnostics

Documentation

Supported Providers

Claude Code · GitHub Copilot CLI · Aider · Cursor · Gemini CLI · Ollama · Generic OpenAI

Scopeon discovers log files automatically — no config needed for standard install paths.
Adding a new provider takes ~50 lines of Rust. See docs/providers.md.

Data & Privacy

• Local-first — no cloud backend, no accounts, no API keys required
• Reads token counts and costs only — never prompt text or code
• scopeon serve is read-only and localhost-bound by default
• Webhooks are opt-in; payloads contain only metric data

Contributing

Contributions are warmly welcomed — bug fixes, new providers, dashboard features.

git clone https://github.com/sorunokoe/Scopeon
cd Scopeon
make          # fmt-check + clippy + test (same as CI)
make install  # install to ~/.cargo/bin

• CONTRIBUTING.md — dev workflow, PR process, adding providers
• ARCHITECTURE.md — codebase map: crate roles, data flow, schema

Every PR must pass the full CI suite (fmt · clippy · tests on Linux/macOS/Windows · MSRV · docs).

Changelog

See CHANGELOG.md for the full version history.

License

Dual-licensed under MIT OR Apache-2.0 — use it however you like.