Skip to content

Autonomous AI sales agent powered by Claude Code or Codex. Finds prospects, writes cold emails, sends campaigns, handles replies, books meetings. No API keys needed — runs on your Claude or Codex subscriptions.

Add full Claude usage tracking: per-call attribution, real quota gauges, dashboard Usage tab

Ethanb7b225045759
diff --git a/.gitignore b/.gitignore
index 4fce73f..93843f4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -41,3 +41,15 @@ Thumbs.db
# Internal context (not for public repo)
.context.md
+
+# <!-- orcha:managed:start v2 -->
+# Orcha session summaries — local-only by default. Contains prompt + output
+# excerpts that may include sensitive content. Remove this rule to share
+# session history across team/devices/clones.
+.agents/sessions/
+
+# Claude Code background-session worktrees. Auto-created at
+# <repo>/.claude/worktrees/<slug>/ when a `claude --bg` task needs to write.
+# Always local — never tracked in the parent repo.
+.claude/worktrees/
+# <!-- orcha:managed:end -->
diff --git a/CLAUDE.md b/CLAUDE.md
index a22811f..e2fc940 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -156,8 +156,9 @@ Users will come back with questions and tasks. Common ones:
### Architecture
- **Heartbeat loop** (`main.py`): Every cycle → check quiet hours → check budget → decide → act → log → sleep
-- **Brain** (`brain.py`): Wraps `claude -p --dangerously-skip-permissions` for headless Claude calls
+- **Brain** (`brain.py`): Wraps `claude -p --output-format json --dangerously-skip-permissions` for headless Claude calls; records exact tokens/cost per call into `usage_events`
- **State** (`state.py`): SQLite at `data/harvey.db` with tables for companies, prospects, campaigns, conversations, actions, usage
+- **Usage tracking** (`usage.py`, `integrations/quota.py`): per-call attribution (agent/task/model/tokens/cost), transcript reconciliation, and a live subscription-quota gauge read the same way Claude Code's `/usage` does. The budget check throttles Harvey against real quota utilization so it always leaves headroom for your own interactive Claude use (`usage.max_daily_claude_percent`). Dashboard has a Usage tab; CLI has `harvey usage`.
- **Skills** (`skills/`): Markdown knowledge files injected into agent prompts
### Sub-Agents
@@ -181,10 +182,13 @@ harvey dashboard # Web UI at http://localhost:5555
harvey setup # Re-run setup wizard
harvey train <url> # Train on a product website
harvey status # Pipeline summary
+harvey usage # Claude quota gauges + per-agent token/cost report
+harvey usage --reconcile # Also backfill usage from Claude Code transcripts
```
### Common Issues
- **"command not found: harvey"**: Activate venv first: `source .venv/bin/activate`
+- **"ModuleNotFoundError: No module named 'harvey'" after install (macOS)**: Python 3.13 silently ignores `.pth` files that carry the macOS hidden file flag, and some Macs propagate that flag into `.venv`. Run `harvey install` again (it auto-fixes by linking the package), or manually: `ln -s "$(pwd)/harvey" .venv/lib/python3.13/site-packages/harvey`
- **"externally-managed-environment"**: Use a venv, not system Python
- **SQLite errors**: The `data/` directory is created automatically on first run
- **Claude headless mode fails**: User needs `claude login` and an active Max subscription
diff --git a/harvey/agents/analyst.py b/harvey/agents/analyst.py
index a37d6be..9444f2b 100644
--- a/harvey/agents/analyst.py
+++ b/harvey/agents/analyst.py
@@ -23,6 +23,15 @@ class Analyst:
"""Generate analytics report from current pipeline data."""
logger.info("Analyst: Running performance analysis...")
+ # Idle cycles are the cheap moment to reconcile usage accounting
+ # against Claude Code's transcripts (catches crashed calls and
+ # non-Harvey usage on this machine). Best-effort only.
+ try:
+ from harvey.usage import reconcile_transcripts
+ await reconcile_transcripts(self.state)
+ except Exception as e:
+ logger.debug(f"Analyst: usage reconcile skipped: {e}")
+
report = {
"generated_at": datetime.utcnow().isoformat(),
"pipeline": await self._pipeline_summary(),
diff --git a/harvey/agents/handler.py b/harvey/agents/handler.py
index 79ad67d..b23865f 100644
--- a/harvey/agents/handler.py
+++ b/harvey/agents/handler.py
@@ -299,7 +299,10 @@ Reply from {prospect.full_name()} ({prospect.title} at {prospect.company}):
Respond with ONLY the category label, nothing else."""
- result = await self.brain.think(prompt, session_id="harvey-handler")
+ result = await self.brain.think(
+ prompt, session_id="harvey-handler",
+ agent="handler", task="classify_intent",
+ )
if not result:
# Classifier failed. Do NOT auto-reply blind — flag for a human.
logger.warning("Handler: Intent classifier returned nothing. Escalating.")
@@ -424,7 +427,10 @@ Write a reply that:"""
prompt += "\n\nWrite ONLY the email body. No subject line, no greeting label, no signature block, no markdown."
- response = await self.brain.think(prompt, session_id="harvey-handler")
+ response = await self.brain.think(
+ prompt, session_id="harvey-handler",
+ agent="handler", task="generate_response",
+ )
if not response:
return ""
response = response.strip()
diff --git a/harvey/agents/scout.py b/harvey/agents/scout.py
index 0040702..1c5c4cc 100644
--- a/harvey/agents/scout.py
+++ b/harvey/agents/scout.py
@@ -996,7 +996,10 @@ Score criteria:
Respond ONLY with the JSON array."""
try:
- result = await self.brain.think_json(prompt, session_id="harvey-scout-score")
+ result = await self.brain.think_json(
+ prompt, session_id="harvey-scout-score",
+ agent="scout", task="score_contacts",
+ )
except Exception as e:
logger.warning(f"Scout: Claude scoring errored ({e}); using heuristic scores.")
result = None
diff --git a/harvey/agents/writer.py b/harvey/agents/writer.py
index 05cb683..5bfe989 100644
--- a/harvey/agents/writer.py
+++ b/harvey/agents/writer.py
@@ -141,7 +141,10 @@ Return ONLY a JSON array (no markdown fences, no commentary):
{{"step": 3, "subject": "...", "body": "...", "delay_days": 4}}
]"""
- result = await self.brain.think_json(prompt, session_id="harvey-writer")
+ result = await self.brain.think_json(
+ prompt, session_id="harvey-writer",
+ agent="writer", task="write_sequence",
+ )
return self._parse_sequence(result)
def _parse_sequence(self, result) -> list[EmailStep]:
diff --git a/harvey/brain.py b/harvey/brain.py
index fcfcbfd..cc80377 100644
--- a/harvey/brain.py
+++ b/harvey/brain.py
@@ -11,8 +11,10 @@ from harvey.state import StateManager
logger = logging.getLogger("harvey.brain")
-PROMPTS_DIR = Path(__file__).parent.parent / "prompts"
-SKILLS_DIR = Path(__file__).parent.parent / "skills"
+from harvey.paths import PROJECT_ROOT
+
+PROMPTS_DIR = PROJECT_ROOT / "prompts"
+SKILLS_DIR = PROJECT_ROOT / "skills"
# Subprocess safety limits
DEFAULT_TIMEOUT_SECONDS = 300 # a single Claude call should never hang forever
@@ -31,6 +33,9 @@ _NON_RETRYABLE_PATTERNS = (
class Brain:
def __init__(self, state: StateManager):
self.state = state
+ # Lazy import avoids a cycle (quota -> usage -> state).
+ from harvey.integrations.quota import QuotaClient
+ self.quota = QuotaClient()
async def think(
self,
@@ -39,16 +44,22 @@ class Brain:
expect_json: bool = False,
timeout: float = DEFAULT_TIMEOUT_SECONDS,
max_retries: int = DEFAULT_MAX_RETRIES,
+ agent: str = "",
+ task: str = "",
) -> str:
"""Send a prompt to Claude Code headless mode and return the response.
Retries transient failures with exponential backoff and enforces a
hard timeout so a hung CLI call can never stall the heartbeat.
Returns "" on unrecoverable failure (callers already handle empty).
+
+ ``agent``/``task`` label the call in the usage_events ledger so the
+ dashboard can attribute tokens and cost to specific work.
"""
cmd = [
"claude", "-p", prompt,
- "--output-format", "text",
+ # JSON output carries exact token/cost accounting per call.
+ "--output-format", "json",
"--dangerously-skip-permissions",
]
if session_id:
@@ -111,12 +122,20 @@ class Brain:
return ""
continue # retry transient failures
- response = stdout.decode(errors="replace").strip()
+ raw = stdout.decode(errors="replace").strip()
+ response, payload = self._parse_result_payload(raw)
+
+ # Usage accounting must never break the response path.
try:
await self.state.increment_usage()
except Exception as e:
- # Usage accounting must never break the response path
- logger.warning(f"Failed to record usage: {e}")
+ logger.warning(f"Failed to record usage counter: {e}")
+ try:
+ await self._record_usage(payload, agent=agent, task=task,
+ label=session_id or "")
+ except Exception as e:
+ logger.warning(f"Failed to record usage event: {e}")
+
logger.debug(f"Brain response: {response[:200]}...")
return response
@@ -144,15 +163,93 @@ class Brain:
)
return ""
+ @staticmethod
+ def _parse_result_payload(raw: str) -> tuple[str, dict | None]:
+ """Split CLI JSON output into (response_text, result_payload).
+
+ With ``--output-format json`` stdout is one JSON object whose
+ ``result`` field is the model's text. If parsing fails (older CLI,
+ truncated output), fall back to treating stdout as plain text so a
+ formatting change can never break Harvey's pipeline.
+ """
+ try:
+ payload = json.loads(raw)
+ except json.JSONDecodeError:
+ return raw, None
+ if not isinstance(payload, dict) or payload.get("type") != "result":
+ return raw, None
+ return str(payload.get("result") or ""), payload
+
+ async def _record_usage(
+ self, payload: dict | None, agent: str, task: str, label: str
+ ):
+ """Write per-model usage rows from a CLI result payload."""
+ if not payload:
+ return
+
+ if not agent and label.startswith("harvey-"):
+ # Callers historically pass labels like "harvey-scout-score".
+ agent = label[len("harvey-"):].split("-")[0]
+
+ session = str(payload.get("session_id") or "")
+ duration_ms = int(payload.get("duration_ms") or 0)
+ num_turns = int(payload.get("num_turns") or 0)
+ is_error = bool(payload.get("is_error"))
+
+ # modelUsage includes subagent spend; the flat `usage` field does not.
+ model_usage = payload.get("modelUsage")
+ rows = []
+ if isinstance(model_usage, dict) and model_usage:
+ for model, mu in model_usage.items():
+ if not isinstance(mu, dict):
+ continue
+ rows.append({
+ "model": str(model),
+ "input_tokens": int(mu.get("inputTokens") or 0),
+ "output_tokens": int(mu.get("outputTokens") or 0),
+ "cache_read_tokens": int(mu.get("cacheReadInputTokens") or 0),
+ "cache_creation_tokens": int(mu.get("cacheCreationInputTokens") or 0),
+ "cost_usd": float(mu.get("costUSD") or 0.0),
+ })
+ else:
+ usage = payload.get("usage")
+ if isinstance(usage, dict):
+ rows.append({
+ "model": "",
+ "input_tokens": int(usage.get("input_tokens") or 0),
+ "output_tokens": int(usage.get("output_tokens") or 0),
+ "cache_read_tokens": int(usage.get("cache_read_input_tokens") or 0),
+ "cache_creation_tokens": int(usage.get("cache_creation_input_tokens") or 0),
+ "cost_usd": float(payload.get("total_cost_usd") or 0.0),
+ })
+
+ for row in rows:
+ await self.state.record_usage_event(
+ agent=agent,
+ task=task or label,
+ session_id=session,
+ duration_ms=duration_ms,
+ num_turns=num_turns,
+ is_error=is_error,
+ source="result_json",
+ **row,
+ )
+
async def think_json(
- self, prompt: str, session_id: str | None = None
+ self,
+ prompt: str,
+ session_id: str | None = None,
+ agent: str = "",
+ task: str = "",
) -> dict | list | None:
"""Send a prompt and parse the response as JSON."""
full_prompt = (
prompt
+ "\n\nRespond ONLY with valid JSON. No markdown, no explanation."
)
- response = await self.think(full_prompt, session_id=session_id)
+ response = await self.think(
+ full_prompt, session_id=session_id, agent=agent, task=task
+ )
if not response:
return None
parsed = self._extract_json(response)
@@ -194,12 +291,40 @@ class Brain:
logger.warning(f"Could not read usage from state: {e}")
return 0.0
- async def is_within_budget(self, max_daily_calls: int = 200) -> bool:
- """Check if we're under the daily usage limit.
+ async def is_within_budget(
+ self, max_daily_calls: int = 200, max_percent: float | None = None
+ ) -> bool:
+ """Check whether Harvey may spend more Claude quota right now.
- The max_daily_claude_percent from config is mapped to a call count.
- Default budget: 200 calls/day at 100%. So 80% = 160 calls.
+ Preferred signal: the account's REAL utilization windows (the same
+ numbers `/usage` shows), compared against max_percent so Harvey
+ always leaves the remainder for the user's own interactive work.
+ Fallback when that endpoint is unavailable: Harvey's own call
+ counter against max_daily_calls.
"""
+ if max_percent is not None:
+ try:
+ windows = await self.quota.get_utilization()
+ except Exception as e:
+ logger.debug(f"Quota check errored: {e}")
+ windows = None
+ if windows:
+ worst = max(
+ (w["utilization"] for w in windows.values()), default=0.0
+ )
+ within = worst < max_percent
+ if not within:
+ resets = ", ".join(
+ f"{name} resets {w['resets_at']}"
+ for name, w in windows.items()
+ if w.get("resets_at")
+ )
+ logger.info(
+ f"Quota gate: utilization {worst:.0f}% >= "
+ f"{max_percent:.0f}% limit. {resets}"
+ )
+ return within
+
calls = await self.check_usage()
return calls < max_daily_calls
diff --git a/harvey/cli.py b/harvey/cli.py
index 0f70e7e..56b7c44 100644
--- a/harvey/cli.py
+++ b/harvey/cli.py
@@ -45,9 +45,49 @@ def cmd_install(args):
else:
print(" ✓ Playwright browsers installed.\n")
+ _ensure_importable(args._project_root)
print(" Harvey is installed. Run 'harvey setup' next.\n")
+def _ensure_importable(project_root: str):
+ """Make sure `import harvey` works outside the repo directory.
+
+ Python 3.13 silently skips .pth files carrying the macOS 'hidden'
+ file flag, and some Macs propagate that flag to everything inside
+ dot-directories like .venv — which breaks editable installs. When
+ that happens, fall back to symlinking the package into site-packages
+ (imports don't check the hidden flag; only .pth parsing does).
+ """
+ check = subprocess.run(
+ [sys.executable, "-c", "import harvey"],
+ cwd="/", capture_output=True,
+ )
+ if check.returncode == 0:
+ return
+
+ try:
+ import site
+ site_packages = Path(site.getsitepackages()[0])
+ link = site_packages / "harvey"
+ target = Path(project_root) / "harvey"
+ if not link.exists() and target.is_dir():
+ link.symlink_to(target)
+ recheck = subprocess.run(
+ [sys.executable, "-c", "import harvey"],
+ cwd="/", capture_output=True,
+ )
+ if recheck.returncode == 0:
+ print(" ✓ Fixed package visibility (editable .pth was being "
+ "ignored; linked the package directly).\n")
+ return
+ except OSError as e:
+ print(f" Could not apply import fix: {e}")
+
+ print("\n Warning: 'import harvey' fails outside the project directory.")
+ print(" Run harvey commands from the project root, or reinstall with:")
+ print(" pip install -e . --config-settings editable_mode=compat\n")
+
+
def cmd_setup(args):
"""Run the interactive setup wizard."""
from harvey.setup import run_setup
@@ -111,8 +151,75 @@ def cmd_status(args):
asyncio.run(_status())
+def cmd_usage(args):
+ """Show Claude usage: quota gauges, totals, per-agent breakdown."""
+ from harvey.state import StateManager
+
+ async def _usage():
+ state = StateManager()
+ await state.init_db()
+
+ if args.reconcile:
+ from harvey.usage import reconcile_transcripts
+ inserted = await reconcile_transcripts(state, since_days=args.days)
+ print(f"\n Reconciled transcripts: {inserted} event(s) backfilled.")
+
+ # Live quota (best-effort; undocumented endpoint)
+ from harvey.integrations.quota import QuotaClient
+ windows = None
+ try:
+ windows = await QuotaClient().get_utilization()
+ except Exception:
+ pass
+
+ print("\n Claude Usage")
+ print(" " + "=" * 52)
+ if windows:
+ labels = {"five_hour": "5-hour window", "seven_day": "Weekly"}
+ for key, w in windows.items():
+ resets = f" (resets {w['resets_at']})" if w.get("resets_at") else ""
+ print(f" {labels.get(key, key):<16} {w['utilization']:5.1f}% used{resets}")
+ else:
+ print(" Quota gauge unavailable (run 'claude login' or check network).")
+
+ totals = await state.usage_totals()
+ print()
+ print(f" {'Period':<10} {'Calls':>7} {'Input':>12} {'Output':>10} {'Cache read':>12} {'Est. cost':>10}")
+ for label, key in (("Today", "today"), ("7 days", "week"), ("30 days", "month")):
+ t = totals.get(key) or {}
+ print(
+ f" {label:<10} {t.get('calls', 0):>7} "
+ f"{t.get('input_tokens', 0):>12,} {t.get('output_tokens', 0):>10,} "
+ f"{t.get('cache_read_tokens', 0):>12,} ${t.get('cost_usd', 0.0):>9.2f}"
+ )
+
+ by_agent = await state.usage_by_agent(days=args.days)
+ if by_agent:
+ print(f"\n By agent (last {args.days} days):")
+ for row in by_agent:
+ print(
+ f" {row['agent']:<14} {row['calls']:>5} calls "
+ f"{row['output_tokens']:>10,} out tokens ${row['cost_usd']:.2f}"
+ )
+
+ by_task = await state.usage_by_task(days=args.days)
+ if by_task:
+ print(f"\n By task (last {args.days} days):")
+ for row in by_task[:10]:
+ print(
+ f" {row['task']:<22} {row['calls']:>5} calls ${row['cost_usd']:.2f}"
+ )
+ print(
+ "\n Costs are equivalent API list prices — what this usage would"
+ "\n have cost without your subscription.\n"
+ )
+
+ asyncio.run(_usage())
+
+
def main():
- project_root = str(Path(__file__).parent.parent)
+ from harvey.paths import PROJECT_ROOT
+ project_root = str(PROJECT_ROOT)
parser = argparse.ArgumentParser(
prog="harvey",
@@ -154,6 +261,15 @@ def main():
sub = subparsers.add_parser("status", help="Show pipeline status")
sub.set_defaults(func=cmd_status)
+ # harvey usage
+ sub = subparsers.add_parser("usage", help="Show Claude usage and quota")
+ sub.add_argument("--days", type=int, default=30, help="Breakdown window (default: 30)")
+ sub.add_argument(
+ "--reconcile", action="store_true",
+ help="Backfill usage from Claude Code transcripts first",
+ )
+ sub.set_defaults(func=cmd_usage)
+
args = parser.parse_args()
args._project_root = project_root
diff --git a/harvey/config.py b/harvey/config.py
index fa06e2d..806612e 100644
--- a/harvey/config.py
+++ b/harvey/config.py
@@ -9,6 +9,8 @@ import yaml
from dotenv import load_dotenv
from pydantic import BaseModel, ValidationError, field_validator
+from harvey.paths import PROJECT_ROOT
+
logger = logging.getLogger("harvey.config")
@@ -217,7 +219,7 @@ def _find_config_file() -> str:
candidates = [
Path.cwd() / "harvey.yaml",
Path.cwd().parent / "harvey.yaml",
- Path(__file__).parent.parent / "harvey.yaml",
+ PROJECT_ROOT / "harvey.yaml",
]
for path in candidates:
if path.exists():
diff --git a/harvey/dashboard.py b/harvey/dashboard.py
index 185b489..b7239e2 100644
--- a/harvey/dashboard.py
+++ b/harvey/dashboard.py
@@ -19,7 +19,7 @@ from fastapi.responses import HTMLResponse, JSONResponse
logger = logging.getLogger("harvey.dashboard")
-PROJECT_ROOT = Path(__file__).parent.parent
+from harvey.paths import PROJECT_ROOT # noqa: E402
DB_PATH = PROJECT_ROOT / "data" / "harvey.db"
ENV_FILE = PROJECT_ROOT / ".env"
CONFIG_FILE = PROJECT_ROOT / "harvey.yaml"
@@ -505,6 +505,67 @@ async def get_stats():
return {"error": str(e)}
+_USAGE_SUM = (
+ "COUNT(DISTINCT CASE WHEN session_id != '' THEN session_id ELSE id END) AS calls, "
+ "COALESCE(SUM(input_tokens), 0) AS input_tokens, "
+ "COALESCE(SUM(output_tokens), 0) AS output_tokens, "
+ "COALESCE(SUM(cache_read_tokens), 0) AS cache_read_tokens, "
+ "COALESCE(SUM(cache_creation_tokens), 0) AS cache_creation_tokens, "
+ "ROUND(COALESCE(SUM(cost_usd), 0), 4) AS cost_usd"
+)
+
+_quota_client = None
+
+
[email protected]("/api/usage")
+async def get_usage():
+ """Token/cost accounting + live subscription quota for the Usage tab."""
+ global _quota_client
+
+ totals = {}
+ for label, where in (
+ ("today", "date(created_at) = date('now')"),
+ ("week", "created_at >= datetime('now', '-7 days')"),
+ ("month", "created_at >= datetime('now', '-30 days')"),
+ ):
+ rows = await query_db(f"SELECT {_USAGE_SUM} FROM usage_events WHERE {where}")
+ totals[label] = rows[0] if rows else {}
+
+ def grouped(expr, alias):
+ return (
+ f"SELECT {expr} AS {alias}, {_USAGE_SUM} FROM usage_events "
+ f"WHERE created_at >= datetime('now', '-30 days') "
+ f"GROUP BY {alias} ORDER BY cost_usd DESC LIMIT 25"
+ )
+
+ by_agent = await query_db(grouped("CASE WHEN agent = '' THEN 'other' ELSE agent END", "agent"))
+ by_task = await query_db(grouped("CASE WHEN task = '' THEN 'other' ELSE task END", "task"))
+ by_model = await query_db(grouped("CASE WHEN model = '' THEN 'unknown' ELSE model END", "model"))
+ by_day = await query_db(
+ f"SELECT date(created_at) AS day, {_USAGE_SUM} FROM usage_events "
+ f"WHERE created_at >= datetime('now', '-30 days') "
+ f"GROUP BY day ORDER BY day ASC"
+ )
+
+ quota = None
+ try:
+ from harvey.integrations.quota import QuotaClient
+ if _quota_client is None:
+ _quota_client = QuotaClient()
+ quota = await _quota_client.get_utilization()
+ except Exception as e:
+ logger.debug("Quota lookup failed: %s", e)
+
+ return {
+ "quota": quota,
+ "totals": totals,
+ "by_day": by_day,
+ "by_agent": by_agent,
+ "by_task": by_task,
+ "by_model": by_model,
+ }
+
+
@app.get("/api/prospects")
async def get_prospects():
rows = await query_db("SELECT * FROM prospects ORDER BY created_at DESC LIMIT 200")
@@ -1009,6 +1070,7 @@ DASHBOARD_HTML = r"""<!DOCTYPE html>
<button onclick="showTab('campaigns', this)">Campaigns</button>
<button onclick="showTab('conversations', this)">Conversations</button>
<button onclick="showTab('activity', this)">Activity</button>
+ <button onclick="showTab('usage', this)">Usage</button>
<button onclick="showTab('settings', this)">Settings</button>
<button onclick="showTab('controls', this)">Controls</button>
<button onclick="showTab('help', this)">Help</button>
@@ -1061,6 +1123,15 @@ DASHBOARD_HTML = r"""<!DOCTYPE html>
<div id="activity-list"></div>
</div>
+<!-- Usage -->
+<div id="usage" class="section">
+ <div class="section-head"><h2>Usage</h2><p>What Harvey is spending — real subscription quota, tokens, and equivalent API cost per agent and task.</p></div>
+ <div id="usage-quota" class="card" style="display:none"></div>
+ <div class="stats-grid" id="usage-stats"></div>
+ <div class="card" id="usage-daily" style="display:none"></div>
+ <div id="usage-tables"></div>
+</div>
+
<!-- Settings -->
<div id="settings" class="section">
<div class="section-head"><h2>Settings</h2><p>Credentials are stored locally in <span style="font-family:var(--mono);font-size:12px">.env</span> — never sent anywhere except the services themselves.</p></div>
@@ -1317,6 +1388,7 @@ function loadCurrentTab() {
case 'campaigns': loadCampaigns(); break;
case 'conversations': loadConversations(); break;
case 'activity': loadActivity(); break;
+ case 'usage': loadUsage(); break;
case 'settings': loadSettings(); break;
case 'controls': loadHarveyStatus(); loadLogs(); break;
}
@@ -1517,6 +1589,112 @@ async function loadStats() {
'<span class="chip">Claude calls today <b>' + escHtml(String(data.claude_calls_today || 0)) + '</b></span>');
}
+function fmtTokens(n) {
+ n = n || 0;
+ if (n >= 1e9) return (n / 1e9).toFixed(1) + 'B';
+ if (n >= 1e6) return (n / 1e6).toFixed(1) + 'M';
+ if (n >= 1e3) return (n / 1e3).toFixed(1) + 'k';
+ return String(n);
+}
+
+function fmtCost(v) { return '$' + (v || 0).toFixed(2); }
+
+async function loadUsage() {
+ const data = await api('/api/usage');
+ const statsEl = document.getElementById('usage-stats');
+ if (!data) { statsEl.innerHTML = offlineState(); return; }
+
+ // Quota gauges — the same numbers `/usage` shows in Claude Code.
+ const quotaEl = document.getElementById('usage-quota');
+ if (data.quota && Object.keys(data.quota).length) {
+ const labels = {five_hour: '5-hour window', seven_day: 'Weekly'};
+ let qHtml = '<h2>Claude Subscription Quota</h2>';
+ for (const [key, w] of Object.entries(data.quota)) {
+ const pct = Math.min(100, Math.max(0, w.utilization || 0));
+ const color = pct >= 80 ? 'yellow' : 'green';
+ const resets = w.resets_at ? 'resets ' + formatDate(w.resets_at) : '';
+ qHtml += '<div class="progress-wrap">' +
+ '<div class="progress-label">' +
+ '<span class="text">' + escHtml(labels[key] || key) + (resets ? ' &middot; ' + escHtml(resets) : '') + '</span>' +
+ '<span class="pct">' + pct.toFixed(0) + '%</span>' +
+ '</div>' +
+ '<div class="progress-bar"><div class="progress-fill ' + color + '" style="width:' + pct + '%"></div></div>' +
+ '</div>';
+ }
+ quotaEl.innerHTML = qHtml;
+ quotaEl.style.display = 'block';
+ } else {
+ quotaEl.style.display = 'none';
+ }
+
+ // Totals cards
+ const t = data.totals || {};
+ const card = (label, p) => {
+ p = p || {};
+ return '<div class="stat-card"><div class="label">' + label + '</div>' +
+ '<div class="value">' + fmtCost(p.cost_usd) + '</div>' +
+ '<div class="breakdown">' +
+ '<span class="chip">calls <b>' + (p.calls || 0) + '</b></span>' +
+ '<span class="chip">out <b>' + fmtTokens(p.output_tokens) + '</b></span>' +
+ '<span class="chip">in <b>' + fmtTokens(p.input_tokens) + '</b></span>' +
+ '<span class="chip">cached <b>' + fmtTokens(p.cache_read_tokens) + '</b></span>' +
+ '</div></div>';
+ };
+ statsEl.innerHTML = card('Today', t.today) + card('Last 7 Days', t.week) + card('Last 30 Days', t.month);
+
+ // Daily bars
+ const dailyEl = document.getElementById('usage-daily');
+ const days = data.by_day || [];
+ if (days.length) {
+ const maxCost = Math.max(...days.map(d => d.cost_usd || 0), 0.0001);
+ let dHtml = '<h2>Daily Cost (equivalent API price, 30 days)</h2>';
+ for (const d of days.slice(-30)) {
+ const pct = Math.max(2, (d.cost_usd || 0) / maxCost * 100);
+ dHtml += '<div style="display:flex;align-items:center;gap:10px;margin-bottom:6px;font-size:12px">' +
+ '<span class="muted" style="width:78px;flex-shrink:0;font-family:var(--mono)">' + escHtml(d.day || '') + '</span>' +
+ '<div style="flex:1;background:rgba(255,255,255,0.05);border-radius:99px;height:10px;overflow:hidden">' +
+ '<div style="width:' + pct + '%;height:100%;border-radius:99px;background:linear-gradient(90deg,var(--accent-deep),var(--accent))"></div>' +
+ '</div>' +
+ '<span style="width:120px;text-align:right;font-variant-numeric:tabular-nums">' + fmtCost(d.cost_usd) +
+ ' <span class="muted">&middot; ' + (d.calls || 0) + ' calls</span></span>' +
+ '</div>';
+ }
+ dailyEl.innerHTML = dHtml;
+ dailyEl.style.display = 'block';
+ } else {
+ dailyEl.style.display = 'none';
+ }
+
+ // Breakdown tables
+ const tablesEl = document.getElementById('usage-tables');
+ const table = (title, rows, keyName) => {
+ if (!rows || !rows.length) return '';
+ let h = '<div class="card"><h2>' + title + '</h2><div class="table-card"><table><thead><tr>' +
+ '<th>' + keyName + '</th><th>Calls</th><th>Input</th><th>Output</th><th>Cache read</th><th>Est. cost</th>' +
+ '</tr></thead><tbody>';
+ for (const r of rows) {
+ h += '<tr><td>' + escHtml(String(r[keyName.toLowerCase()] || '')) + '</td>' +
+ '<td>' + (r.calls || 0) + '</td>' +
+ '<td class="muted">' + fmtTokens(r.input_tokens) + '</td>' +
+ '<td>' + fmtTokens(r.output_tokens) + '</td>' +
+ '<td class="muted">' + fmtTokens(r.cache_read_tokens) + '</td>' +
+ '<td>' + fmtCost(r.cost_usd) + '</td></tr>';
+ }
+ return h + '</tbody></table></div></div>';
+ };
+
+ const anyRows = (data.by_agent || []).length || (data.by_task || []).length;
+ if (!anyRows) {
+ tablesEl.innerHTML = emptyState('&#9680;', 'No usage recorded yet',
+ 'Once Harvey starts making Claude calls, every one is logged here with exact tokens and equivalent API cost. Run <b>harvey usage --reconcile</b> to backfill from Claude Code transcripts.');
+ } else {
+ tablesEl.innerHTML =
+ table('By Agent (30 days)', data.by_agent, 'Agent') +
+ table('By Task (30 days)', data.by_task, 'Task') +
+ table('By Model (30 days)', data.by_model, 'Model');
+ }
+}
+
async function loadCompanies() {
companyDrill = false;
const el = document.getElementById('companies-list');
@@ -1706,6 +1884,7 @@ setInterval(() => {
case 'campaigns': loadCampaigns(); break;
case 'conversations': loadConversations(); break;
case 'activity': loadActivity(); break;
+ case 'usage': loadUsage(); break;
case 'controls': loadLogs(); break;
// settings & help: never auto-refreshed (user may be typing)
}
diff --git a/harvey/integrations/linkedin.py b/harvey/integrations/linkedin.py
index 92c5a7d..b06bdfa 100644
--- a/harvey/integrations/linkedin.py
+++ b/harvey/integrations/linkedin.py
@@ -16,7 +16,9 @@ from urllib.parse import quote_plus
logger = logging.getLogger("harvey.linkedin")
-DATA_DIR = Path(__file__).parent.parent.parent / "data"
+from harvey.paths import PROJECT_ROOT
+
+DATA_DIR = PROJECT_ROOT / "data"
COOKIES_PATH = DATA_DIR / "linkedin_cookies.json"
ACTIVITY_PATH = DATA_DIR / "linkedin_activity.json"
diff --git a/harvey/integrations/quota.py b/harvey/integrations/quota.py
new file mode 100644
index 0000000..558e023
--- /dev/null
+++ b/harvey/integrations/quota.py
@@ -0,0 +1,196 @@
+"""Claude subscription quota gauge.
+
+Reads the real 5-hour-window and weekly utilization the same way Claude
+Code's own /usage command does: GET api.anthropic.com/api/oauth/usage with
+the locally-stored OAuth token. The endpoint is undocumented, so every
+failure degrades to None and callers fall back to Harvey's own call
+counting. Responses are cached in-memory to stay polite.
+"""
+
+import asyncio
+import json
+import logging
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Optional
+
+import httpx
+
+from harvey.usage import claude_config_dir
+
+logger = logging.getLogger("harvey.quota")
+
+USAGE_URL = "https://api.anthropic.com/api/oauth/usage"
+OAUTH_BETA_HEADER = "oauth-2025-04-20"
+CACHE_TTL_OK = 300.0 # seconds to reuse a good response
+CACHE_TTL_FAIL = 60.0 # seconds to back off after a failure
+REQUEST_TIMEOUT = httpx.Timeout(connect=5.0, read=10.0, write=5.0, pool=5.0)
+
+# macOS keychain item Claude Code stores credentials under.
+KEYCHAIN_SERVICE = "Claude Code-credentials"
+
+
+def _token_from_json_blob(blob: str) -> Optional[str]:
+ try:
+ data = json.loads(blob)
+ except (json.JSONDecodeError, TypeError):
+ return None
+ if not isinstance(data, dict):
+ return None
+ oauth = data.get("claudeAiOauth")
+ if isinstance(oauth, dict):
+ token = oauth.get("accessToken")
+ if isinstance(token, str) and token:
+ return token
+ return None
+
+
+def get_oauth_token() -> Optional[str]:
+ """Find the Claude Code OAuth access token on this machine.
+
+ Tries the credentials file (Linux / CLAUDE_CONFIG_DIR overrides),
+ then the macOS keychain. Returns None when not logged in.
+ """
+ creds_file = claude_config_dir() / ".credentials.json"
+ try:
+ if creds_file.is_file():
+ token = _token_from_json_blob(creds_file.read_text())
+ if token:
+ return token
+ except OSError as e:
+ logger.debug(f"Could not read {creds_file}: {e}")
+
+ # Default config dir fallback, in case CLAUDE_CONFIG_DIR points elsewhere
+ default_creds = Path.home() / ".claude" / ".credentials.json"
+ if default_creds != creds_file:
+ try:
+ if default_creds.is_file():
+ token = _token_from_json_blob(default_creds.read_text())
+ if token:
+ return token
+ except OSError:
+ pass
+
+ if sys.platform == "darwin":
+ # Claude Code stores credentials per config dir: the default item is
+ # "Claude Code-credentials", but a CLAUDE_CONFIG_DIR install uses a
+ # hash-suffixed service name (and the default item may hold an empty
+ # token). Enumerate every matching service and take the first item
+ # with a real token.
+ for service in _keychain_services():
+ try:
+ result = subprocess.run(
+ ["security", "find-generic-password", "-s", service, "-w"],
+ capture_output=True, text=True, timeout=5,
+ )
+ except (subprocess.TimeoutExpired, OSError) as e:
+ logger.debug(f"Keychain lookup failed for {service}: {e}")
+ continue
+ if result.returncode == 0:
+ token = _token_from_json_blob(result.stdout.strip())
+ if token:
+ return token
+
+ return None
+
+
+def _keychain_services() -> list[str]:
+ """All keychain service names Claude Code may store credentials under."""
+ services = [KEYCHAIN_SERVICE]
+ try:
+ dump = subprocess.run(
+ ["security", "dump-keychain"],
+ capture_output=True, text=True, timeout=10,
+ )
+ if dump.returncode == 0:
+ for line in dump.stdout.splitlines():
+ # Lines look like: "svce"<blob>="Claude Code-credentials-53f815ad"
+ if '"svce"<blob>="' not in line:
+ continue
+ name = line.split('"svce"<blob>="', 1)[1].rstrip('"')
+ if name.startswith(KEYCHAIN_SERVICE) and name not in services:
+ services.append(name)
+ except (subprocess.TimeoutExpired, OSError) as e:
+ logger.debug(f"Keychain enumeration failed: {e}")
+ return services
+
+
+def _parse_window(value) -> Optional[dict]:
+ """Normalize one utilization window to {'utilization': float, 'resets_at': str}."""
+ if not isinstance(value, dict):
+ return None
+ utilization = value.get("utilization")
+ if not isinstance(utilization, (int, float)):
+ return None
+ resets_at = value.get("resets_at") or value.get("resetsAt") or ""
+ return {
+ "utilization": float(utilization),
+ "resets_at": str(resets_at) if resets_at else "",
+ }
+
+
+class QuotaClient:
+ """Cached reader of Claude subscription utilization."""
+
+ def __init__(self):
+ self._cache: Optional[dict] = None
+ self._cache_at = 0.0
+ self._cache_ttl = 0.0
+ self._lock = asyncio.Lock()
+
+ async def get_utilization(self) -> Optional[dict]:
+ """Return {'five_hour': {...}, 'seven_day': {...}} or None.
+
+ Each window dict has 'utilization' (percent, 0-100) and
+ 'resets_at' (ISO timestamp or ''). Missing windows are omitted;
+ an empty result is reported as None.
+ """
+ async with self._lock:
+ now = time.monotonic()
+ if self._cache_at and now - self._cache_at < self._cache_ttl:
+ return self._cache
+
+ result = await self._fetch()
+ self._cache = result
+ self._cache_at = now
+ self._cache_ttl = CACHE_TTL_OK if result else CACHE_TTL_FAIL
+ return result
+
+ async def _fetch(self) -> Optional[dict]:
+ token = await asyncio.get_event_loop().run_in_executor(None, get_oauth_token)
+ if not token:
+ logger.debug("Quota: no Claude OAuth token found; falling back.")
+ return None
+
+ try:
+ async with httpx.AsyncClient(timeout=REQUEST_TIMEOUT) as client:
+ resp = await client.get(
+ USAGE_URL,
+ headers={
+ "Authorization": f"Bearer {token}",
+ "anthropic-beta": OAUTH_BETA_HEADER,
+ },
+ )
+ except httpx.HTTPError as e:
+ logger.debug(f"Quota fetch failed: {e}")
+ return None
+
+ if resp.status_code != 200:
+ logger.debug(f"Quota endpoint returned {resp.status_code}.")
+ return None
+
+ try:
+ payload = resp.json()
+ except ValueError:
+ return None
+ if not isinstance(payload, dict):
+ return None
+
+ windows = {}
+ for key in ("five_hour", "seven_day"):
+ parsed = _parse_window(payload.get(key))
+ if parsed:
+ windows[key] = parsed
+ return windows or None
diff --git a/harvey/main.py b/harvey/main.py
index dbdef17..1f0c8ec 100644
--- a/harvey/main.py
+++ b/harvey/main.py
@@ -153,11 +153,15 @@ async def heartbeat(stop_event: asyncio.Event | None = None):
break
continue
- # 2. Check usage budget
- if not await brain.is_within_budget(max_calls):
+ # 2. Check usage budget (real subscription quota when readable,
+ # else Harvey's own call counter)
+ if not await brain.is_within_budget(
+ max_calls, max_percent=config.usage.max_daily_claude_percent
+ ):
logger.info(
- f"Daily usage limit reached ({max_calls} calls). "
- "Sleeping 1h, then re-checking (resets at midnight)."
+ f"Claude usage limit reached "
+ f"({config.usage.max_daily_claude_percent}% of quota or "
+ f"{max_calls} calls). Sleeping 1h, then re-checking."
)
if await _interruptible_sleep(3600, stop_event):
break
@@ -242,7 +246,8 @@ async def heartbeat(stop_event: asyncio.Event | None = None):
def _needs_setup() -> bool:
"""Check if Harvey needs first-time setup."""
from pathlib import Path
- project_root = Path(__file__).parent.parent
+ from harvey.paths import PROJECT_ROOT
+ project_root = PROJECT_ROOT
env_file = project_root / ".env"
config_file = project_root / "harvey.yaml"
diff --git a/harvey/paths.py b/harvey/paths.py
new file mode 100644
index 0000000..6319d9f
--- /dev/null
+++ b/harvey/paths.py
@@ -0,0 +1,12 @@
+"""Canonical filesystem locations for the Harvey checkout.
+
+Harvey is repo-centric: config (harvey.yaml, .env), knowledge (prompts/,
+skills/), and state (data/) all live next to the package. ``resolve()``
+matters — when the package is reached through a symlink (some editable
+installs), a bare ``Path(__file__).parent`` would point into
+site-packages and Harvey would silently read/write the wrong files.
+"""
+
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
diff --git a/harvey/setup.py b/harvey/setup.py
index 61869db..aec9b29 100644
--- a/harvey/setup.py
+++ b/harvey/setup.py
@@ -13,7 +13,7 @@ from harvey.state import StateManager
logger = logging.getLogger("harvey.setup")
-PROJECT_ROOT = Path(__file__).parent.parent
+from harvey.paths import PROJECT_ROOT
ENV_FILE = PROJECT_ROOT / ".env"
ENV_EXAMPLE = PROJECT_ROOT / ".env.example"
CONFIG_FILE = PROJECT_ROOT / "harvey.yaml"
diff --git a/harvey/state.py b/harvey/state.py
index befc2e0..93bbc50 100644
--- a/harvey/state.py
+++ b/harvey/state.py
@@ -22,7 +22,9 @@ from harvey.models.prospect import Prospect
from harvey.models.campaign import Campaign, EmailStep # noqa: F401 (EmailStep re-exported)
from harvey.models.conversation import Conversation, Message # noqa: F401
-DB_PATH = Path(__file__).parent.parent / "data" / "harvey.db"
+from harvey.paths import PROJECT_ROOT
+
+DB_PATH = PROJECT_ROOT / "data" / "harvey.db"
# How long (seconds) a connection waits on a locked database before failing.
BUSY_TIMEOUT_SECONDS = 30.0
@@ -187,6 +189,35 @@ MIGRATIONS: list[str] = [
CREATE INDEX IF NOT EXISTS idx_prospects_status_updated ON prospects(status, updated_at);
CREATE INDEX IF NOT EXISTS idx_actions_created_at ON actions(created_at);
""",
+ # ── v3: per-call usage accounting (tokens, cost, attribution) ──
+ """
+ CREATE TABLE IF NOT EXISTS usage_events (
+ id TEXT PRIMARY KEY,
+ created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+ agent TEXT DEFAULT '',
+ task TEXT DEFAULT '',
+ session_id TEXT DEFAULT '',
+ request_key TEXT DEFAULT '',
+ model TEXT DEFAULT '',
+ input_tokens INTEGER DEFAULT 0,
+ output_tokens INTEGER DEFAULT 0,
+ cache_read_tokens INTEGER DEFAULT 0,
+ cache_creation_tokens INTEGER DEFAULT 0,
+ cost_usd REAL DEFAULT 0.0,
+ duration_ms INTEGER DEFAULT 0,
+ num_turns INTEGER DEFAULT 0,
+ is_error INTEGER DEFAULT 0,
+ source TEXT DEFAULT 'result_json'
+ );
+
+ CREATE INDEX IF NOT EXISTS idx_usage_events_created ON usage_events(created_at);
+ CREATE INDEX IF NOT EXISTS idx_usage_events_agent ON usage_events(agent);
+ CREATE INDEX IF NOT EXISTS idx_usage_events_session ON usage_events(session_id);
+ -- Transcript-backfilled rows carry a request_key; uniqueness makes
+ -- reconciliation idempotent (INSERT OR IGNORE).
+ CREATE UNIQUE INDEX IF NOT EXISTS uq_usage_events_request
+ ON usage_events(request_key) WHERE request_key != '';
+ """,
]
# Column whitelists for dynamic UPDATEs (prevents SQL injection via kwargs).
@@ -686,6 +717,136 @@ class StateManager:
)
await db.commit()
+ # ── Per-call usage accounting (usage_events) ──
+
+ async def record_usage_event(
+ self,
+ *,
+ agent: str = "",
+ task: str = "",
+ session_id: str = "",
+ request_key: str = "",
+ model: str = "",
+ input_tokens: int = 0,
+ output_tokens: int = 0,
+ cache_read_tokens: int = 0,
+ cache_creation_tokens: int = 0,
+ cost_usd: float = 0.0,
+ duration_ms: int = 0,
+ num_turns: int = 0,
+ is_error: bool = False,
+ source: str = "result_json",
+ created_at: str | None = None,
+ ) -> bool:
+ """Insert one usage row (one model within one Claude call).
+
+ Returns False when the row was skipped as a duplicate (request_key
+ uniqueness makes transcript reconciliation idempotent).
+ """
+ async with self._connect() as db:
+ cursor = await db.execute(
+ """INSERT OR IGNORE INTO usage_events
+ (id, created_at, agent, task, session_id, request_key, model,
+ input_tokens, output_tokens, cache_read_tokens,
+ cache_creation_tokens, cost_usd, duration_ms, num_turns,
+ is_error, source)
+ VALUES (?, COALESCE(?, CURRENT_TIMESTAMP), ?, ?, ?, ?, ?,
+ ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+ (
+ _new_id(), created_at, agent, task, session_id, request_key,
+ model, int(input_tokens or 0), int(output_tokens or 0),
+ int(cache_read_tokens or 0), int(cache_creation_tokens or 0),
+ float(cost_usd or 0.0), int(duration_ms or 0),
+ int(num_turns or 0), 1 if is_error else 0, source,
+ ),
+ )
+ await db.commit()
+ return cursor.rowcount > 0
+
+ async def get_recorded_session_ids(self) -> set[str]:
+ """Session IDs already captured live (skip during reconciliation)."""
+ async with self._connect() as db:
+ async with db.execute(
+ "SELECT DISTINCT session_id FROM usage_events "
+ "WHERE source = 'result_json' AND session_id != ''"
+ ) as cursor:
+ return {row[0] for row in await cursor.fetchall()}
+
+ _USAGE_SUM = (
+ "COUNT(DISTINCT CASE WHEN session_id != '' THEN session_id ELSE id END) AS calls, "
+ "SUM(input_tokens) AS input_tokens, "
+ "SUM(output_tokens) AS output_tokens, "
+ "SUM(cache_read_tokens) AS cache_read_tokens, "
+ "SUM(cache_creation_tokens) AS cache_creation_tokens, "
+ "SUM(cost_usd) AS cost_usd"
+ )
+
+ @staticmethod
+ def _usage_row_to_dict(row: aiosqlite.Row) -> dict:
+ d = dict(row)
+ for key, value in d.items():
+ if value is None and key != "period":
+ d[key] = 0
+ if "cost_usd" in d:
+ d["cost_usd"] = round(float(d["cost_usd"] or 0.0), 6)
+ return d
+
+ async def _usage_grouped(self, group_expr: str, alias: str, days: int) -> list[dict]:
+ sql = (
+ f"SELECT {group_expr} AS {alias}, {self._USAGE_SUM} "
+ f"FROM usage_events "
+ f"WHERE created_at >= datetime('now', ?) "
+ f"GROUP BY {alias} ORDER BY cost_usd DESC"
+ )
+ async with self._connect() as db:
+ db.row_factory = aiosqlite.Row
+ async with db.execute(sql, (f"-{int(days)} days",)) as cursor:
+ return [self._usage_row_to_dict(r) for r in await cursor.fetchall()]
+
+ async def usage_by_agent(self, days: int = 30) -> list[dict]:
+ return await self._usage_grouped(
+ "CASE WHEN agent = '' THEN 'other' ELSE agent END", "agent", days
+ )
+
+ async def usage_by_task(self, days: int = 30) -> list[dict]:
+ return await self._usage_grouped(
+ "CASE WHEN task = '' THEN 'other' ELSE task END", "task", days
+ )
+
+ async def usage_by_model(self, days: int = 30) -> list[dict]:
+ return await self._usage_grouped(
+ "CASE WHEN model = '' THEN 'unknown' ELSE model END", "model", days
+ )
+
+ async def usage_by_day(self, days: int = 30) -> list[dict]:
+ sql = (
+ f"SELECT date(created_at) AS day, {self._USAGE_SUM} "
+ f"FROM usage_events "
+ f"WHERE created_at >= datetime('now', ?) "
+ f"GROUP BY day ORDER BY day ASC"
+ )
+ async with self._connect() as db:
+ db.row_factory = aiosqlite.Row
+ async with db.execute(sql, (f"-{int(days)} days",)) as cursor:
+ return [self._usage_row_to_dict(r) for r in await cursor.fetchall()]
+
+ async def usage_totals(self) -> dict:
+ """Rollups for today / last 7 days / last 30 days (UTC)."""
+ totals = {}
+ async with self._connect() as db:
+ db.row_factory = aiosqlite.Row
+ for label, where in (
+ ("today", "date(created_at) = date('now')"),
+ ("week", "created_at >= datetime('now', '-7 days')"),
+ ("month", "created_at >= datetime('now', '-30 days')"),
+ ):
+ async with db.execute(
+ f"SELECT {self._USAGE_SUM} FROM usage_events WHERE {where}"
+ ) as cursor:
+ row = await cursor.fetchone()
+ totals[label] = self._usage_row_to_dict(row) if row else {}
+ return totals
+
# ── Summary for Decision Making ──
async def get_state_summary(self) -> dict:
diff --git a/harvey/trainer.py b/harvey/trainer.py
index ee8dfeb..fc56d0c 100644
--- a/harvey/trainer.py
+++ b/harvey/trainer.py
@@ -21,7 +21,7 @@ from harvey.state import StateManager
logger = logging.getLogger("harvey.trainer")
-PROJECT_ROOT = Path(__file__).parent.parent
+from harvey.paths import PROJECT_ROOT
def _normalize_start_url(url: str) -> str:
@@ -630,7 +630,7 @@ Do NOT pursue prospects who:
{product_info.get('tone', 'professional, consultative, confident')}
"""
- skills_path = Path(__file__).parent.parent / "skills" / "product_knowledge.md"
+ skills_path = PROJECT_ROOT / "skills" / "product_knowledge.md"
skills_path.write_text(knowledge)
print(f" Generated: skills/product_knowledge.md")
@@ -678,7 +678,7 @@ What prospects do instead of buying a solution like ours:
---
"""
- skills_path = Path(__file__).parent.parent / "skills" / "competitive_intel.md"
+ skills_path = PROJECT_ROOT / "skills" / "competitive_intel.md"
skills_path.write_text(cards)
print(f" Generated: skills/competitive_intel.md")
diff --git a/harvey/usage.py b/harvey/usage.py
new file mode 100644
index 0000000..3f8211a
--- /dev/null
+++ b/harvey/usage.py
@@ -0,0 +1,221 @@
+"""Usage accounting — model pricing and Claude Code transcript reconciliation.
+
+Harvey's primary usage source is the per-call result JSON from `claude -p
+--output-format json` (recorded live by the Brain). This module supplies:
+
+1. A pricing table + cost math for when the CLI doesn't report a cost
+ (transcript rows have ``costUSD: null`` on Max subscriptions).
+2. A reconciler that scans Claude Code's JSONL transcripts and backfills
+ usage_events rows for calls the live path missed (crashes, other tools
+ using Claude on this machine). Idempotent: rows are keyed by
+ (message.id, requestId) with a unique index, and sessions already
+ captured live are skipped entirely.
+"""
+
+import json
+import logging
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+from harvey.state import StateManager
+
+logger = logging.getLogger("harvey.usage")
+
+# USD per million tokens: (input, output). Matched by longest prefix, so
+# order here doesn't matter but specificity does — the dated Opus 4.0 id
+# must not fall through to the modern "claude-opus-4" rate.
+PRICING: dict[str, tuple[float, float]] = {
+ "claude-fable-5": (10.0, 50.0),
+ "claude-mythos": (10.0, 50.0),
+ "claude-opus-4-2025": (15.0, 75.0), # claude-opus-4-20250514 (Opus 4.0)
+ "claude-opus-4-0": (15.0, 75.0),
+ "claude-opus-4-1": (15.0, 75.0),
+ "claude-opus-4": (5.0, 25.0), # Opus 4.5 / 4.6 / 4.7 / 4.8
+ "claude-sonnet": (3.0, 15.0),
+ "claude-haiku-4": (1.0, 5.0),
+ "claude-3-5-haiku": (0.8, 4.0),
+ "claude-3-haiku": (0.25, 1.25),
+}
+
+# Cache pricing multipliers relative to base input price.
+CACHE_READ_MULT = 0.1
+CACHE_WRITE_5M_MULT = 1.25
+CACHE_WRITE_1H_MULT = 2.0
+
+
+def match_pricing(model: str) -> tuple[float, float] | None:
+ """Longest-prefix match a model id to (input, output) $/MTok."""
+ if not model:
+ return None
+ best_key = ""
+ for key in PRICING:
+ if model.startswith(key) and len(key) > len(best_key):
+ best_key = key
+ return PRICING[best_key] if best_key else None
+
+
+def compute_cost(
+ model: str,
+ input_tokens: int = 0,
+ output_tokens: int = 0,
+ cache_read_tokens: int = 0,
+ cache_write_5m_tokens: int = 0,
+ cache_write_1h_tokens: int = 0,
+) -> float:
+ """Equivalent API-list-price cost in USD. 0.0 for unknown models."""
+ prices = match_pricing(model)
+ if not prices:
+ return 0.0
+ p_in, p_out = prices
+ per_tok_in = p_in / 1_000_000
+ per_tok_out = p_out / 1_000_000
+ return (
+ input_tokens * per_tok_in
+ + output_tokens * per_tok_out
+ + cache_read_tokens * per_tok_in * CACHE_READ_MULT
+ + cache_write_5m_tokens * per_tok_in * CACHE_WRITE_5M_MULT
+ + cache_write_1h_tokens * per_tok_in * CACHE_WRITE_1H_MULT
+ )
+
+
+def claude_config_dir() -> Path:
+ """Claude Code's config directory (honors CLAUDE_CONFIG_DIR)."""
+ override = os.environ.get("CLAUDE_CONFIG_DIR", "").strip()
+ if override:
+ return Path(override).expanduser()
+ return Path.home() / ".claude"
+
+
+def _iso_to_sqlite_utc(ts: str) -> str | None:
+ """'2026-08-28T20:15:03.123Z' -> '2026-08-28 20:15:03' (UTC, naive)."""
+ if not ts:
+ return None
+ try:
+ dt = datetime.fromisoformat(ts.replace("Z", "+00:00"))
+ if dt.tzinfo is not None:
+ dt = dt.astimezone(timezone.utc).replace(tzinfo=None)
+ return dt.strftime("%Y-%m-%d %H:%M:%S")
+ except ValueError:
+ return None
+
+
+def parse_transcript_events(path: Path) -> dict[str, dict]:
+ """Extract per-request usage from one session transcript.
+
+ Returns {request_key: event_dict}. Claude Code writes multiple
+ entries per API request (streaming snapshots, resume replays) — the
+ LAST entry per (message.id, requestId) is authoritative, so later
+ lines simply overwrite earlier ones here.
+ """
+ events: dict[str, dict] = {}
+ try:
+ with path.open(encoding="utf-8", errors="replace") as f:
+ for line in f:
+ line = line.strip()
+ if not line:
+ continue
+ try:
+ entry = json.loads(line)
+ except json.JSONDecodeError:
+ continue
+ if not isinstance(entry, dict) or entry.get("type") != "assistant":
+ continue
+ message = entry.get("message")
+ if not isinstance(message, dict):
+ continue
+ usage = message.get("usage")
+ if not isinstance(usage, dict):
+ continue
+
+ msg_id = str(message.get("id") or "")
+ req_id = str(entry.get("requestId") or "")
+ if not msg_id and not req_id:
+ continue
+ key = f"{msg_id}:{req_id}"
+
+ model = str(message.get("model") or "")
+ input_tokens = int(usage.get("input_tokens") or 0)
+ output_tokens = int(usage.get("output_tokens") or 0)
+ cache_read = int(usage.get("cache_read_input_tokens") or 0)
+ cache_creation = int(usage.get("cache_creation_input_tokens") or 0)
+
+ # 5m/1h split (when present) prices cache writes correctly.
+ split = usage.get("cache_creation")
+ if isinstance(split, dict):
+ write_1h = int(split.get("ephemeral_1h_input_tokens") or 0)
+ write_5m = int(split.get("ephemeral_5m_input_tokens") or 0)
+ else:
+ write_1h, write_5m = 0, cache_creation
+
+ cost = entry.get("costUSD")
+ if not isinstance(cost, (int, float)):
+ cost = compute_cost(
+ model,
+ input_tokens=input_tokens,
+ output_tokens=output_tokens,
+ cache_read_tokens=cache_read,
+ cache_write_5m_tokens=write_5m,
+ cache_write_1h_tokens=write_1h,
+ )
+
+ events[key] = {
+ "request_key": key,
+ "session_id": str(entry.get("sessionId") or ""),
+ "model": model,
+ "input_tokens": input_tokens,
+ "output_tokens": output_tokens,
+ "cache_read_tokens": cache_read,
+ "cache_creation_tokens": cache_creation,
+ "cost_usd": float(cost),
+ "created_at": _iso_to_sqlite_utc(str(entry.get("timestamp") or "")),
+ }
+ except OSError as e:
+ logger.debug(f"Could not read transcript {path}: {e}")
+ return events
+
+
+async def reconcile_transcripts(
+ state: StateManager,
+ since_days: int = 7,
+ config_dir: Path | None = None,
+) -> int:
+ """Backfill usage_events from Claude Code JSONL transcripts.
+
+ Only touches transcripts modified in the last ``since_days`` days,
+ skips sessions Harvey already recorded live, and relies on the
+ request_key unique index for idempotency. Returns rows inserted.
+ """
+ base = (config_dir or claude_config_dir()) / "projects"
+ if not base.is_dir():
+ logger.debug(f"No Claude transcripts directory at {base}")
+ return 0
+
+ try:
+ recorded_sessions = await state.get_recorded_session_ids()
+ except Exception as e:
+ logger.warning(f"Could not load recorded sessions: {e}")
+ recorded_sessions = set()
+
+ cutoff = datetime.now().timestamp() - since_days * 86400
+ inserted = 0
+
+ for path in base.glob("*/*.jsonl"):
+ try:
+ if path.stat().st_mtime < cutoff:
+ continue
+ except OSError:
+ continue
+
+ for event in parse_transcript_events(path).values():
+ if event["session_id"] and event["session_id"] in recorded_sessions:
+ continue
+ try:
+ if await state.record_usage_event(source="transcript", **event):
+ inserted += 1
+ except Exception as e:
+ logger.debug(f"Failed to record transcript event: {e}")
+
+ if inserted:
+ logger.info(f"Usage reconcile: backfilled {inserted} transcript event(s).")
+ return inserted
diff --git a/tests/test_usage.py b/tests/test_usage.py
new file mode 100644
index 0000000..2b2721b
--- /dev/null
+++ b/tests/test_usage.py
@@ -0,0 +1,267 @@
+"""Tests for usage tracking: schema, pricing, result parsing, reconciliation, quota."""
+
+import json
+import os
+import tempfile
+from pathlib import Path
+
+import pytest
+import pytest_asyncio
+
+from harvey.brain import Brain
+from harvey.state import StateManager
+from harvey.usage import (
+ compute_cost,
+ match_pricing,
+ parse_transcript_events,
+ reconcile_transcripts,
+)
+from harvey.integrations.quota import _parse_window, _token_from_json_blob
+
+
+@pytest_asyncio.fixture
+async def state():
+ with tempfile.TemporaryDirectory() as tmpdir:
+ db_path = os.path.join(tmpdir, "test.db")
+ sm = StateManager(db_path)
+ await sm.init_db()
+ yield sm
+
+
+# ── usage_events table + aggregations ──
+
+
+async def test_record_usage_event_and_totals(state):
+ ok = await state.record_usage_event(
+ agent="writer", task="write_sequence", session_id="sess-1",
+ model="claude-opus-4-8", input_tokens=100, output_tokens=500,
+ cache_read_tokens=2000, cache_creation_tokens=300,
+ cost_usd=0.05, duration_ms=1200, num_turns=1,
+ )
+ assert ok
+
+ totals = await state.usage_totals()
+ assert totals["today"]["calls"] == 1
+ assert totals["today"]["output_tokens"] == 500
+ assert totals["today"]["cost_usd"] == pytest.approx(0.05)
+ assert totals["week"]["input_tokens"] == 100
+
+
+async def test_usage_by_agent_groups_and_counts_sessions(state):
+ # Two model-rows from the SAME call (same session) → one "call"
+ await state.record_usage_event(
+ agent="scout", session_id="sess-a", model="claude-opus-4-8",
+ output_tokens=10, cost_usd=0.01,
+ )
+ await state.record_usage_event(
+ agent="scout", session_id="sess-a", model="claude-haiku-4-5",
+ output_tokens=5, cost_usd=0.001,
+ )
+ await state.record_usage_event(
+ agent="handler", session_id="sess-b", model="claude-opus-4-8",
+ output_tokens=20, cost_usd=0.02,
+ )
+
+ rows = await state.usage_by_agent(days=7)
+ by_name = {r["agent"]: r for r in rows}
+ assert by_name["scout"]["calls"] == 1
+ assert by_name["scout"]["output_tokens"] == 15
+ assert by_name["handler"]["calls"] == 1
+
+
+async def test_request_key_dedup(state):
+ first = await state.record_usage_event(
+ request_key="msg_1:req_1", model="claude-opus-4-8",
+ output_tokens=50, source="transcript",
+ )
+ second = await state.record_usage_event(
+ request_key="msg_1:req_1", model="claude-opus-4-8",
+ output_tokens=50, source="transcript",
+ )
+ assert first is True
+ assert second is False # unique index makes reconciliation idempotent
+
+ totals = await state.usage_totals()
+ assert totals["today"]["output_tokens"] == 50
+
+
+# ── pricing ──
+
+
+def test_match_pricing_prefixes():
+ assert match_pricing("claude-opus-4-8") == (5.0, 25.0)
+ assert match_pricing("claude-opus-4-5-20251101") == (5.0, 25.0)
+ # Dated Opus 4.0 must NOT get the modern rate
+ assert match_pricing("claude-opus-4-20250514") == (15.0, 75.0)
+ assert match_pricing("claude-haiku-4-5-20251001") == (1.0, 5.0)
+ assert match_pricing("claude-fable-5") == (10.0, 50.0)
+ assert match_pricing("gpt-4o") is None
+ assert match_pricing("") is None
+
+
+def test_compute_cost_with_cache_tiers():
+ # 1M of everything on Haiku: 1 + 5 + 0.1 + 1.25 + 2.0
+ cost = compute_cost(
+ "claude-haiku-4-5",
+ input_tokens=1_000_000,
+ output_tokens=1_000_000,
+ cache_read_tokens=1_000_000,
+ cache_write_5m_tokens=1_000_000,
+ cache_write_1h_tokens=1_000_000,
+ )
+ assert cost == pytest.approx(1 + 5 + 0.1 + 1.25 + 2.0)
+ assert compute_cost("unknown-model", output_tokens=1000) == 0.0
+
+
+# ── Brain result-JSON parsing ──
+
+
+SAMPLE_RESULT = {
+ "type": "result",
+ "subtype": "success",
+ "is_error": False,
+ "duration_ms": 1428,
+ "num_turns": 1,
+ "result": "Hello from Claude",
+ "session_id": "f362e409-925c-4eb1-ba98-60484bb2dcf5",
+ "total_cost_usd": 0.0182948,
+ "usage": {"input_tokens": 10, "output_tokens": 51},
+ "modelUsage": {
+ "claude-haiku-4-5-20251001": {
+ "inputTokens": 10, "outputTokens": 51,
+ "cacheReadInputTokens": 17198, "cacheCreationInputTokens": 8155,
+ "costUSD": 0.0182948,
+ }
+ },
+}
+
+
+def test_parse_result_payload_json():
+ text, payload = Brain._parse_result_payload(json.dumps(SAMPLE_RESULT))
+ assert text == "Hello from Claude"
+ assert payload["session_id"] == "f362e409-925c-4eb1-ba98-60484bb2dcf5"
+
+
+def test_parse_result_payload_plain_text_fallback():
+ text, payload = Brain._parse_result_payload("just plain text output")
+ assert text == "just plain text output"
+ assert payload is None
+ # A JSON response body that isn't a CLI result envelope stays verbatim
+ text2, payload2 = Brain._parse_result_payload('{"intent": "interested"}')
+ assert text2 == '{"intent": "interested"}'
+ assert payload2 is None
+
+
+async def test_brain_records_usage_from_payload(state):
+ brain = Brain(state)
+ await brain._record_usage(
+ SAMPLE_RESULT, agent="", task="", label="harvey-scout-score"
+ )
+ rows = await state.usage_by_agent(days=1)
+ assert len(rows) == 1
+ assert rows[0]["agent"] == "scout" # derived from the harvey-* label
+ assert rows[0]["output_tokens"] == 51
+ assert rows[0]["cost_usd"] == pytest.approx(0.0182948, abs=1e-4)
+
+ by_model = await state.usage_by_model(days=1)
+ assert by_model[0]["model"] == "claude-haiku-4-5-20251001"
+
+
+# ── transcript reconciliation ──
+
+
+def _write_transcript(path: Path, entries: list[dict]):
+ path.parent.mkdir(parents=True, exist_ok=True)
+ with path.open("w") as f:
+ for e in entries:
+ f.write(json.dumps(e) + "\n")
+
+
+def _assistant_entry(msg_id, req_id, session, output_tokens, cost=None):
+ return {
+ "type": "assistant",
+ "sessionId": session,
+ "requestId": req_id,
+ "timestamp": "2026-08-28T20:15:03.123Z",
+ "costUSD": cost,
+ "message": {
+ "id": msg_id,
+ "model": "claude-opus-4-8",
+ "usage": {
+ "input_tokens": 10,
+ "output_tokens": output_tokens,
+ "cache_read_input_tokens": 100,
+ "cache_creation_input_tokens": 50,
+ "cache_creation": {
+ "ephemeral_1h_input_tokens": 50,
+ "ephemeral_5m_input_tokens": 0,
+ },
+ },
+ },
+ }
+
+
+def test_parse_transcript_keeps_last_duplicate(tmp_path):
+ transcript = tmp_path / "projects" / "proj" / "sess.jsonl"
+ _write_transcript(transcript, [
+ _assistant_entry("msg_1", "req_1", "sess-x", 5), # streaming snapshot
+ _assistant_entry("msg_1", "req_1", "sess-x", 51), # authoritative final
+ {"type": "user", "message": {"content": "hi"}}, # ignored
+ {"not": "even a dict of the right shape"}, # ignored
+ ])
+ events = parse_transcript_events(transcript)
+ assert len(events) == 1
+ event = events["msg_1:req_1"]
+ assert event["output_tokens"] == 51
+ # costUSD null on Max → computed from pricing (Opus 4-8: $5/$25)
+ expected = compute_cost(
+ "claude-opus-4-8", input_tokens=10, output_tokens=51,
+ cache_read_tokens=100, cache_write_1h_tokens=50,
+ )
+ assert event["cost_usd"] == pytest.approx(expected)
+ assert event["created_at"] == "2026-08-28 20:15:03"
+
+
+async def test_reconcile_skips_live_sessions_and_is_idempotent(state, tmp_path):
+ # Session recorded live by the Brain → its transcript must be skipped
+ await state.record_usage_event(
+ agent="writer", session_id="sess-live", model="claude-opus-4-8",
+ output_tokens=99, source="result_json",
+ )
+ _write_transcript(tmp_path / "projects" / "p1" / "a.jsonl",
+ [_assistant_entry("m1", "r1", "sess-live", 99)])
+ _write_transcript(tmp_path / "projects" / "p2" / "b.jsonl",
+ [_assistant_entry("m2", "r2", "sess-other", 40)])
+
+ inserted = await reconcile_transcripts(state, since_days=7, config_dir=tmp_path)
+ assert inserted == 1 # only sess-other
+
+ # Second run inserts nothing (request_key unique index)
+ inserted_again = await reconcile_transcripts(state, since_days=7, config_dir=tmp_path)
+ assert inserted_again == 0
+
+ totals = await state.usage_totals()
+ assert totals["month"]["output_tokens"] == 99 + 40
+
+
+# ── quota client helpers ──
+
+
+def test_token_from_json_blob():
+ blob = json.dumps({"claudeAiOauth": {"accessToken": "sk-ant-oat01-abc"}})
+ assert _token_from_json_blob(blob) == "sk-ant-oat01-abc"
+ assert _token_from_json_blob("not json") is None
+ assert _token_from_json_blob(json.dumps({"other": 1})) is None
+
+
+def test_parse_window():
+ parsed = _parse_window({"utilization": 42.5, "resets_at": "2026-08-29T01:00:00Z"})
+ assert parsed == {"utilization": 42.5, "resets_at": "2026-08-29T01:00:00Z"}
+ assert _parse_window({"utilization": "bad"}) is None
+ assert _parse_window(None) is None
+ assert _parse_window({"utilization": 0})["utilization"] == 0.0