Know what you spend before you spend it.

English · 简体中文 · 日本語 · 한국어

---

Install

Option A: npm (recommended)

# Install CLI skills (/costea + /costeamigo)
npx @costea/costea

# Start Web UI dashboard
npx @costea/web serve 3000

If your npm registry is private, add: --registry https://registry.npmjs.org

Option B: Git clone

git clone https://github.com/memovai/costea.git
cd costea

# Link skills into Claude Code
ln -sf $(pwd)/skills/costea ~/.claude/skills/costea
ln -sf $(pwd)/skills/costeamigo ~/.claude/skills/costeamigo

# Link skills into Codex CLI
ln -sf $(pwd)/skills/costea ~/.codex/skills/costea

# Start Web UI
cd web && npm install && npm run dev

Requirements

• jq — brew install jq (used by all shell scripts)
• Node.js 18+ — for Web UI only

First run — build the index

After installing, build the session index from your history:

# Via installed skill scripts
bash ~/.claude/skills/costea/scripts/update-index.sh

# Or if cloned
bash skills/costea/scripts/update-index.sh

This scans ~/.claude/projects/, ~/.codex/sessions/, and ~/.openclaw/ to build the task database.

---

Usage

CLI Skills

Open a new Claude Code or Codex session after installing:

# Estimate cost before running a task — shows receipt, asks Y/N
/costea refactor the auth module

# Historical spending report
/costeamigo all        # All platforms combined
/costeamigo claude     # Claude Code only
/costeamigo codex      # Codex CLI only
/costeamigo openclaw   # OpenClaw only

Web UI

# Via npm
npx @costea/web serve 3000

# Or locally
cd web && npm run dev

Open http://localhost:3000 — pages:

Page	What it shows
/	Landing page with receipt card, install commands
/dashboard	All sessions, total cost, platform filter, sort by cost/tokens/date
/session/{id}	Per-session detail: model breakdown, tools, turns (expandable with LLM call detail)
/estimate	Interactive cost prediction — type a task, get live receipt
/analytics	Cost over time, by-model/platform charts, daily breakdown
/accuracy	Prediction vs actual comparison: scatter plot, error distribution, accuracy stats

---

Skills

/costea — Cost Prediction Receipt

Estimates token cost before execution. Shows a terminal receipt with multi-provider comparison, then asks for Y/N confirmation. Logs predictions to ~/.costea/estimates.jsonl and compares with actual usage after execution.

┌──────────────────────────────────────────────────┐
│                  C O S T E A                     │
│              Agent Cost Receipt                  │
│╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌│
│  TASK                                            │
│  Refactor the auth module                        │
│╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌│
│  Input tokens                        12,400      │
│  Output tokens                        5,800      │
│  Tool calls                              14      │
│╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌│
│  PROVIDER ESTIMATES                              │
│  Claude Sonnet 4                        $0.38    │
│  GPT-5.4                                $0.54    │
│  Gemini 2.5 Pro                         $0.29    │
│══════════════════════════════════════════════════│
│  ESTIMATED TOTAL                        $0.38    │
│  Confidence                              96%     │
│╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌│
│            Proceed? [Y/N]                        │
└──────────────────────────────────────────────────┘

/costeamigo — Historical Spending Report

Multi-dimensional analysis: per-platform, per-model, per-skill, tool patterns, reasoning vs tool split, top expensive tasks.

---

How It Works

Session JSONL (3 platforms)
      ↓  parse-claudecode.sh / parse-codex.sh / parse-openclaw.sh
~/.costea/sessions/{id}/
  session.jsonl · llm-calls.jsonl · tools.jsonl · agents.jsonl
      ↓  summarize-session.sh
summary.json → index.json → task-index.json
      ↓
  ┌───────┬──────────┬────────────┬──────────────┐
  ↓       ↓          ↓            ↓              ↓
/costea  /costeamigo  Web UI    estimates.jsonl  fitting/
receipt  report       dashboard  prediction      ML predictor
+ Y/N                analytics  tracking        P10/P50/P90

Key Design

• Parallel tool-call dedup — Claude Code splits one API response into multiple records sharing message.id. Only the first is counted.
• Cumulative delta — Codex CLI stores running totals; per-turn usage = current - previous.
• Native cost — OpenClaw provides per-message USD cost directly.
• Subagent attribution — Claude Code subagents/agent-*.jsonl scanned and attributed to parent session.
• Prediction tracking — Each /costea estimate is logged; actual usage is compared after execution.

ML Prediction Engine (fitting/)

The fitting/ module provides machine-learned cost and token prediction with multiple model backends, all pure JS at inference:

• GBDT (LightGBM) — best overall log-RMSE, robust to outliers
• MLP (PyTorch → pure-JS forward pass) — best median APE, supports ONNX export
• Linear (sklearn → pure-JS dot product) — fast baseline
• TF-IDF kNN retrieves Top-K similar historical tasks as explainability evidence

On 2,769 real tasks (277 test): cost median APE dropped from 70.9% (baseline) to 19.1% (MLP) / 20.7% (GBDT), within ±25% improved to 58.5% (MLP) / 55.6% (GBDT). All inference is pure JS — no native bindings or Python required at predict-time.

See fitting/README.md and fitting/BENCHMARKS.md for full details.

---

Supported Platforms

Platform	Parser	Token Source	Status
Claude Code	parse-claudecode.sh	message.usage per assistant msg	Tested
Codex CLI	parse-codex.sh	Cumulative token_count events	Tested
OpenClaw	parse-openclaw.sh	message.usage with cost	Tested

---

npm Packages

Package	Version	Purpose	Install
@costea/costea	1.1.0	CLI skills (SKILL.md + scripts)	npx @costea/costea
@costea/web	1.0.0	Web UI (standalone Next.js)	npx @costea/web serve [port]
@costea/fitting	0.1.0	ML predictor (GBDT + kNN, pure JS)	npm install @costea/fitting

---

Scripts Reference

Script	Purpose
parse-claudecode.sh	Parse Claude Code JSONL (dedup + subagents)
parse-codex.sh	Parse Codex CLI rollout JSONL (cumulative deltas)
parse-openclaw.sh	Parse OpenClaw JSONL (native cost)
build-index.sh	Build task index from all platforms
estimate-cost.sh	Historical data + aggregate stats for prediction
receipt.sh	Render terminal receipt from JSON
log-estimate.sh	Log predictions + actuals for accuracy tracking
summarize-session.sh	Generate summary.json from session JSONL
update-index.sh	Full scan + rebuild index
test-all.sh	Run regression test suite (9 tests)
lib/cost.sh	Shared price table and jq helpers

---

Data Directory

All data under ~/.costea/ — safe to delete and regenerate:

~/.costea/
├── sessions/{uuid}/
│   ├── session.jsonl      per-turn summaries
│   ├── llm-calls.jsonl    per-API-call records (deduped)
│   ├── tools.jsonl        per-tool invocation
│   ├── agents.jsonl       subagent lifecycle events
│   └── summary.json       aggregated session stats
├── task-index.json        task index (build-index.sh)
├── index.json             session index (update-index.sh)
└── estimates.jsonl        prediction log (log-estimate.sh)

---

License

Apache License 2.0