\r \r

Session Cost Tracking (codesession-cli)\r

\r Track agent session costs, file changes, and git commits. Enforces budget limits and provides detailed session analytics with a full web dashboard.\r \r Latest: v2.5.1 - cs run \x3Ccommand> wraps everything in one step (session + proxy + run + cost summary). cs today for multi-project context. Dashboard Help tab, Codex pricing, security fixes.\r \r 📦 npm • ⭐ GitHub • 📝 Changelog\r \r

Installation\r

\r

# 1. Install the CLI globally from npm\r
npm install -g codesession-cli\r
\r
# 2. Install the OpenClaw skill\r
clawhub install codesession\r
```\r
\r
After installing, the `cs` command is available globally. The OpenClaw agent will automatically use it to track sessions.\r
\r
> **Requirements:** Node.js 18+ and C/C++ build tools (needed to compile the embedded SQLite module).\r
>\r
> | OS | Install build tools |\r
> |---|---|\r
> | **Ubuntu/Debian** | `sudo apt-get install -y build-essential python3` |\r
> | **macOS** | `xcode-select --install` |\r
> | **Windows** | `npm install -g windows-build-tools` or install Visual Studio Build Tools |\r
> | **Alpine** | `apk add build-base python3` |\r
>\r
> Data is stored locally at `~/.codesession/sessions.db`.\r
\r
## When to use\r
\r
- **Always** start a tracked session at the beginning of a multi-step task\r
- **Always** log AI usage after each API call you make\r
- **Always** end the session when the task is complete\r
- Check budget before expensive operations\r
- Use `cs dashboard` to review session data in a browser\r
\r
## Commands\r
\r
### Start tracking\r
```bash\r
# Agent mode (always use --json for structured output):\r
cs start "task description" --json --close-stale\r
\r
# Resume if a session was left open (e.g. after a crash):\r
cs start "task description" --json --resume\r
\r
# Human/interactive mode (stays running with live file watcher):\r
cs start "task description"\r
```\r
\r
> **Agent mode vs interactive mode:** With `--json`, the session is created in the database, JSON is printed, and the process exits immediately -- the session stays "active" and tracks git changes when you run `cs end`. Without `--json`, the process stays running with a live file watcher and git commit poller until you press Ctrl+C or run `cs end` in another terminal.\r
\r
### Log AI usage (after each API call)\r
```bash\r
# With granular tokens (cost auto-calculated from built-in pricing):\r
cs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --json\r
\r
# With agent name tracking (NEW in v1.9.1):\r
cs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --agent "Code Review Bot" --json\r
\r
# With manual cost:\r
cs log-ai -p anthropic -m claude-opus-4-6 -t 15000 -c 0.30 --json\r
\r
# With all fields:\r
cs log-ai -p openai -m gpt-4o --prompt-tokens 5000 --completion-tokens 1500 -c 0.04 --agent "Research Agent" --json\r
```\r
Providers: `anthropic`, `openai`, `google`, `mistral`, `deepseek`\r
Cost is auto-calculated from a configurable pricing table (21+ built-in models including Codex). Use `cs pricing list --json` to see known models. If a model is unknown, provide `-c \x3Ccost>` manually.\r
\r
**Agent Name (optional):** Use `--agent "Agent Name"` to track which agent performed the work. Perfect for multi-agent systems, A/B testing, and cost attribution. Agent names appear in the dashboard and can be used to filter/analyze costs per agent.\r
\r
### Check current status\r
```bash\r
cs status --json\r
```\r
Returns JSON with current session cost, tokens, files changed, duration. All JSON responses include `schemaVersion` and `codesessionVersion` fields.\r
\r
### End session and get summary\r
```bash\r
cs end -n "completion notes" --json\r
```\r
When ending, codesession automatically scans git for all files changed and commits made since the session started -- even if `--json` mode was used (no live watcher needed).\r
\r
### Web Dashboard\r
```bash\r
cs dashboard\r
# Opens http://localhost:3737 with full analytics UI\r
\r
cs dashboard --port 4000       # custom port\r
cs dashboard --no-open         # don't auto-open browser\r
```\r
\r
The dashboard shows:\r
- **Overview** — KPIs, daily cost/token trends, spend projections, cost velocity\r
- **Sessions** — searchable/sortable table, per-session detail with timeline, files, commits, AI calls, notes\r
- **Models** — per-model & per-provider cost breakdown, token ratios, usage charts\r
- **Insights** — file hotspots, activity heatmap, project breakdown, pricing table\r
- **Alerts** — set daily/total/per-session cost thresholds with alarm mode (sound + browser notifications)\r
- **Start Fresh** — reset all session data from the sidebar\r
\r
### View session details\r
```bash\r
cs show --json --files --commits\r
```\r
\r
### View historical stats\r
```bash\r
cs stats --json\r
```\r
\r
### Export sessions\r
```bash\r
cs export --format json --limit 10\r
cs export --format csv\r
```\r
\r
### Add notes / annotations\r
```bash\r
cs note "Starting refactor phase"\r
cs note "Tests passing, moving to cleanup"\r
```\r
Timestamped annotations appear in `cs show --json` under `annotations`.\r
\r
### Recover stale sessions\r
```bash\r
cs recover --max-age 12\r
```\r
Auto-ends any active sessions older than 12 hours.\r
\r
## Agent Workflow\r
\r
Agents should **always** use `--json` on every command for structured, parseable output.\r
\r
1. At task start: `cs start "Fix authentication bug" --json --close-stale`\r
2. Add context notes: `cs note "analyzing auth flow" --json`\r
3. After each AI call: `cs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --agent "Bug Fixer" --json`\r
4. Check spend: `cs status --json` -- read `aiCost` field\r
5. At task end: `cs end -n "Fixed the auth bug, added tests" --json`\r
6. Review past sessions: `cs dashboard`\r
\r
**Tip:** Use the `--agent` flag to identify your agent's work, especially useful in multi-agent systems where different agents handle different tasks (e.g., "Code Review Bot", "Test Writer", "Documentation Agent").\r
\r
## Pricing\r
\r
Pricing is configurable. Run `cs pricing list` to see all known model prices. Override or add models:\r
\r
```bash\r
# Plain model key\r
cs pricing set my-model 5.00 15.00\r
\r
# Provider-namespaced key (avoids collisions)\r
cs pricing set gpt-4o 2.50 10.00 --provider openai\r
```\r
\r
If the model isn't in the pricing table, you must provide `-c \x3Ccost>` when logging.\r
\r
## Proxy mode & cs run (v2.5.0)\r
\r
The fastest way to track any agent run:\r
\r
```bash\r
cs run python my_agent.py\r
# or: cs run --name "fix auth" node agent.js\r
```\r
\r
This starts a session, launches the proxy, runs your command, then ends the session and prints a cost summary. No extra terminals, no env vars to export.\r
\r
If you prefer manual control, start the proxy in one terminal and set env vars:\r
\r
```bash\r
cs proxy --session "my task"   # auto-starts a session too\r
# then in your agent shell:\r
export ANTHROPIC_BASE_URL=http://127.0.0.1:3739\r
export OPENAI_BASE_URL=http://127.0.0.1:3739/v1\r
```\r
\r
The proxy binds to `127.0.0.1` only. It never stores prompt text or API keys — only token counts are written to the session.\r
\r
## Budget awareness\r
\r
If the user has set a budget or you detect high spending:\r
- Check `cs status --json` before expensive operations\r
- Warn the user if `aiCost` exceeds $5.00 in a single session\r
- Suggest cheaper models if costs are escalating\r
\r
## Important\r
\r
- Use `--close-stale` on `cs start` to avoid "session_active" errors from prior crashes\r
- If `cs` is not installed, skip session tracking — don't block the user's task\r
- **Always** use `--json` on every command — agents must use structured output\r
- With `--json`, `cs start` creates the session and exits (no long-running process needed)\r
- Sessions are scoped by **git root** — running from a subdirectory still matches the repo-level session\r
- On errors in `--json` mode, exit code is always `1` and the response has `{ "error": { "code": "...", "message": "..." } }`\r
- Check `schemaVersion` in JSON responses to detect breaking changes\r
\r
## Update check\r
\r
Periodically check if the CLI is up to date (e.g. at session start or once per day):\r
\r
```bash\r
# Compare installed version to latest on npm:\r
cs --version          # installed version\r
npm view codesession-cli version  # latest on npm\r
```\r
\r
If the installed version is behind, notify the user:\r
> "codesession-cli update available: v1.9.4 -> v2.0.0. Run `npm install -g codesession-cli` to update."\r
\r
Don't block the workflow for an update — just inform and continue.\r
\r
## JSON output\r
\r
All commands support `--json` for machine-readable output. Use this when you need to parse session data programmatically.\r