agwatch is a terminal analytics CLI for AI coding workflows. It reads local usage data from supported agents, normalizes it into a shared event model, and renders that data as an interactive dashboard or structured summary output.

It is built to answer practical questions such as:

• How much did each agent, model, project, or activity cost?
• Which tools and shell commands were used most?
• How many input, output, cached, and written tokens were consumed?
• Which provider usage windows are close to their limits?

What It Shows

agwatch organizes usage into panels so you can inspect both totals and breakdowns quickly.

Agent Analytics

Across enabled agents, the dashboard and summary can show:

• Total cost
• Total calls
• Session count
• Cache hit rate
• Input, output, cached, and written token counts
• Daily activity trends
• Usage by project
• Usage by activity type
• Usage by model
• Tool call frequency
• Shell command frequency
• MCP server usage

Agent Organization

Data is grouped in two ways:

• All Agents aggregates usage from every enabled agent
• Per-agent tabs show isolated usage for each configured agent

The default config currently supports:

• OpenCode via SQLite or JSON-based local data
• Claude Code via local JSONL project logs

Provider Panel

The dashboard also includes a provider usage panel for configured providers.

For each provider, agwatch shows:

• Provider name
• Data source: api or browser-fallback
• Scrape time
• Current 5h usage percentage
• 5h reset time/date
• Current weekly usage percentage
• Weekly reset time/date
• Current monthly usage percentage (when available)
• Monthly reset time/date (when available)
• Provider-specific error state when usage could not be fetched

Supported providers currently include:

• OpenAI
• Anthropic
• Z.AI
• OpenCode Go

Installation

Requirements

• Node.js 18+
• Access to local agent data files

Global Install

npm install -g agwatch-cli

Run Without Installing Globally

npx agwatch-cli dashboard

Quick Start

agwatch
agwatch dashboard
agwatch summary
agwatch summary --range today --json

Commands

dashboard

Launch the interactive terminal dashboard.

agwatch
agwatch dashboard
agwatch dashboard --range today
agwatch dashboard --range 30d
agwatch dashboard --watch

agwatch and agwatch dashboard do the same thing. If no subcommand is provided, the CLI starts the interactive dashboard by default.

summary

Print a non-interactive usage report.

agwatch summary
agwatch summary --range 7d
agwatch summary --from 2026-04-01 --to 2026-04-20
agwatch summary --json

CLI Flags

Shared Time Range Flags

Flag	Values	Description
--range	today, 7d, 30d, month	Preset reporting range
--from	YYYY-MM-DD	Custom start date for summary
--to	YYYY-MM-DD	Custom end date for summary

Summary Flags

Flag	Description
--json	Emit structured JSON instead of text

Dashboard Flags

Flag	Description
--watch	Auto-refresh usage data every 3 seconds
--provider-debug	Enable provider debug logging in non-interactive contexts
--provider-startup-timeout-ms <ms>	Timeout for background provider loading during startup
--provider-manual-timeout-ms <ms>	Timeout for manual provider refresh actions
--provider-fallback <mode>	Browser fallback policy: never, on_auth_error, on_any_error

Provider Runtime Defaults

Option	Default
provider debug	false
startup timeout	25000 ms
manual timeout	35000 ms
fallback mode	on_auth_error

Dashboard Keybindings

Key	Action
q	Quit
1-4	Switch time period
↑↓	Cycle periods
←→	Switch agent tabs
u	Refresh usage data
r	Refresh pricing data
v	Refresh provider usage
a	Refresh all data
p	Open provider setup menu

Dashboard Panels

Panel	What it shows
Overview	Total cost, calls, sessions, cache hit rate, and token totals
Providers	Provider usage percentages, reset windows (5h, weekly, monthly when available), scrape source, and provider errors
By Project	Cost, tokens, and sessions grouped by project
By Model	Cost, tokens, and calls grouped by model
By Activity	Cost and calls grouped by inferred workflow type such as coding, debugging, or testing
Daily Activity	Per-day cost, tokens, and calls
Core Tools	Tool usage frequency
Shell Commands	Shell command frequency
MCP Servers	MCP server usage frequency

Progress bars are relative to the highest row in each panel.

Configuration

Configuration is stored in:

~/.config/agwatch/config.json

On first run, agwatch creates this file automatically.

Example Config

{
"agents": [
{
"id": "opencode",
"label": "OpenCode",
"enabled": true,
"type": "sqlite",
"paths": [
"~/.local/share/opencode/opencode.db",
"~/.opencode/opencode.db",
"~/.config/opencode/opencode.db"
]
},
{
"id": "claude",
"label": "Claude Code",
"enabled": true,
"type": "jsonl",
"paths": [
"~/.claude/projects"
]
}
],
"providers": []
}

Agent Fields

Field	Type	Description
id	string	Stable internal identifier
label	string	Display name used in tabs and UI
enabled	boolean	Whether the agent is included in aggregation
type	sqlite | json | jsonl	Local storage format
paths	string[]	Candidate paths to search for agent data

Provider Fields

Field	Type	Description
id	string	Provider identifier
label	string	Display name
enabled	boolean	Whether provider scraping is enabled

Provider Setup

Provider configuration is handled from inside the dashboard.

1. Open the dashboard.
2. Press p to open the provider menu.
3. Choose a supported provider.
4. Authenticate in the browser flow.
5. Return to the dashboard to view provider usage.

If browser automation dependencies are missing, agwatch prompts to install them during setup.

Provider Session Security

When you authenticate a provider, agwatch captures the browser session cookies needed to fetch your usage data and stores them locally so you are not prompted to log in on every run.

What is stored

Only authentication-relevant cookies are saved — session tokens, auth tokens, and httpOnly server-set cookies. Analytics, tracking, and other non-auth cookies are discarded before the file is written.

Encryption

Stored cookies are encrypted at rest using AES-256-GCM.

The encryption key is derived per-provider using HKDF-SHA256 keyed from a stable machine-bound identifier:

Platform	Machine identifier
Windows	HKLM\SOFTWARE\Microsoft\Cryptography\MachineGuid
macOS	IOPlatformSerialNumber via ioreg
Linux	/etc/machine-id or /var/lib/dbus/machine-id

This means a cookie file copied off your machine cannot be decrypted without the source machine's identifier.

File permissions

Cookie files are written with owner-only access:

Platform	Enforcement
macOS / Linux	chmod 0600 at write time
Windows	icacls removes inherited ACLs and grants full control only to the current user

Storage location

~/.config/agwatch/provider-cookies/<provider-id>.json

Expiry

Cookies with past expiry timestamps are filtered out automatically on every load. If all stored cookies for a provider have expired, the file is deleted and you are prompted to re-authenticate.

Linux note

On Linux, agwatch will display a security notice if libsecret is not installed. libsecret is required for OS-keychain-backed key storage via keytar. Without it, the machine-ID derivation described above is used as a fallback.

Install libsecret for your distribution:

Distribution	Command
Debian / Ubuntu	sudo apt-get install libsecret-1-dev
Red Hat / Fedora / CentOS	sudo yum install libsecret-devel
Arch Linux	sudo pacman -S libsecret
Alpine Linux	sudo apk add libsecret-dev

Pricing

Model pricing is fetched from the LiteLLM pricing database and cached locally.

• Source: https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json
• Cache file: ~/.config/agwatch/pricing-cache.json
• Cache TTL: 24 hours

Behavior:

1. agwatch uses cached prices when the cache is still fresh.
2. It fetches fresh prices when the cache is stale.
3. If fetching fails, it falls back to the last cached pricing.
4. If no pricing is available, unknown costs resolve to $0.
5. If a source record already contains a non-zero cost, that stored cost is used.

Summary Output

Text Output

The text summary includes:

• Summary totals
• Top models
• Top projects
• Daily activity
• Activity breakdown

JSON Output

agwatch summary --json returns:

• metadata
• summary
• panels.dailyActivity
• panels.byProject
• panels.byActivity
• panels.byModel
• panels.tools
• panels.shellCommands
• panels.mcpServers

Data Sources

agwatch reads local agent data and converts it into a shared usage event model.

OpenCode

Reads session, message, and tool-call data from local OpenCode storage.

• SQLite is preferred when available
• Fallback SQLite reading is supported
• JSON-based fallback reading is supported

Claude Code

Reads local JSONL project logs from the Claude Code projects directory.

Architecture

Data Layer -> Domain Layer -> Aggregation Layer -> Presentation Layer

src/
cli/ command dispatch and argument parsing
adapters/ agent-specific readers for OpenCode and Claude Code
domain/ shared types and normalization
services/ loading, aggregation, pricing, and provider services
tui/ Ink-based dashboard UI
output/ text and JSON summary renderers
config/ config loading and time ranges
utils/ formatting, grouping, dates, and error handling

Tech Stack

• TypeScript
• Node.js
• Ink
• React
• Commander
• better-sqlite3
• sql.js
• dayjs
• zod

Development

Install Dependencies

npm install

Build

npm run build

Watch Mode

npm run dev

Type Check

npm run typecheck

You can also run:

npm run lint

Run Locally

npm start
node dist/cli/index.js dashboard --range today
node dist/cli/index.js summary --range 7d

Notes

• No test runner is configured yet.
• The package exposes the agwatch binary from dist/cli/index.js.
• Required Node.js version is 18+.

License

ISC