codesession-cli 1.0.0 → 1.3.0

package/README.md

@@ -1,186 +1,272 @@
-# codesession
+<div align="center">
+  <h1>codesession-cli</h1>
+  <p><strong>Track what your AI agents actually cost</strong></p>
+  
+  <p>
+    <a href="https://www.npmjs.com/package/codesession-cli"><img src="https://img.shields.io/npm/v/codesession-cli?color=brightgreen" alt="npm version"></a>
+    <a href="https://www.npmjs.com/package/codesession-cli"><img src="https://img.shields.io/npm/dm/codesession-cli" alt="npm downloads"></a>
+    <a href="https://github.com/brian-mwirigi/codesession-cli/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/codesession-cli" alt="license"></a>
+  </p>
+
+  <p><em>Track agent runs • Monitor files • Log commits • Enforce budgets</em></p>
+</div>
 
-Track your AI coding sessions: time, files, commits, and AI costs.
+---
 
-## Features
+## The Problem
 
-- **Session Tracking** - Start/stop coding sessions with one command
-- **File Monitoring** - Automatically track file changes
-- **Git Integration** - Log commits during sessions
-- **AI Cost Tracking** - Record AI API usage per session
-- **Statistics** - View productivity metrics
-- **Local Storage** - All data stored locally in SQLite
+Your AI agent just ran for 45 minutes. It made 23 API calls, edited 15 files, and created 4 commits.
 
-## Quick Start
+**You have no idea what it cost.**
 
-```bash
-# Install
-npm install -g codesession
+OpenClaw, Claude Code, custom agents — they all burn tokens with zero visibility. You find out when the bill arrives.
 
-# Start a session
-cs start "Build user auth"
+## The Solution
 
-# Code away... (files, commits tracked automatically)
+One command to start tracking. Everything logged automatically.
 
-# End session
-cs end -n "Completed basic auth flow"
+```bash
+# Start tracking an agent run
+cs start "Fix authentication bug"
+
+# Agent does its thing... (files, commits, AI calls tracked automatically)
 
-# View session
-cs show
+# End and see the damage
+cs end
+# Session: 47m • 15 files • 4 commits • $8.47 AI cost
 ```
 
+## Works With
+
+- **[OpenClaw](https://openclaw.ai)** — Ships as an OpenClaw skill ([install from ClawHub](#openclaw-skill))
+- **Claude Code** — Track autonomous coding sessions
+- **Custom agents** — Programmatic API with budget enforcement
+- **Manual sessions** — Track your own coding time and costs
+
 ## Installation
 
 ```bash
-npm install -g codesession
+npm install -g codesession-cli
 ```
 
-## Usage
+## Quick Start
 
-### Start a Session
+### CLI Usage
 
 ```bash
-# Start tracking
-cs start "Feature name"
+# Start a session
+cs start "Build user auth"
+
+# Log AI usage — cost auto-calculated from built-in pricing
+cs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000
+
+# Or provide cost manually
+cs log-ai -p anthropic -m claude-opus-4-6 -t 15000 -c 0.30
+
+# Check current costs mid-session
+cs status
+
+# End session
+cs end -n "Auth complete, all tests passing"
+
+# View session history
+cs list
+cs show --files --commits
+cs stats
 
-# Automatically tracks:
-# - File changes in real-time
-# - Git commits
-# - Time spent
+# Export sessions
+cs export --format csv
+cs export --format json --limit 10
 ```
 
-### End a Session
+### JSON Output (for agents)
+
+Every command supports `--json` for machine-readable output:
 
 ```bash
-# End with notes
-cs end -n "Completed feature X"
+cs status --json
+# {"id":42,"name":"Fix auth","status":"active","aiCost":3.47,"aiTokens":89000,...}
 
-# View summary automatically
+cs log-ai -p openai -m gpt-4o --prompt-tokens 3000 --completion-tokens 2000 --json
+# {"logged":{"provider":"openai","model":"gpt-4o","tokens":5000,"promptTokens":3000,"completionTokens":2000,"cost":0.0275},"session":{"id":42,"aiCost":3.52,"aiTokens":94000}}
 ```
 
-### View Sessions
+---
 
-```bash
-# Show last session
-cs show
+## OpenClaw Skill
 
-# Show specific session
-cs show 5
+codesession-cli ships as an [OpenClaw](https://openclaw.ai) skill. The agent automatically tracks its own session costs.
 
-# Show with details
-cs show --files --commits
+### Install the skill
 
-# List recent sessions
-cs list
+Copy the skill to your OpenClaw workspace:
+
+```bash
+# Option 1: Copy from npm package
+cp -r $(npm root -g)/codesession-cli/skills/codesession ~/.openclaw/skills/
 
-# List more
-cs list -l 20
+# Option 2: Clone and copy
+git clone https://github.com/brian-mwirigi/codesession-cli.git
+cp -r codesession-cli/skills/codesession ~/.openclaw/skills/
 ```
 
-### Statistics
+### What it does
+
+Once installed, the OpenClaw agent will:
+
+1. Run `cs start "task name"` at the beginning of each task
+2. Log API usage with `cs log-ai` after each AI call
+3. Check costs with `cs status --json` during long tasks
+4. Run `cs end` when the task completes
+
+### Example: Agent run tracked by codesession
 
-```bash
-# Overall stats
-cs stats
 ```
+You: Fix the payment processing bug and add retry logic
 
-### Log AI Usage
+Agent: Starting session tracking...
+  $ cs start "Fix payment processing + retry"
+  ✓ Session started
 
-```bash
-# Manually log AI usage (or integrate with APIs)
-cs log-ai -p anthropic -m claude-3.5-sonnet -t 15000 -c 0.105
+  [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
 ```
 
-### Check Status
+After 50 agent runs:
 
 ```bash
-# See active session
-cs status
+$ cs stats
+┌──────────────┬────────────────┐
+│ Total Sessions│ 50            │
+│ Total Time   │ 8h 34m        │
+│ Files Changed│ 312           │
+│ Commits      │ 87            │
+│ Total AI Cost│ $47.23        │
+└──────────────┴────────────────┘
 ```
 
-## Example Output
+---
 
-```bash
-$ cs show
+## Programmatic API (for agent frameworks)
 
-Session: Build user auth
+Build codesession tracking directly into your agent:
 
-┌──────────────┬────────────────────────────┐
-│ Metric       │ Value                      │
-├──────────────┼────────────────────────────┤
-│ Status       │ Completed                  │
-│ Started      │ Feb 01, 2026 14:30         │
-│ Ended        │ Feb 01, 2026 16:45         │
-│ Duration     │ 2h 15m                     │
-│ Files Changed│ 12                         │
-│ Commits      │ 5                          │
-│ AI Tokens    │ 45,000                     │
-│ AI Cost      │ $2.34                      │
-│ Notes        │ Completed basic auth flow  │
-└──────────────┴────────────────────────────┘
-```
+```typescript
+import { AgentSession, BudgetExceededError } from 'codesession-cli/agents';
 
-## Use Cases
+const session = new AgentSession('Refactor auth module', {
+  budget: 5.00,        // Hard cap: stop at $5
+  directory: './src',   // Watch this directory
+  git: true,           // Track commits
+});
 
-### Freelancers
-Track exact time and costs per feature for client billing.
+session.start();
 
-### Indie Hackers
-Monitor build speed and AI spending per feature.
+// After each AI call — with granular tokens (cost auto-calculated)
+session.logAI('anthropic', 'claude-opus-4-6', 15000, 0.30, {
+  promptTokens: 10000,
+  completionTokens: 5000,
+});
 
-### Learning
-See how long features take you to build.
+// Pre-flight check
+if (!session.canAfford(2.00)) {
+  console.log('Switching to cheaper model...');
+}
 
-### Content Creation
-Auto-generate "I built X in Y hours" blog posts.
+// 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})`);
+  }
+}
 
-### Portfolio
-Show concrete evidence of shipping speed.
+const summary = session.end();
+// { duration: 847, filesChanged: 12, aiCost: 4.80, commits: 3, ... }
+```
 
-## Integrations
+### `runAgentSession` helper
 
-### With TokenCost
+Wraps start/end/error handling automatically:
 
-```bash
-# Track tokens with tokencost
-tc list --json | jq -r '.[] | "cs log-ai -p \(.provider) -m \(.model) -t \(.totalTokens) -c \(.cost)"'
+```typescript
+import { runAgentSession } from 'codesession-cli/agents';
+
+const summary = await runAgentSession(
+  'Fix all linting errors',
+  { budget: 3.00, directory: './src' },
+  async (session) => {
+    // Your agent logic
+    const response = await anthropic.messages.create({ ... });
+    session.logAI('anthropic', 'claude-sonnet-4-5', tokens, cost);
+  }
+);
+
+console.log(`Done: ${summary.filesChanged} files, $${summary.aiCost}`);
 ```
 
-### With Git Hooks
+---
 
-Create `.git/hooks/post-commit`:
+## All Commands
 
-```bash
-#!/bin/sh
-# Auto-log commits to active session
-cs status > /dev/null 2>&1
-```
+| Command | Description |
+|---------|-------------|
+| `cs start <name>` | Start tracking a session |
+| `cs end [-n notes]` | End session, show summary |
+| `cs status` | Show active session |
+| `cs show [id] [--files] [--commits]` | Show session details |
+| `cs list [-l limit]` | List recent sessions |
+| `cs stats` | Overall statistics |
+| `cs log-ai -p <provider> -m <model> [options]` | Log AI usage (cost auto-derived or manual) |
+| `cs export [--format json\|csv] [--limit n]` | Export sessions as JSON or CSV |
 
-## Data Storage
+All commands support `--json` for machine-readable output.
 
-All data stored locally in `~/.codesession/sessions.db` (SQLite).
+### log-ai options
 
-No data sent anywhere. 100% privacy.
+| Flag | Description |
+|------|-------------|
+| `-p, --provider` | AI provider (required) |
+| `-m, --model` | Model name (required) |
+| `-t, --tokens` | Total tokens |
+| `--prompt-tokens` | Prompt/input tokens |
+| `--completion-tokens` | Completion/output tokens |
+| `-c, --cost` | Cost in USD (auto-calculated if omitted for known models) |
 
-## Development
+## Data Storage
 
-```bash
-# Clone
-git clone https://github.com/brian-mwirigi/codesession.git
-cd codesession
+All data stored locally in `~/.devsession/sessions.db` (SQLite with WAL mode for concurrent access).
 
-# Install
-npm install
+No telemetry. No cloud. 100% local.
 
-# Dev mode
-npm run dev -- start "Test session"
+## Example Output
 
-# Build
-npm run build
+```bash
+$ cs show
 
-# Test
-npm link
-cs start "My session"
+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  │
+└──────────────┴────────────────────────────┘
 ```
 
 ## License
@@ -191,10 +277,6 @@ MIT
 
 Built by [Brian Mwirigi](https://github.com/brian-mwirigi)
 
-## Testing
-
-This is a test modification to trigger file watcher.
-
 ---
 
-**Track your velocity. Ship faster.**
+**Know what your agents cost. Ship with confidence.**

package/dist/agents.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Agent Sessions - Programmatic API for AI agents
+ *
+ * Track agent runs with automatic file watching, git tracking,
+ * AI cost logging, and budget enforcement.
+ *
+ * @example
+ * ```typescript
+ * import { AgentSession } from 'codesession-cli/agents';
+ *
+ * const session = new AgentSession('Refactor auth module', {
+ *   budget: 5.00,
+ *   directory: './src',
+ *   git: true,
+ * });
+ *
+ * session.start();
+ * // ... agent does work ...
+ * const summary = session.end();
+ * ```
+ */
+export interface AgentSessionConfig {
+    /** Hard budget cap in dollars. Session auto-ends if exceeded. */
+    budget?: number;
+    /** Directory to watch for file changes. Defaults to cwd. */
+    directory?: string;
+    /** Enable git commit tracking. Defaults to true. */
+    git?: boolean;
+    /** Interval (ms) to check for new git commits. Defaults to 5000. */
+    gitPollInterval?: number;
+    /** Callback when budget is exceeded. Called before session ends. */
+    onBudgetExceeded?: (spent: number, budget: number) => void;
+    /** Callback when AI usage is logged. */
+    onAIUsage?: (cost: number, totalCost: number, model: string) => void;
+    /** Callback on each file change. */
+    onFileChange?: (filePath: string, changeType: string) => void;
+    /** Optional metadata to attach to the session. */
+    metadata?: Record<string, any>;
+}
+export interface AgentSessionSummary {
+    sessionId: number;
+    name: string;
+    duration: number;
+    filesChanged: number;
+    commits: number;
+    aiCost: number;
+    aiTokens: number;
+    budgetRemaining: number | null;
+    files: {
+        path: string;
+        type: string;
+        timestamp: string;
+    }[];
+    commitList: {
+        hash: string;
+        message: string;
+        timestamp: string;
+    }[];
+    aiUsageBreakdown: {
+        provider: string;
+        model: string;
+        tokens: number;
+        cost: number;
+        timestamp: string;
+    }[];
+    metadata?: Record<string, any>;
+}
+export declare class AgentSession {
+    private sessionId;
+    private name;
+    private config;
+    private gitInterval;
+    private totalCost;
+    private totalTokens;
+    private started;
+    private ended;
+    constructor(name: string, config?: AgentSessionConfig);
+    /**
+     * Start the agent session. Begins file watching and git tracking.
+     * @returns The session ID
+     */
+    start(): number;
+    /**
+     * Log AI usage for this session. Automatically checks budget.
+     * Cost is optional — auto-calculated from built-in pricing if omitted (requires known model).
+     * @returns The remaining budget (null if no budget set)
+     * @throws BudgetExceededError if budget is exceeded
+     */
+    logAI(provider: string, model: string, tokens: number, cost: number, options?: {
+        promptTokens?: number;
+        completionTokens?: number;
+    }): number | null;
+    /**
+     * Check how much budget remains.
+     * @returns Remaining budget in dollars, or null if no budget set
+     */
+    get budgetRemaining(): number | null;
+    /** Current total cost spent in this session */
+    get spent(): number;
+    /** Current total tokens used in this session */
+    get tokens(): number;
+    /** Whether this session is currently active */
+    get isActive(): boolean;
+    /** The database session ID (null if not started) */
+    get id(): number | null;
+    /**
+     * End the agent session and return a full summary.
+     */
+    end(notes?: string): AgentSessionSummary;
+    /**
+     * Check if an AI call would exceed the budget.
+     * Useful for pre-flight checks before making expensive API calls.
+     * @returns true if the call would stay within budget
+     */
+    canAfford(estimatedCost: number): boolean;
+    private assertStarted;
+}
+/**
+ * Thrown when an agent session exceeds its budget.
+ * Catch this to handle budget enforcement gracefully.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   session.logAI('openai', 'gpt-4o', 5000, 0.10);
+ * } catch (e) {
+ *   if (e instanceof BudgetExceededError) {
+ *     console.log(`Over budget: spent $${e.spent}, limit $${e.budget}`);
+ *   }
+ * }
+ * ```
+ */
+export declare class BudgetExceededError extends Error {
+    spent: number;
+    budget: number;
+    constructor(spent: number, budget: number);
+}
+/**
+ * Quick helper to run an agent function within a tracked session.
+ * Handles start/end/error automatically.
+ *
+ * @example
+ * ```typescript
+ * const summary = await runAgentSession('Fix all linting errors', {
+ *   budget: 3.00,
+ *   directory: './src',
+ * }, async (session) => {
+ *   // Your agent logic here
+ *   const response = await openai.chat.completions.create({ ... });
+ *   session.logAI('openai', 'gpt-4o', response.usage.total_tokens, 0.05);
+ * });
+ * ```
+ */
+export declare function runAgentSession(name: string, config: AgentSessionConfig, agentFn: (session: AgentSession) => Promise<void>): Promise<AgentSessionSummary>;
+//# sourceMappingURL=agents.d.ts.map

package/dist/agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"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"}