Session Cost Tracking (codesession-cli)

Track agent session costs, file changes, and git commits. Enforces budget limits and provides detailed session analytics with a full web dashboard.

Latest: v2.5.1 - cs run <command> wraps everything in one step (session + proxy + run + cost summary). cs today for multi-project context. Dashboard Help tab, Codex pricing, security fixes.

📦 npm • ⭐ GitHub • 📝 Changelog

Installation

CODEBLOCK0

After installing, the cs command is available globally. The OpenClaw agent will automatically use it to track sessions.

Requirements: Node.js 18+ and C/C++ build tools (needed to compile the embedded SQLite module).

OS	Install build tools
Ubuntu/Debian	INLINECODE3
macOS

xcode-select --install |
| Windows | npm install -g windows-build-tools or install Visual Studio Build Tools |
| Alpine | apk add build-base python3 |
Data is stored locally at ~/.codesession/sessions.db.

When to use

• - Always start a tracked session at the beginning of a multi-step task
• Always log AI usage after each API call you make
• Always end the session when the task is complete
• Check budget before expensive operations
• Use cs dashboard to review session data in a browser

Commands

Start tracking

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.

Log AI usage (after each API call)

# With granular tokens (cost auto-calculated from built-in pricing):
cs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --json

# With agent name tracking (NEW in v1.9.1):
cs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --agent "Code Review Bot" --json

# With manual cost:
cs log-ai -p anthropic -m claude-opus-4-6 -t 15000 -c 0.30 --json

# With all fields:
cs log-ai -p openai -m gpt-4o --prompt-tokens 5000 --completion-tokens 1500 -c 0.04 --agent "Research Agent" --json

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.

Check current status

cs status --json

End session and get summary

cs end -n "completion notes" --json

Web Dashboard

The dashboard shows:

• - Overview — KPIs, daily cost/token trends, spend projections, cost velocity
• Sessions — searchable/sortable table, per-session detail with timeline, files, commits, AI calls, notes
• Models — per-model & per-provider cost breakdown, token ratios, usage charts
• Insights — file hotspots, activity heatmap, project breakdown, pricing table
• Alerts — set daily/total/per-session cost thresholds with alarm mode (sound + browser notifications)
• Start Fresh — reset all session data from the sidebar

View session details

View historical stats

Export sessions

Add notes / annotations

cs note "Starting refactor phase"
cs note "Tests passing, moving to cleanup"

Recover stale sessions

cs recover --max-age 12

Agent Workflow

Agents should always use --json on every command for structured, parseable output.

1. 1. At task start: INLINECODE27
2. Add context notes: INLINECODE28
3. After each AI call: INLINECODE29
4. Check spend: cs status --json -- read aiCost field
5. At task end: INLINECODE32
6. Review past sessions: INLINECODE33

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").

Pricing

Pricing is configurable. Run cs pricing list to see all known model prices. Override or add models:

CODEBLOCK11

If the model isn't in the pricing table, you must provide -c <cost> when logging.

Proxy mode & cs run (v2.5.0)

The fastest way to track any agent run:

CODEBLOCK12

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.

If you prefer manual control, start the proxy in one terminal and set env vars:

CODEBLOCK13

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.

Budget awareness

If the user has set a budget or you detect high spending:

• - Check cs status --json before expensive operations
• Warn the user if aiCost exceeds $5.00 in a single session
• Suggest cheaper models if costs are escalating

Important

• - Use --close-stale on cs start to avoid "session_active" errors from prior crashes
• If cs is not installed, skip session tracking — don't block the user's task
• Always use --json on every command — agents must use structured output
• With --json, cs start creates the session and exits (no long-running process needed)
• Sessions are scoped by git root — running from a subdirectory still matches the repo-level session
• On errors in --json mode, exit code is always 1 and the response has INLINECODE48
• Check schemaVersion in JSON responses to detect breaking changes

Update check

Periodically check if the CLI is up to date (e.g. at session start or once per day):

CODEBLOCK14

If the installed version is behind, notify the user:

"codesession-cli update available: v1.9.4 -> v2.0.0. Run npm install -g codesession-cli to update."

Don't block the workflow for an update — just inform and continue.

JSON output

All commands support --json for machine-readable output. Use this when you need to parse session data programmatically.