These commands manage the full lifecycle of a CostHQ tracking session — from opening a session and annotating work in progress, to ending it and reviewing the resulting metrics. Use them together to capture time, file changes, git commits, and AI spend for any task.
cs start
cs start <description> [options]
<description> you provide appears in cs list output and the dashboard, so specific descriptions make your history far more useful.
| Flag | Description |
|---|
--resume | Resume the existing session for the current git root instead of creating a new one |
--close-stale | Auto-close any orphaned sessions before starting a fresh one |
--json | Machine-readable output |
cs start "Feature: Add user search"
cs start "Bug: Fix null pointer in payment flow" --close-stale
cs start "Continue work" --resume --json
{
"schemaVersion": 1,
"CostHQVersion": "3.1.1",
"id": 42,
"name": "Feature: Add user search",
"status": "active",
"directory": "/home/user/project",
"gitRoot": "/home/user/project",
"branch": "feature/user-search"
}
cs end
End the active session and print a summary of time spent, files changed, commits made, and AI cost incurred.
| Flag | Description |
|---|
-n, --notes <text> | Add a note to the session before ending |
-s, --session <id> | Target a specific session by ID instead of the active one |
--json | Machine-readable output |
cs end
cs end -n "Completed login flow, needs QA review"
cs end -n "Branch: $(git branch --show-current)" --json
{
"schemaVersion": 1,
"CostHQVersion": "3.1.1",
"id": 42,
"duration": 847,
"durationFormatted": "14m",
"filesChanged": 8,
"commits": 2,
"aiCost": 1.43,
"aiTokens": 31450
}
cs status
Show whether a session is currently active, and if so, its live duration and running AI spend. Use this mid-task to check costs without ending the session.
| Flag | Description |
|---|
-s, --session <id> | Show status for a specific session by ID |
--json | Machine-readable output |
{
"schemaVersion": 1,
"CostHQVersion": "3.1.1",
"id": 42,
"name": "Feature: Add user search",
"status": "active",
"gitRoot": "/home/user/project",
"aiCost": 1.23,
"aiTokens": 45000,
"liveDuration": 847,
"liveDurationFormatted": "14m"
}
cs status --json exits with code 1 and returns a structured error:
{
"schemaVersion": 1,
"error": {
"code": "no_active_session",
"message": "No active session"
}
}
error.code — never string-compare error.message, which may change between versions.
cs show
Show detailed metrics for a session. Defaults to the most recent session when you omit [id].
| Flag | Description |
|---|
--files | List every file that changed during the session |
--commits | List every git commit made during the session |
--json | Machine-readable output (includes files, commits, aiUsage, and annotations arrays) |
cs show
cs show 12
cs show 12 --files --commits
$ cs show
Session: Fix authentication bug
┌─────────────────┬────────────────────────────────────┐
│ Status │ Completed │
│ Started │ Mar 02, 2026 14:30 │
│ Ended │ Mar 02, 2026 14:44 │
│ Duration │ 14m │
│ Files Changed │ 8 │
│ Commits │ 2 │
│ AI Tokens │ 31,450 │
│ AI Cost │ $1.43 │
│ Top Model │ claude-3-5-sonnet-20241022 │
│ Notes │ Resolved null pointer in JWT check │
└─────────────────┴────────────────────────────────────┘
cs list
List recent sessions in a compact summary table, sorted from most recent to oldest.
| Flag | Default | Description |
|---|
-l, --limit <n> | 10 | Number of sessions to return |
--json | — | Machine-readable output |
$ cs list
Recent Sessions:
┌────┬─────────────────────────────────┬──────────┬───────┬─────────┐
│ ID │ Description │ Duration │ Files │ Cost │
├────┼─────────────────────────────────┼──────────┼───────┼─────────┤
│ 14 │ Fix authentication bug │ 14m │ 8 │ $1.43 │
│ 13 │ Build recommendation engine │ 2h 10m │ 21 │ $6.25 │
│ 12 │ Refactor payment service │ 1h 45m │ 14 │ $3.12 │
│ 11 │ Add user search with filters │ 55m │ 6 │ $0.89 │
└────┴─────────────────────────────────┴──────────┴───────┴─────────┘
cs stats
Show aggregate statistics across all sessions: total sessions, total time, average session length, files changed, commits made, AI tokens used, and total AI cost.
| Flag | Description |
|---|
--json | Machine-readable output |
$ cs stats
Overall Statistics:
┌───────────────────┬──────────┐
│ Total Sessions │ 52 │
│ Total Time │ 138h 20m │
│ Average Session │ 2h 39m │
│ Files Changed │ 412 │
│ Total Commits │ 184 │
│ AI Tokens Used │ 3.1M │
│ Total AI Cost │ $104.72 │
└───────────────────┴──────────┘
cs note
cs note <message> [options]
| Flag | Description |
|---|
-s, --session <id> | Attach the note to a specific session by ID instead of the active one |
--json | Machine-readable output |
cs note "Starting refactor phase"
cs note "Tests passing, moving to docs"
cs note "Switched to cheaper model for remaining calls" -s 42
cs show --json under the annotations array, each with a message and timestamp field.
cs recover
Bulk-end all sessions older than a given age. Use this as a periodic cleanup command or in CI teardown scripts to avoid accumulating stale open sessions.
| Flag | Default | Description |
|---|
--max-age <hours> | 24 | End all sessions whose start time is older than this many hours |
--json | — | Machine-readable output |
cs recover
cs recover --max-age 12
Run cs recover --max-age 1 at the top of CI jobs to ensure no stale session from a previous failed run blocks the new one.