Sato

AI Coding Telemetry Collector. One command to capture OpenTelemetry data from Claude Code.

Quick Start

npx satoai

That's it. On first run, Sato automatically configures Claude Code to export telemetry, starts an OTLP receiver on :4318, and installs a LaunchAgent so it runs on login.

Open a new terminal and use Claude Code as usual — telemetry flows automatically.

Commands

sato / sato start

Start the OTLP receiver.

sato                         # default: OTLP receiver on :4318
sato start --otlp-port 4319  # custom OTLP port

sato stop

Stop the running Sato instance.

sato stop
sato stop --uninstall        # also remove the LaunchAgent

sato status

Show running state and forwarding endpoint.

sato status

sato setup claude

Configure Claude Code to export telemetry. Appends env vars to your shell profile (~/.zshrc or ~/.bashrc). Idempotent — safe to run multiple times.

sato setup claude

How It Works

1. sato start launches an OTLP HTTP/JSON receiver on :4318
2. Claude Code (with telemetry enabled) sends OpenTelemetry logs and metrics to the receiver
3. The receiver appends data to ~/.sato/data/ and forwards to the dashboard

Data

Telemetry is stored locally in ~/.sato/data/.

• ~/.sato/data/logs.json — OTLP log records
• ~/.sato/data/metrics.json — OTLP metric records
• ~/.sato/sato.pid — PID file for the running instance

Environment Variables

| Variable | Description | |----------|-------------| | SATO_API_KEY | API key for forwarding data to the Supabase-backed dashboard. Get this from the dashboard after logging in with GitHub. | | SATO_INGEST_URL | Dashboard URL to forward data to. Defaults to http://localhost:3000. Set to your deployed URL (e.g. https://satoai.co) for remote forwarding. |

These are automatically added to your shell profile by sato setup claude. To add your API key manually:

# Add to your ~/.zshrc (inside the Sato block)
export SATO_API_KEY=sato_your_key_here

Development

git clone https://github.com/SatoAI-co/Sato.git
cd Sato
npm install
npm run dev         # Next.js dashboard on :3000
npm run build:cli   # compile CLI to dist/cli/

Publishing to npm

The CLI is published as the satoai package on npm. prepack automatically runs build:cli before publishing.

# 1. Bump version in package.json
npm version patch    # 0.1.0 → 0.1.1 (or minor/major)

# 2. Publish (requires npm login + 2FA)
npm publish --access public

# If you have 2FA enabled, pass your OTP:
npm publish --access public --otp=123456

Pre-publish checklist

1. All CLI changes are committed
2. npm run build:cli compiles without errors (runs automatically via prepack)
3. Version in package.json is bumped (npm rejects duplicate versions)
4. You're logged in to npm (npm whoami)

Prerequisites

• Node.js 18+
• Claude Code CLI (npm install -g @anthropic-ai/claude-code)