visantchi

Local-first observability for developers juggling multiple LLMs. Tracks token usage, calculates costs, ties spend to git branches, and runs a dashboard on your machine — no cloud, no signup, no data leaving your workstation.

Works with Claude Code, Gemini, and Cursor out of the box.

Install

npm install -g visantchi

Quickstart

visantchi setup        # inject Claude Code Stop hook (one-time)
visantchi start        # start server + dashboard
# open http://localhost:3737

Commands

| Command | Description | |---|---| | visantchi start [--host] [--port] [--no-hook] | Start the HTTP server and dashboard | | visantchi setup | Register the Claude Code Stop hook automatically | | visantchi status | Print metrics from local cache (no server required) | | visantchi config | Show current configuration | | visantchi export [--output <path>] | Export sessions to a JSON file | | visantchi sync [--git] [--folder <path>] [--import <file>] | Sync sessions across machines | | visantchi reset [--mascot] [--all] | Reset cache, mascot identity, or both |

API

The server runs on http://localhost:3737 by default. All endpoints are GET.

| Endpoint | Description | |---|---| | /api/health | Server health check | | /api/metrics?project=<hash> | Token and cost metrics for a project | | /api/metrics/projects | Metrics across all tracked projects | | /api/sessions?project=<hash> | Session list for a project | | /api/sessions/projects | All sessions grouped by project | | /api/insights?project=<hash> | Usage insights and trends | | /api/mascote | Current mascot state |

MCP Server

An MCP-compatible server runs on port 3738. Any agent with MCP support can connect and call:

| Tool | Description | |---|---| | get_metrics | Retrieve token and cost metrics | | get_sessions | Retrieve session records | | get_mascote_state | Get the current mascot state | | get_daily_summary | Summarized usage for the current day | | log_session | Record a session from an external agent |

Multi-Machine Sync

Sessions are tagged with your machine's hostname automatically. Three sync strategies are available — pick whichever fits your workflow:

# Option 1: Git — push/pull cache to a private repo
visantchi sync --git

# Option 2: Shared folder — Dropbox, OneDrive, Syncthing, NAS
visantchi sync --folder ~/Dropbox/visantchi-sync

# Option 3: Manual import — exchange export files between machines
visantchi export --output ./my-sessions.json   # machine A
visantchi sync --import ./my-sessions.json     # machine B

All strategies deduplicate by session ID. No data leaves your control.

Configuration

Config is stored at ~/.visantchi/config.json. All fields are optional.

{
  "host": "localhost",
  "port": 3737,
  "claudeLogsDir": "~/.claude/logs",
  "cacheDir": "~/.visantchi/cache",
  "pollIntervalMs": 5000,
  "syncRemote": "[email protected]:you/visantchi-cache.git"
}

Edit the file directly or use visantchi config to inspect current values.

How it works

• Reads logs from Claude Code, Gemini, and Cursor automatically via file watchers (chokidar)
• Parses token counts and maps them to cost using a built-in pricing table per model
• Associates sessions with the active git branch at the time of the session
• Stores everything in a local cache — sqlite3 is used for Cursor logs if available
• The mascot reacts to usage levels — a low-key indicator of how hard your stack is working

Stack

• Node.js 18+, TypeScript (strict)
• Express — HTTP server and REST API
• chokidar — log file watching
• MCP SDK — agent-compatible tool server
• sqlite3 (optional) — Cursor log parsing

Contributing

Open an issue or PR on GitHub. Keep changes focused and avoid touching the design system without discussion.