> ## 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.

# cs run: Automatic Zero-Config Agent Session Tracking

> cs run wraps any command with a full session lifecycle: starts a session, spins up the local proxy, runs your command, and prints a cost summary on exit.

`cs run` is the zero-configuration approach to tracking any agent script or one-off command. You hand it a command, and it handles the entire session lifecycle — no environment variable setup, no manual start/end calls, no forgotten sessions.

## How it works

When you run `cs run <command>`, CostHQ executes the following sequence automatically:

1. **Creates a new session** — the session name defaults to the command string you passed (e.g., `python my_agent.py`). Override it with `--name`.
2. **Starts the local proxy on port 3739** — a lightweight HTTP proxy that sits in front of the Anthropic and OpenAI APIs.
3. **Launches your command** with `ANTHROPIC_BASE_URL` and `OPENAI_BASE_URL` already pointing at the proxy — no shell exports needed.
4. **Intercepts and logs all API calls** — every request your command makes to Anthropic or OpenAI is captured and associated with the active session.
5. **Ends the session and prints a cost summary** — when your command exits (success or failure), CostHQ closes the session and prints duration, file changes, commits, and total AI cost.

## Usage

```bash theme={null}
cs run python my_agent.py
cs run node agent.js
cs run -- npx my-agent --task "fix the bug"
```

Use `--` before commands that have their own flags so the shell doesn't try to parse them as `cs run` flags.

## Options

| Flag            | Default        | Description                             |
| --------------- | -------------- | --------------------------------------- |
| `--name <name>` | command string | Custom session name                     |
| `--port <port>` | `3739`         | Proxy port                              |
| `--no-proxy`    | `false`        | Skip the proxy; track session time only |

## Example output

When your command exits, CostHQ prints a summary like this:

```text theme={null}
  Done  python my_agent.py
    14m  •  8 files  •  2 commits  •  $1.43 AI cost
    Top model: claude-3-5-sonnet-20241022
```

The summary shows elapsed time, the number of files changed and commits made during the session, total AI spend, and the model that accounted for the most usage.

<Tip>
  Use `--no-proxy` if your API calls already route through a separate proxy or if you are tracking session time only and do not need cost data. When `--no-proxy` is set, `ANTHROPIC_BASE_URL` and `OPENAI_BASE_URL` are left untouched and no proxy process is started.
</Tip>

## Running the proxy separately

If you need the proxy running independently of a single command — for example, while you work across multiple terminals or editor sessions — see [Local Proxy](/tracking/proxy). You can start the proxy once and leave it running while you use `cs start` and `cs end` to control session boundaries yourself.