Prerequisites

codesession-cli uses an embedded SQLite database (better-sqlite3) which requires C/C++ build tools to compile:

Note: If prebuilt binaries are available for your platform, compilation is skipped automatically.

Installation

Install

npm install -g codesession-cli

Failsafe: `cs` not installed

Agent skills should check which cs (or where cs on Windows) before attempting to track. If not available, degrade gracefully — don't block the agent's primary task.

AI Usage with Agent Tracking

<img src="https://raw.githubusercontent.com/brian-mwirigi/codesession-cli/main/docs/screenshots/agent-tracking.png" alt="Agent Tracking" width="800">

Quick Start: Node.js Library (New!)

With the merge of aitoken-cli, you can now use codesession as a drop-in Node.js library to track API spend in your own backend applications. Costs are automatically calculated and sent to your dashboard!

Quick Start: CLI (for Agents & Humans)

If you use OpenClaw, Claude Code, or any AI agent framework, this is for you. All commands support --json for machine-readable output:

```bash

CLI Usage (Manual / Interactive)

For human developers tracking their own sessions:

```bash

Log AI usage

cs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000

Example: Agent run tracked by codesession

You: Fix the payment processing bug and add retry logic

Agent: Starting session tracking...
  $ cs start "Fix payment processing + retry"
  Session started

  [Agent works: reads files, edits code, runs tests...]
  $ cs log-ai -p anthropic -m claude-opus-4-6 --prompt-tokens 8000 --completion-tokens 4000
  $ cs log-ai -p anthropic -m claude-opus-4-6 --prompt-tokens 12000 --completion-tokens 6000
  $ cs log-ai -p anthropic -m claude-opus-4-6 --prompt-tokens 5000 --completion-tokens 3000

  $ cs end -n "Fixed payment bug, added exponential backoff retry"
  Session ended

  Session: 12m • 6 files • 2 commits • $0.76 AI cost

After 50 agent runs:

$ cs stats
┌──────────────┬────────────────┐
│ Total Sessions│ 50            │
│ Total Time   │ 8h 34m        │
│ Files Changed│ 312           │
│ Commits      │ 87            │
│ Total AI Cost│ $47.23        │
└──────────────┴────────────────┘

---

Example Output

$ cs show

Session: Build user auth

┌──────────────┬────────────────────────────┐
│ Metric       │ Value                      │
├──────────────┼────────────────────────────┤
│ Status       │ Completed                  │
│ Started      │ Feb 09, 2026 14:30         │
│ Ended        │ Feb 09, 2026 16:45         │
│ Duration     │ 2h 15m                     │
│ Files Changed│ 12                         │
│ Commits      │ 5                          │
│ AI Tokens    │ 45,000                     │
│ AI Cost      │ $2.34                      │
│ Notes        │ Completed basic auth flow  │
└──────────────┴────────────────────────────┘

Example `cs show --json` output

{
  "id": 42,
  "name": "Fix payment processing + retry",
  "status": "completed",
  "startTime": "2026-02-09T14:30:00.000Z",
  "endTime": "2026-02-09T14:42:17.000Z",
  "duration": 737,
  "durationFormatted": "12m",
  "workingDirectory": "/home/user/project",
  "filesChanged": 6,
  "commits": 2,
  "aiTokens": 46000,
  "aiCost": 1.065,
  "notes": "Fixed payment bug, added exponential backoff retry",
  "files": [
    { "id": 1, "sessionId": 42, "filePath": "src/payments.ts", "changeType": "modified", "timestamp": "2026-02-09T14:32:11.000Z" },
    { "id": 2, "sessionId": 42, "filePath": "src/retry.ts", "changeType": "created", "timestamp": "2026-02-09T14:35:44.000Z" },
    { "id": 3, "sessionId": 42, "filePath": "tests/payments.test.ts", "changeType": "modified", "timestamp": "2026-02-09T14:38:20.000Z" }
  ],
  "commits": [
    { "id": 1, "sessionId": 42, "hash": "a1b2c3d", "message": "fix: payment processing null check", "timestamp": "2026-02-09T14:36:00.000Z" },
    { "id": 2, "sessionId": 42, "hash": "e4f5g6h", "message": "feat: add exponential backoff retry", "timestamp": "2026-02-09T14:41:00.000Z" }
  ],
  "aiUsage": [
    { "id": 1, "sessionId": 42, "provider": "anthropic", "model": "claude-opus-4-6", "tokens": 12000, "promptTokens": 8000, "completionTokens": 4000, "cost": 0.42, "timestamp": "2026-02-09T14:31:05.000Z" },
    { "id": 2, "sessionId": 42, "provider": "anthropic", "model": "claude-opus-4-6", "tokens": 18000, "promptTokens": 12000, "completionTokens": 6000, "cost": 0.63, "timestamp": "2026-02-09T14:34:22.000Z" },
    { "id": 3, "sessionId": 42, "provider": "anthropic", "model": "claude-sonnet-4", "tokens": 16000, "promptTokens": 14000, "completionTokens": 2000, "cost": 0.072, "timestamp": "2026-02-09T14:39:50.000Z" }
  ],
  "annotations": [
    { "id": 1, "sessionId": 42, "message": "Starting retry logic implementation", "timestamp": "2026-02-09T14:35:00.000Z" },
    { "id": 2, "sessionId": 42, "message": "Tests passing, cleaning up", "timestamp": "2026-02-09T14:40:30.000Z" }
  ]
}

All --json responses include schemaVersion (currently 1) and codesessionVersion (e.g. "2.0.0") at the top level.

log-ai options

Configurable pricing

codesession ships with built-in pricing for 17 models. Override or add models:

```bash

What's New in v2.1.0 (The API Tracking Pivot)

We merged the most loved features of aitoken-cli directly into codesession! You can now use codesession as a drop-in Node.js library to automatically track AI costs in your backend apps, completely headless.

• Drop-in SDKs — Just import { TrackedOpenAI } from 'codesession-cli/extensions'
• Background Sessions — API calls made via the library auto-create headless tracking sessions so you never lose a cent of data.
• Extended Model Pricing — 42+ built-in models including DeepSeek, o1, o3, Azure, and Cohere.
• Middleware Hooks — createTrackedClient() and BatchTracker for advanced Node.js architectures.

---

1. Drop-in SDK Extensions

Simply replace new OpenAI() with new TrackedOpenAI():

import { TrackedOpenAI, TrackedAnthropic } from 'codesession-cli/extensions';

// Works exactly like the official OpenAI SDK, but logs tokens and costs automatically!
const openai = new TrackedOpenAI({ apiKey: process.env.OPENAI_API_KEY });
const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello!' }]
});

Programmatic API (for agent frameworks)

Build codesession tracking directly into your agent:

import { AgentSession, BudgetExceededError } from 'codesession-cli/agents';

const session = new AgentSession('Refactor auth module', {
  budget: 5.00,        // Hard cap: stop at $5
  directory: './src',   // Watch this directory
  git: true,           // Track commits
});

session.start();

// After each AI call — with granular tokens (cost auto-calculated)
session.logAI('anthropic', 'claude-opus-4-6', 15000, 0.30, {
  promptTokens: 10000,
  completionTokens: 5000,
});

// Pre-flight check
if (!session.canAfford(2.00)) {
  console.log('Switching to cheaper model...');
}

// Budget enforcement is automatic
try {
  session.logAI('openai', 'gpt-4o', 50000, 4.80);
} catch (e) {
  if (e instanceof BudgetExceededError) {
    console.log(`Stopped at $${e.spent} (limit: $${e.budget})`);
  }
}

const summary = session.end();
// { duration: 847, filesChanged: 12, aiCost: 4.80, commits: 3, ... }

Agent Workflow

Typical agent flow: 1. cs start "Task name" --json --close-stale - Creates session 2. Agent performs work (files, commits auto-tracked) 3. cs log-ai -p anthropic -m claude-sonnet-4 --agent "Agent Name" --json - Log each AI call 4. cs status --json - Check costs mid-session 5. cs end -n "Task complete" --json - Finalize and summarize 6. cs dashboard - Review analytics

Integration Contract (for agent frameworks)

If you're building an agent framework integration (OpenClaw, Claude Code, custom), here's the contract: