# Task Cost

> Measure the weight of one agent task from explicit start and finish snapshots. Use when the user asks for task cost, token usage, elapsed time, model and reasoning configuration, subagent cost, account-usage percentage change, or a concurrency-adjusted estimate of how much usage one task consumed. Currently supports the OpenAI Codex CLI's local session state; the measurement pattern generalizes to any agent runtime that logs per-session token snapshots.

- Skill: `dreamers-laboratory/task-cost` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add dreamers-laboratory/task-cost`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dreamers-laboratory/task-cost/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: dreamers-laboratory (https://skillmd.com/u/dreamers-laboratory)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/dreamers-laboratory/task-cost

---


# Agent Task Cost

Measure the task; do not estimate from prose or wall time alone.

This skill currently reads the OpenAI Codex CLI's local session state (rollout files under `~/.codex/sessions` and the local authenticated app server). The pattern of explicit start/finish snapshots, subagent registration, and concurrency adjustment generalizes to any agent runtime that logs per-session token counts.

All commands below run `scripts/task_cost.py` from this skill's folder.

## Start the meter

Run this before substantive task work:

```bash
python3 scripts/task_cost.py start \
  --label "<short task label>" \
  --planned-subagent "<model>:<reasoning-effort>:<count>"
```

The script detects the parent session, model, and reasoning effort from the current rollout. If detection is missing or wrong, pass `--model`, `--reasoning-effort`, or `--service-tier` explicitly. Preserve the returned task ID.

The start record must contain:

- local and UTC start time;
- parent model, reasoning effort, and service tier when known;
- planned subagent model, effort, and count;
- parent token baseline;
- live account-usage percentages and reset boundaries.

## Register every subagent

Immediately after spawning a subagent, register its session ID and actual configuration:

```bash
python3 scripts/task_cost.py add-subagent \
  --task-id <task-id> \
  --session-id <subagent-session-id> \
  --model <model> \
  --reasoning-effort medium \
  --baseline zero
```

Use `--baseline zero` for a newly created subagent whose whole session belongs to this task. Use `--baseline current` only when continuing a pre-existing session. Unregistered subagents are conservatively treated as concurrent outside work, so registration matters.

## Finish the meter

Run this as the final tool action, after substantive work and verification:

```bash
python3 scripts/task_cost.py finish --task-id <task-id>
```

Report:

- elapsed wall time;
- parent and subagent configurations;
- exact observed token deltas for parent, every registered subagent, and total task;
- input, cached input, uncached input, output, reasoning output, and total tokens without double-counting cached or reasoning tokens;
- raw account-percentage change for every comparable pool/window;
- other active session count and observed token delta during the interval;
- best-guess task-attributable percentage change and confidence;
- all measurement limitations.

Treat `total_tokens` as token cost. Do not invent a dollar cost. If a dollar estimate is requested, obtain a current authoritative rate card and state that subscription usage percentages are an unreliable billing ledger.

## Concurrency adjustment

Account usage is shared and backend-rounded. Other running tasks can move the same percentage meter. The script scans locally observed rollouts active during the interval, excludes the parent and registered subagents, and estimates:

`task-attributable percentage = raw percentage change x task token share of observed concurrent tokens`

Treat the result as a best-guess estimate; exact allocation is impossible from a shared meter. Model, reasoning, cache, tool, and service-tier differences can make equal token counts consume unequal capacity. State the detected concurrent-session count, token share, and confidence. A raw 0-point change with nonzero tokens means the task fell below the meter's rounding resolution while still consuming usage.

## Measurement boundaries

- Token deltas are exact between local rollout snapshots, provided all task subagents were registered.
- The final natural-language answer generated after `finish` is necessarily outside the ending snapshot; say so.
- If a usage window resets between snapshots, mark its percentage delta non-comparable.
- If the live usage query fails after one retry, still report tokens and elapsed time, but mark percentage measurement unavailable.
- Never expose authentication tokens or app-server credentials.