Skip to main content
Manual tracking gives you explicit control over when a session starts and ends. It is the right approach for longer work periods — multi-hour feature builds, exploratory sessions, or any workflow where you want to draw session boundaries yourself rather than wrapping a single command with cs run.

​
Basic workflow

1

Start a session

cs start "Refactor payment service"
CostHQ creates the session, records the start time, and begins watching for file changes and git commits automatically.
2

Work

Write code, run tests, make commits. File changes and git commits are tracked in the background — you do not need to do anything extra.
3

Optionally log AI usage manually

If you are not using the proxy, record AI calls directly with cs log-ai:
cs log-ai -p anthropic -m claude-3-5-sonnet-20241022 -t 25000 -c 0.25
The -t flag sets total tokens and -c sets cost in USD. For models in CostHQ’s built-in pricing table, you can omit -c and the cost is calculated automatically.
4

End the session

cs end -n "Extracted PaymentService class, 3 tests added"
The -n flag attaches a note to the session before it closes. Notes appear in cs show and the dashboard.
5

Review

cs show
Displays the full session summary in a table.

​
Session summary

cs show outputs a formatted table for the most recent session (or a specific session by ID): 
$ 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 │
└─────────────────┴────────────────────────────────────┘
Pass --files or --commits to include the full file change list or commit log in the output.

​
Combining the proxy with manual tracking

For the best of both worlds — manual session boundaries plus automatic API cost capture — start the proxy in a separate terminal while your session is active: 
cs start "Build recommendation engine"
cs proxy start   # in a separate terminal
# ... code with your AI tools pointing at http://127.0.0.1:3739 ...
cs end
All API calls routed through the proxy are logged to the active session automatically, so you do not need to run cs log-ai by hand. See Local Proxy for proxy setup details.

​
Session annotations with cs note

Add timestamped notes within a session to mark transitions between sub-tasks or phases of work: 
cs note "Starting refactor phase"
cs note "Tests passing, moving to docs"
Annotations appear in cs show --json under the annotations array and in the session detail view in the dashboard. They are useful for reconstructing what happened during a long session.
Run cs status before cs start to confirm no session is already active. Only one session can run at a time — if you switch tasks without ending the previous session, time and costs from the new work will be attributed to the old one.
For the complete flag reference for cs start, cs end, cs log-ai, and related commands, see Session Commands.