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

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:

  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.

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.

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. You can start the proxy once and leave it running while you use cs start and cs end to control session boundaries yourself.