> ## Documentation Index
> Fetch the complete documentation index at: https://costhq.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Manual Session Tracking with cs start and cs end Commands

> Use cs start and cs end to manually control session boundaries for longer work periods. Combine with cs log-ai to record AI usage from any provider.

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

<Steps>
  <Step title="Start a session">
    ```bash theme={null}
    cs start "Refactor payment service"
    ```

    CostHQ creates the session, records the start time, and begins watching for file changes and git commits automatically.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Optionally log AI usage manually">
    If you are not using the proxy, record AI calls directly with `cs log-ai`:

    ```bash theme={null}
    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.
  </Step>

  <Step title="End the session">
    ```bash theme={null}
    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.
  </Step>

  <Step title="Review">
    ```bash theme={null}
    cs show
    ```

    Displays the full session summary in a table.
  </Step>
</Steps>

## Session summary

`cs show` outputs a formatted table for the most recent session (or a specific session by ID):

```text theme={null}
$ 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:

```bash theme={null}
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](/tracking/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:

```bash theme={null}
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.

<Tip>
  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.
</Tip>

For the complete flag reference for `cs start`, `cs end`, `cs log-ai`, and related commands, see [Session Commands](/reference/session-commands).