vectiscode 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vectiscode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# vectiscode
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Find out why your Claude Code and Codex limits drain, and what to change.
+
+```sh
+npx vectiscode
+```
+
+vectiscode reads the session logs that Claude Code and Codex already keep on your computer and tells you where your usage went:
+
+- **Long chats.** How much ran with more than 150k tokens of context, which chats grew biggest, and how often they were compacted. Every step in a chat re-reads the whole chat, so late steps cost far more than early ones.
+- **Always-on context.** How big a new chat is before you type anything, what that setup is made of (tool definitions, system prompt, skills list, CLAUDE.md), and which tools were sent with every request but never called.
+- **Cache after breaks.** What it cost to come back to a big chat after its cache expired.
+- **Helpers and subagents.** How much went to each helper type and to workflows.
+- **Codex limits.** Your latest 5-hour and weekly readings, and how much of a weekly limit each chat used, taken from the real percentages Codex logs after every turn.
+
+Each finding comes with a fix.
+
+Nothing leaves your computer. There is no account, no telemetry and no network call, and the logs are only read, never changed.
+
+## Options
+
+| Option | |
+|---|---|
+| `--days <n>` | look at the last n days (default 30) |
+| `--since <date>` | look at everything since a date, like `2026-10-01` |
+| `--json` | print the full report as JSON |
+| `--claude-dir <dir>` | Claude Code folder (default `$CLAUDE_CONFIG_DIR` or `~/.claude`) |
+| `--codex-dir <dir>` | Codex folder (default `$CODEX_HOME` or `~/.codex`) |
+
+## How the numbers work
+
+- **Claude Code** logs the tokens of every request. vectiscode weighs them with API list prices and calls the result *units* (API-equivalent dollars). When Claude Code's own cost records are in the logs, the prices are checked against them, so the units stay right when prices change. Plans are not billed this way; units are a common scale for comparing requests, chats and habits.
+- **Codex** logs how much of your 5-hour and weekly limits you have used after every turn. vectiscode credits each turn with the change, so its Codex numbers are real percentages, not estimates. If you switch between ChatGPT accounts, each account's window is counted separately.
+- **Setup sizes** are estimated from the characters in the logs, so they are approximate.
+
+## Requirements
+
+Node 22 or newer. Built and tested on Windows; Claude Code and Codex write the same logs on macOS and Linux.
+
+## Status
+
+Early. If a number looks wrong for your logs, please open an issue.
+
+## License
+
+MIT

package/dist/checks.js

@@ -0,0 +1,301 @@
+import { limitDeltas, openWindows } from "./codex.js";
+import { costParts, readPrice } from "./prices.js";
+const WEEK = 10_080;
+const LONG = 150_000;
+const VERY_LONG = 300_000;
+export function analyze(claude, codex, since, now = Date.now()) {
+    const report = { since, findings: [] };
+    const weekly = codex ? turnPoints(codex.limits, since) : new Map();
+    if (claude?.requests.length) {
+        const reqs = claude.requests;
+        const total = sum(reqs, (r) => r.cost) || 1;
+        const parts = reqs.map(costParts);
+        report.claude = {
+            units: total,
+            requests: reqs.length,
+            chats: new Set(reqs.filter((r) => r.agent === "main").map((r) => r.session)).size,
+            split: {
+                read: sum(parts, (p) => p.read) / total,
+                write: sum(parts, (p) => p.write) / total,
+                output: sum(parts, (p) => p.output) / total,
+                input: sum(parts, (p) => p.input) / total,
+            },
+            agents: shares(reqs, (r) => r.agent, total),
+            projects: shares(reqs, (r) => r.project, total).slice(0, 4),
+        };
+    }
+    if (codex?.requests.length) {
+        const latest = new Map();
+        for (const s of codex.limits)
+            latest.set(`${s.limit}:${s.windowMinutes}`, s);
+        const bySession = new Map();
+        for (const r of codex.requests)
+            bySession.set(r.session, (bySession.get(r.session) ?? 0) + (weekly.get(r.id) ?? 0));
+        report.codex = {
+            turns: codex.requests.length,
+            chats: codex.sessions.size,
+            openWeekly: openWindows(codex.limits, WEEK, now),
+            limits: [...latest.values()].map((s) => ({
+                limit: s.limit,
+                windowMinutes: s.windowMinutes,
+                used: s.resetsAt <= now ? 0 : s.used,
+                resetsAt: s.resetsAt,
+                plan: s.plan,
+            })),
+            topChats: [...bySession]
+                .filter(([, points]) => points > 0)
+                .map(([id, points]) => ({ project: codex.sessions.get(id)?.project ?? "unknown", start: codex.sessions.get(id)?.start ?? 0, points }))
+                .sort((a, b) => b.points - a.points)
+                .slice(0, 3),
+        };
+    }
+    const checks = [longChats(claude, codex, weekly), alwaysOn(claude, codex), cacheBreaks(claude), helpers(claude)];
+    const order = ["high", "medium", "low", "ok"];
+    report.findings = checks
+        .filter((f) => f !== null)
+        .sort((a, b) => order.indexOf(a.level) - order.indexOf(b.level) || b.share - a.share);
+    return report;
+}
+function longChats(claude, codex, weekly) {
+    const facts = [];
+    let share = 0;
+    const claudeTotal = sum(claude?.requests ?? [], (r) => r.cost);
+    if (claude && claudeTotal > 0) {
+        const main = claude.requests.filter((r) => r.agent === "main");
+        const over = sum(main.filter((r) => r.context > LONG), (r) => r.cost) / claudeTotal;
+        const overVery = sum(main.filter((r) => r.context > VERY_LONG), (r) => r.cost) / claudeTotal;
+        const beyond = sum(main, (r) => Math.max(0, r.context - LONG) * readPrice(r.model));
+        share = over;
+        facts.push(`${pct(over)} of your Claude usage ran in chats past ${k(LONG)} tokens of context, ${pct(overVery)} past ${k(VERY_LONG)}.`);
+        facts.push(`Re-reading the part beyond ${k(LONG)} alone cost ${units(beyond)} units, ${pct(beyond / claudeTotal)} of everything.`);
+        const chats = chatStats(main, claude.sessions);
+        const veryLong = chats.filter((c) => c.peak > VERY_LONG);
+        if (veryLong.length) {
+            const compactions = sum(veryLong, (c) => c.compactions);
+            facts.push(`${veryLong.length} ${plural(veryLong.length, "chat")} grew past ${k(VERY_LONG)}${compactions ? ` and ${plural(compactions, "was", "were")} compacted ${compactions} ${plural(compactions, "time")}` : ""}.`);
+        }
+        for (const c of chats.slice(0, 3)) {
+            facts.push(`  ${c.project}, ${day(c.start)}: ${units(c.cost)} units, peaked at ${k(c.peak)}${c.compactions ? `, ${c.compactions} ${plural(c.compactions, "compaction")}` : ""}.`);
+        }
+    }
+    if (codex?.requests.length) {
+        const points = sum(codex.requests, (r) => weekly.get(r.id) ?? 0);
+        if (points > 0) {
+            const over = sum(codex.requests.filter((r) => r.context > LONG), (r) => weekly.get(r.id) ?? 0) / points;
+            share = Math.max(share, over);
+            facts.push(`Codex: ${pct(over)} of the weekly limit you used went to turns past ${k(LONG)} tokens of context.`);
+        }
+        else {
+            const input = sum(codex.requests, (r) => r.context) || 1;
+            const over = sum(codex.requests.filter((r) => r.context > LONG), (r) => r.context) / input;
+            share = Math.max(share, over);
+            facts.push(`Codex: ${pct(over)} of the tokens you sent were in turns past ${k(LONG)} tokens of context.`);
+        }
+    }
+    if (!facts.length)
+        return null;
+    const level = grade(share, 0.5, 0.25, 0.1);
+    return {
+        id: "long-chats",
+        level,
+        title: level === "ok" ? "Chat length" : `Long chats: ${pct(share)} of your usage ran past ${k(LONG)} tokens of context`,
+        share,
+        facts,
+        fix: "Every step in a chat re-reads the whole chat, so late steps cost several times what early ones do. Start a fresh chat from a short handoff note once a chat passes about 150k, instead of letting it grow and compact.",
+    };
+}
+function alwaysOn(claude, codex) {
+    const facts = [];
+    let share = 0;
+    const claudeTotal = sum(claude?.requests ?? [], (r) => r.cost);
+    if (claude && claudeTotal > 0) {
+        const firsts = firstContexts(claude.requests.filter((r) => r.agent === "main"));
+        if (firsts.size) {
+            const floor = sum(claude.requests.filter((r) => r.agent === "main" && firsts.has(r.session)), (r) => Math.min(r.context, firsts.get(r.session)) * readPrice(r.model));
+            share = floor / claudeTotal;
+            facts.push(`A new Claude Code chat starts at about ${k(median([...firsts.values()]))} tokens (median of ${firsts.size} ${plural(firsts.size, "chat")}), and most of that goes out again with every request.`);
+            facts.push(`Re-sending it cost ${units(floor)} units, ${pct(share)} of your Claude usage.`);
+        }
+        // The logs give characters, not tokens, for each part, so these are estimates; the rest is what isn't itemized.
+        const logged = [...claude.sessions.values()].filter((s) => s.setup?.has("tools") && firsts.has(s.id)).sort((a, b) => b.end - a.end);
+        const latest = logged[0];
+        if (latest) {
+            const first = firsts.get(latest.id);
+            const parts = new Map();
+            for (const [part, chars] of latest.setup) {
+                const name = SETUP_PARTS[part] ?? "other";
+                parts.set(name, (parts.get(name) ?? 0) + chars / (part === "tools" ? JSON_CHARS : TEXT_CHARS));
+            }
+            const rest = first - sum([...parts.values()], (t) => t);
+            if (rest > 0)
+                parts.set("not itemized", rest);
+            const top = [...parts].filter(([, tokens]) => tokens >= 500).sort((a, b) => b[1] - a[1]);
+            facts.push(`Where it comes from in your latest chat (${k(first)}): ${top.map(([name, tokens]) => `${name} ${k(tokens)}`).join(", ")}.`);
+            const withTools = [...claude.sessions.values()].filter((s) => s.tools);
+            const unused = unusedTools(withTools, 1 / JSON_CHARS);
+            if (unused.length) {
+                const list = unused.slice(0, 5).map((t) => `${t.name} (${k(t.tokens)})`).join(", ");
+                facts.push(`Never called in the ${withTools.length} ${plural(withTools.length, "chat")} that logged their tools: ${list}${unused.length > 5 ? ` and ${unused.length - 5} more` : ""}, about ${k(sum(unused, (t) => t.tokens))} per request.`);
+            }
+        }
+    }
+    if (codex?.requests.length) {
+        const firsts = firstContexts(codex.requests);
+        if (firsts.size)
+            facts.push(`A new Codex chat starts at about ${k(median([...firsts.values()]))} tokens.`);
+    }
+    if (!facts.length)
+        return null;
+    const level = grade(share, 0.2, 0.1, 0.03);
+    return {
+        id: "always-on",
+        level,
+        title: level === "ok" ? "Always-on context" : `Always-on context: ${pct(share)} of your Claude usage is re-sending the same setup`,
+        share,
+        facts,
+        fix: "The system prompt, every tool definition, MCP servers, skills and CLAUDE.md files go out with every single request. Turn off MCP servers and plugins a project doesn't use, deny unused built-in tools with permissions.deny in settings.json, and keep instruction files short.",
+    };
+}
+function cacheBreaks(claude) {
+    const total = sum(claude?.requests ?? [], (r) => r.cost);
+    if (!claude || total <= 0)
+        return null;
+    const cold = [];
+    const last = new Map();
+    for (const r of claude.requests) {
+        const prev = last.get(r.thread);
+        last.set(r.thread, r);
+        if (!prev)
+            continue;
+        const ttl = r.cacheWrite1h > 0 ? 3_600_000 : 300_000;
+        const written = r.cacheWrite5m + r.cacheWrite1h;
+        const gap = r.time - prev.time;
+        if (gap > ttl && written > 20_000)
+            cold.push({ r, gap, written, cost: costParts(r).write });
+    }
+    const spent = sum(cold, (c) => c.cost);
+    const share = spent / total;
+    const level = grade(share, 0.1, 0.04, 0.01);
+    const facts = [
+        `${cold.length} ${plural(cold.length, "time")} a chat was picked up after its cache had expired, so the whole chat was written to the cache again.`,
+        `That cost ${units(spent)} units, ${pct(share)} of your Claude usage.`,
+    ];
+    const big = cold.sort((a, b) => b.written - a.written)[0];
+    if (big)
+        facts.push(`Biggest: ${big.r.project} on ${day(big.r.time)}, ${k(big.written)} tokens rewritten after a ${duration(big.gap)} break.`);
+    return {
+        id: "cache-breaks",
+        level,
+        title: level === "ok" ? "Cache after breaks" : `Coming back to big chats after a break cost ${pct(share)} of your Claude usage`,
+        share,
+        facts,
+        fix: "The cache keeps a chat for about an hour (5 minutes for some requests). After that, the next step pays to write the whole chat again. Before a long break, finish the step and continue in a fresh chat afterwards, or run /compact first so the rewrite is small.",
+    };
+}
+function helpers(claude) {
+    const total = sum(claude?.requests ?? [], (r) => r.cost);
+    if (!claude || total <= 0)
+        return null;
+    const types = shares(claude.requests.filter((r) => r.agent !== "main"), (r) => r.agent, total);
+    const share = sum(types, (t) => t.share);
+    if (!types.length)
+        return null;
+    const level = grade(share, 0.4, 0.25, 0.15);
+    return {
+        id: "helpers",
+        level,
+        title: level === "ok" ? "Helpers and subagents" : `Helpers and subagents: ${pct(share)} of your Claude usage`,
+        share,
+        facts: [`By type: ${types.slice(0, 5).map((t) => `${t.name} ${pct(t.share)}`).join(", ")}.`],
+        fix: "Each helper starts its own context with its own tools and instructions. Keep the types that save main-chat work, give them a cheaper model where the result holds up, and cap how many a single workflow can start.",
+    };
+}
+/** Points of the weekly Codex limit each turn used. */
+function turnPoints(limits, since) {
+    const out = new Map();
+    for (const [s, d] of limitDeltas(limits, WEEK, since))
+        if (s.turn && s.limit === "codex")
+            out.set(s.turn, (out.get(s.turn) ?? 0) + d);
+    return out;
+}
+function chatStats(main, sessions) {
+    const chats = new Map();
+    for (const r of main) {
+        const c = chats.get(r.session) ?? { project: r.project, start: r.time, cost: 0, peak: 0, compactions: sessions.get(r.session)?.compactions.length ?? 0 };
+        c.cost += r.cost;
+        c.peak = Math.max(c.peak, r.context);
+        chats.set(r.session, c);
+    }
+    return [...chats.values()].sort((a, b) => b.cost - a.cost);
+}
+/** Context of the first request of each chat with at least three requests. */
+function firstContexts(reqs) {
+    const count = new Map();
+    const first = new Map();
+    for (const r of reqs) {
+        count.set(r.session, (count.get(r.session) ?? 0) + 1);
+        if (!first.has(r.session))
+            first.set(r.session, r.context);
+    }
+    for (const [id, n] of count)
+        if (n < 3)
+            first.delete(id);
+    return first;
+}
+function unusedTools(sessions, perChar) {
+    const called = new Set(sessions.flatMap((s) => [...s.toolsCalled]));
+    const tools = new Map();
+    for (const s of sessions)
+        for (const t of s.tools)
+            if (!called.has(t.name))
+                tools.set(t.name, Math.max(tools.get(t.name) ?? 0, t.chars * perChar));
+    return [...tools].map(([name, tokens]) => ({ name, tokens })).sort((a, b) => b.tokens - a.tokens);
+}
+// Rough characters per token: prose, and JSON tool schemas.
+const TEXT_CHARS = 3.5;
+const JSON_CHARS = 3;
+const SETUP_PARTS = {
+    tools: "tool definitions",
+    system: "system prompt",
+    instructions: "CLAUDE.md and rules",
+    skill_listing: "skills list",
+    invoked_skills: "skills in use",
+    deferred_tools_delta: "deferred tool list",
+    deferred_tools_record: "deferred tool list",
+    agent_listing_delta: "subagent list",
+    mcp_instructions_delta: "MCP instructions",
+    file: "attached files",
+    "first-message": "your first message",
+};
+function shares(reqs, key, total) {
+    const m = new Map();
+    for (const r of reqs)
+        m.set(key(r), (m.get(key(r)) ?? 0) + r.cost);
+    return [...m].map(([name, c]) => ({ name, share: c / total })).sort((a, b) => b.share - a.share);
+}
+function grade(share, high, medium, low) {
+    return share >= high ? "high" : share >= medium ? "medium" : share >= low ? "low" : "ok";
+}
+export function sum(xs, f) {
+    let s = 0;
+    for (const x of xs)
+        s += f(x);
+    return s;
+}
+function median(xs) {
+    const s = [...xs].sort((a, b) => a - b);
+    return s[Math.floor(s.length / 2)] ?? 0;
+}
+const plural = (n, one, many = `${one}s`) => (n === 1 ? one : many);
+export const pct = (x) => (x > 0 && x < 0.005 ? "<1%" : `${Math.round(x * 100)}%`);
+export const k = (n) => (n < 1000 ? String(Math.round(n)) : `${Math.round(n / 1000)}k`);
+export const units = (x) => (x >= 100 ? x.toFixed(0) : x.toFixed(1));
+export const day = (t) => new Date(t).toLocaleDateString("en-US", { month: "short", day: "numeric" });
+function duration(ms) {
+    const h = Math.floor(ms / 3_600_000);
+    if (h >= 48)
+        return `${Math.round(h / 24)}-day`;
+    if (h >= 1)
+        return `${h}-hour`;
+    return `${Math.round(ms / 60_000)}-minute`;
+}

package/dist/claude.js

@@ -0,0 +1,142 @@
+import { readFileSync } from "node:fs";
+import { basename, join, sep } from "node:path";
+import { jsonlFiles, readLines } from "./files.js";
+import { projectName, sessionFor } from "./model.js";
+import { calibrate, cost } from "./prices.js";
+const NEEDLES = ['"type":"assistant"', '"compact_boundary"', '"api-request-shape"', '"type":"cost-state"'];
+// Until a chat's first request, also read what Claude Code put into it.
+const SETUP_NEEDLES = ['"type":"attachment"', '"type":"user"'];
+/** Reads Claude Code's logs: <root>/projects/<folder>/<session>.jsonl plus <session>/subagents/**.jsonl for helpers. */
+export async function readClaude(root, since) {
+    const projects = join(root, "projects");
+    const requests = new Map();
+    const sessions = new Map();
+    const costs = [];
+    for (const file of jsonlFiles(projects, since)) {
+        const parts = file.slice(projects.length + 1).split(sep);
+        const folder = parts[0] ?? "";
+        const isHelperFile = parts.length > 2;
+        const sessionId = isHelperFile ? parts[1] : basename(file, ".jsonl");
+        const helper = isHelperFile ? helperType(file, parts) : null;
+        let started = false;
+        let costState = null;
+        const keep = (line) => NEEDLES.some((n) => line.includes(n)) || (!started && !helper && SETUP_NEEDLES.some((n) => line.includes(n)));
+        for await (const r of readLines(file, keep)) {
+            if (r.type === "cost-state") {
+                costState = r;
+                continue;
+            }
+            const usage = r.type === "assistant" ? r.message?.usage : undefined;
+            const wasStarted = started;
+            if (usage)
+                started = true;
+            const time = Date.parse(r.timestamp);
+            if (!(time >= since))
+                continue;
+            const session = sessionFor(sessions, "claude", sessionId, projectName(r.cwd, folder), time);
+            if (r.cwd)
+                session.project = projectName(r.cwd, folder);
+            if (r.type === "assistant") {
+                const m = r.message ?? {};
+                for (const block of Array.isArray(m.content) ? m.content : []) {
+                    if (block?.type === "tool_use" && block.name)
+                        session.toolsCalled.add(block.name);
+                }
+                if (!usage || m.model === "<synthetic>")
+                    continue;
+                const id = r.requestId ?? m.id;
+                const known = requests.get(id);
+                if (known) {
+                    // Claude Code writes one record per content block, all carrying the same usage.
+                    known.output = Math.max(known.output, usage.output_tokens ?? 0);
+                    continue;
+                }
+                const write = usage.cache_creation_input_tokens ?? 0;
+                const write1h = Math.min(write, usage.cache_creation?.ephemeral_1h_input_tokens ?? 0);
+                const req = {
+                    source: "claude",
+                    id,
+                    session: sessionId,
+                    thread: helper ? file : r.isSidechain ? `${sessionId}:side` : sessionId,
+                    project: session.project,
+                    time,
+                    model: m.model ?? "unknown",
+                    agent: helper ?? (r.isSidechain ? "helper" : "main"),
+                    input: usage.input_tokens ?? 0,
+                    cacheRead: usage.cache_read_input_tokens ?? 0,
+                    cacheWrite5m: write - write1h,
+                    cacheWrite1h: write1h,
+                    output: usage.output_tokens ?? 0,
+                    context: 0,
+                    cost: 0,
+                };
+                req.context = req.input + req.cacheRead + write;
+                requests.set(id, req);
+            }
+            else if (r.type === "system" && r.subtype === "compact_boundary" && !helper) {
+                if (!session.compactions.some((c) => c.time === time))
+                    session.compactions.push({ time, tokens: r.compactMetadata?.preTokens ?? 0 });
+            }
+            else if (r.type === "api-request-shape" && !helper && r.shape && !session.tools) {
+                session.tools = (r.shape.tools ?? []).map((t) => ({ name: String(t.name), chars: JSON.stringify(t).length }));
+                if (!wasStarted) {
+                    addSetup(session, "system", JSON.stringify(r.shape.system ?? []).length);
+                    addSetup(session, "tools", JSON.stringify(r.shape.tools ?? []).length);
+                }
+            }
+            else if (r.type === "attachment" && !wasStarted) {
+                addSetup(session, r.attachment?.type ?? "other", textLength(r.rendered));
+            }
+            else if (r.type === "user" && !wasStarted) {
+                addSetup(session, "first-message", textLength(r.message?.content));
+            }
+        }
+        for (const [model, u] of Object.entries(costState?.modelUsage ?? {})) {
+            costs.push({
+                model,
+                input: u.inputTokens ?? 0,
+                output: u.outputTokens ?? 0,
+                read: u.cacheReadInputTokens ?? 0,
+                write: u.cacheCreationInputTokens ?? 0,
+                searches: u.webSearchRequests ?? 0,
+                usd: u.costUSD ?? 0,
+            });
+        }
+    }
+    calibrate(costs);
+    const list = [...requests.values()].sort((a, b) => a.time - b.time);
+    for (const r of list)
+        r.cost = cost(r);
+    return { requests: list, sessions };
+}
+function addSetup(session, part, chars) {
+    session.setup ??= new Map();
+    session.setup.set(part, (session.setup.get(part) ?? 0) + chars);
+}
+/** Characters of text in a message or a rendered attachment: a string, or a list of text blocks. Images don't count. */
+function textLength(content) {
+    if (typeof content === "string")
+        return content.length;
+    if (!Array.isArray(content))
+        return 0;
+    let n = 0;
+    for (const b of content)
+        n += typeof b?.text === "string" ? b.text.length : typeof b?.content === "string" ? b.content.length : 0;
+    return n;
+}
+const metaCache = new Map();
+function helperType(file, parts) {
+    if (parts.includes("workflows"))
+        return "workflow";
+    let type = metaCache.get(file);
+    if (!type) {
+        try {
+            type = String(JSON.parse(readFileSync(file.replace(/\.jsonl$/, ".meta.json"), "utf8")).agentType || "helper");
+        }
+        catch {
+            type = "helper";
+        }
+        metaCache.set(file, type);
+    }
+    return type;
+}

package/dist/cli.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { parseArgs } from "node:util";
+import { analyze } from "./checks.js";
+import { readClaude } from "./claude.js";
+import { readCodex } from "./codex.js";
+import { render } from "./report.js";
+const HELP = `vectiscode: find out why your Claude Code and Codex limits drain, and what to change.
+
+Usage: npx vectiscode [options]
+
+  --days <n>          look at the last n days (default 30)
+  --since <date>      look at everything since a date, like 2026-10-01
+  --json              print the full report as JSON
+  --claude-dir <dir>  Claude Code folder (default $CLAUDE_CONFIG_DIR or ~/.claude)
+  --codex-dir <dir>   Codex folder (default $CODEX_HOME or ~/.codex)
+  -v, --version       print the version
+  -h, --help          print this help
+
+Everything runs on this computer. Your logs are read, never changed and never sent anywhere.`;
+const { values } = parseArgs({
+    options: {
+        days: { type: "string" },
+        since: { type: "string" },
+        json: { type: "boolean" },
+        "claude-dir": { type: "string" },
+        "codex-dir": { type: "string" },
+        version: { type: "boolean", short: "v" },
+        help: { type: "boolean", short: "h" },
+    },
+});
+if (values.help) {
+    console.log(HELP);
+}
+else if (values.version) {
+    console.log(JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version);
+}
+else {
+    const days = values.since ? null : Number(values.days ?? 30);
+    const since = values.since ? Date.parse(values.since) : Date.now() - days * 86_400_000;
+    if (!Number.isFinite(since)) {
+        console.error(`Could not read the date or number of days. Try --since 2026-10-01 or --days 7.`);
+        process.exit(1);
+    }
+    const claudeDir = values["claude-dir"] ?? process.env.CLAUDE_CONFIG_DIR ?? join(homedir(), ".claude");
+    const codexDir = values["codex-dir"] ?? process.env.CODEX_HOME ?? join(homedir(), ".codex");
+    if (process.stderr.isTTY && !values.json)
+        process.stderr.write("Reading your logs...\r");
+    const [claude, codex] = await Promise.all([readClaude(claudeDir, since), readCodex(codexDir, since)]);
+    if (process.stderr.isTTY && !values.json)
+        process.stderr.write("                   \r");
+    const report = analyze(claude, codex, since);
+    console.log(values.json ? JSON.stringify(report, null, 2) : render(report, days));
+}

package/dist/codex.js

@@ -0,0 +1,114 @@
+import { basename, join } from "node:path";
+import { jsonlFiles, readLines } from "./files.js";
+import { projectName, sessionFor } from "./model.js";
+const NEEDLES = ['"session_meta"', '"turn_context"', '"token_count"'];
+const keep = (line) => NEEDLES.some((n) => line.includes(n));
+const JITTER = 3 * 3_600_000;
+/** Reads Codex's logs: <root>/sessions/YYYY/MM/DD/rollout-*.jsonl. */
+export async function readCodex(root, since) {
+    const requests = [];
+    const sessions = new Map();
+    const limits = [];
+    const seen = new Set();
+    for (const file of jsonlFiles(join(root, "sessions"), since)) {
+        let id = basename(file, ".jsonl");
+        let project = "unknown";
+        let model = "unknown";
+        let lastTotal = -1;
+        for await (const r of readLines(file, keep)) {
+            const p = r.payload ?? {};
+            if (r.type === "session_meta") {
+                id = p.id ?? p.session_id ?? id;
+                project = projectName(p.cwd, project);
+                continue;
+            }
+            if (r.type === "turn_context") {
+                model = p.model ?? model;
+                continue;
+            }
+            const time = Date.parse(r.timestamp);
+            if (p.type !== "token_count" || !(time >= since))
+                continue;
+            const session = sessionFor(sessions, "codex", id, project, time);
+            let turn;
+            const total = p.info?.total_token_usage?.total_tokens;
+            const last = p.info?.last_token_usage;
+            // The running total repeats when nothing new was sent, and resumed chats copy earlier events.
+            if (last && total !== lastTotal && !seen.has(`${id}:${total}`)) {
+                seen.add(`${id}:${total}`);
+                turn = `${id}:${total}`;
+                const input = last.input_tokens ?? 0;
+                const cached = Math.min(input, last.cached_input_tokens ?? 0);
+                requests.push({
+                    source: "codex",
+                    id: turn,
+                    session: id,
+                    thread: id,
+                    project: session.project,
+                    time,
+                    model,
+                    agent: "main",
+                    input: input - cached,
+                    cacheRead: cached,
+                    cacheWrite5m: last.cache_write_input_tokens ?? 0,
+                    cacheWrite1h: 0,
+                    output: last.output_tokens ?? 0,
+                    context: input,
+                    cost: 0,
+                });
+            }
+            lastTotal = total ?? lastTotal;
+            const rl = p.rate_limits;
+            for (const w of [rl?.primary, rl?.secondary]) {
+                if (!w || typeof w.used_percent !== "number")
+                    continue;
+                limits.push({
+                    time,
+                    session: id,
+                    turn,
+                    limit: rl.limit_id ?? "codex",
+                    windowMinutes: w.window_minutes,
+                    used: w.used_percent,
+                    resetsAt: w.resets_at * 1000,
+                    plan: rl.plan_type ?? undefined,
+                });
+            }
+        }
+    }
+    requests.sort((a, b) => a.time - b.time);
+    limits.sort((a, b) => a.time - b.time);
+    return { requests, sessions, limits };
+}
+/**
+ * How many percentage points of a limit window each turn used. A window is known by its reset time: people who
+ * switch between ChatGPT accounts have several running at once, and parallel chats report the same window with
+ * reset times up to an hour apart, sometimes with an older, lower reading. So each window counts up from its peak.
+ */
+export function limitDeltas(limits, windowMinutes, since) {
+    const deltas = new Map();
+    const windows = new Map();
+    for (const s of limits) {
+        if (s.windowMinutes !== windowMinutes)
+            continue;
+        const list = windows.get(s.limit) ?? [];
+        windows.set(s.limit, list);
+        let w = list.find((x) => Math.abs(x.resetsAt - s.resetsAt) <= JITTER);
+        if (!w) {
+            // A window that started before the logs being read began already has usage nobody here can place.
+            w = { resetsAt: s.resetsAt, peak: s.resetsAt - windowMinutes * 60_000 < since ? s.used : 0 };
+            list.push(w);
+        }
+        deltas.set(s, Math.max(0, s.used - w.peak));
+        w.peak = Math.max(w.peak, s.used);
+    }
+    return deltas;
+}
+/** How many different windows of this length were still open at `now`. */
+export function openWindows(limits, windowMinutes, now) {
+    const open = [];
+    for (const s of limits) {
+        if (s.windowMinutes === windowMinutes && s.limit === "codex" && s.resetsAt > now && !open.some((r) => Math.abs(r - s.resetsAt) <= JITTER))
+            open.push(s.resetsAt);
+    }
+    return open.length;
+}

package/dist/files.js

@@ -0,0 +1,33 @@
+import { createReadStream, readdirSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import { createInterface } from "node:readline";
+/** Every .jsonl log under `dir` changed since `since`, oldest first, so forks lose to the chat they copied. */
+export function jsonlFiles(dir, since) {
+    let names;
+    try {
+        names = readdirSync(dir, { recursive: true, encoding: "utf8" });
+    }
+    catch {
+        return [];
+    }
+    return names
+        .filter((n) => n.endsWith(".jsonl") && basename(n) !== "journal.jsonl")
+        .map((n) => ({ path: join(dir, n), stat: statSync(join(dir, n)) }))
+        .filter((f) => f.stat.mtimeMs >= since)
+        .sort((a, b) => a.stat.birthtimeMs - b.stat.birthtimeMs)
+        .map((f) => f.path);
+}
+/** Parses only the lines `keep` accepts, which skips most of a multi-gigabyte log unparsed. */
+export async function* readLines(path, keep) {
+    const lines = createInterface({ input: createReadStream(path, { encoding: "utf8" }), crlfDelay: Infinity });
+    for await (const line of lines) {
+        if (!keep(line))
+            continue;
+        try {
+            yield JSON.parse(line);
+        }
+        catch {
+            // a line still being written
+        }
+    }
+}

package/dist/model.js

@@ -0,0 +1,18 @@
+export function projectName(cwd, fallback) {
+    if (!cwd)
+        return fallback;
+    // Split on both separators: logs written on Windows can be read anywhere.
+    return cwd.replace(/[\\/]\.claude[\\/]worktrees[\\/].*$/, "").split(/[\\/]/).filter(Boolean).pop() || fallback;
+}
+export function sessionFor(sessions, source, id, project, time) {
+    let s = sessions.get(id);
+    if (!s) {
+        s = { source, id, project, start: time, end: time, compactions: [], toolsCalled: new Set() };
+        sessions.set(id, s);
+    }
+    if (time < s.start)
+        s.start = time;
+    if (time > s.end)
+        s.end = time;
+    return s;
+}

package/dist/prices.js

@@ -0,0 +1,61 @@
+// API list prices, used to weigh tokens against each other. Subscriptions are not billed this way.
+// The 5.5 rates reconcile with the cost records Claude Code writes into its own logs.
+const CLAUDE = {
+    "opus-5-5": [4, 20, 0.2, 5, 8],
+    "sonnet-5-5": [2, 10, 0.2, 2.5, 4],
+    "haiku-5-5": [0.1, 0.5, 0.01, 0.125, 0.2],
+    "opus-4-6": [5, 25, 0.5, 6.25, 10],
+    "opus-4-5": [5, 25, 0.5, 6.25, 10],
+    "opus-4-1": [15, 75, 1.5, 18.75, 30],
+    "opus-4": [15, 75, 1.5, 18.75, 30],
+    "sonnet-4-5": [3, 15, 0.3, 3.75, 6],
+    "sonnet-4": [3, 15, 0.3, 3.75, 6],
+    "haiku-4-5": [1, 5, 0.1, 1.25, 2],
+    "3-7-sonnet": [3, 15, 0.3, 3.75, 6],
+    "3-5-sonnet": [3, 15, 0.3, 3.75, 6],
+    "3-5-haiku": [0.8, 4, 0.08, 1, 1.6],
+};
+// Unknown versions fall back to the newest price of their family.
+const FAMILY = { opus: CLAUDE["opus-5-5"], sonnet: CLAUDE["sonnet-5-5"], haiku: CLAUDE["haiku-5-5"] };
+export function priceOf(model) {
+    const id = model.replace(/^.*claude-/, "").replace(/\[.*\]$/, "").replace(/-\d{8}(-v\d+(:\d+)?)?$/, "");
+    return CLAUDE[id] ?? Object.entries(FAMILY).find(([family]) => id.includes(family))?.[1];
+}
+const scale = new Map();
+/** Scales each model's prices to match the costs Claude Code recorded, so the numbers keep up when prices change. */
+export function calibrate(records) {
+    const sums = new Map();
+    for (const c of records) {
+        const p = priceOf(c.model);
+        if (!p)
+            continue;
+        const s = sums.get(c.model) ?? { real: 0, table: 0 };
+        s.real += c.usd - c.searches * 0.01;
+        s.table += (c.input * p[0] + c.output * p[1] + c.read * p[2] + c.write * p[4]) / 1e6;
+        sums.set(c.model, s);
+    }
+    for (const [model, s] of sums)
+        if (s.table > 1)
+            scale.set(model, Math.min(5, Math.max(0.2, s.real / s.table)));
+}
+/** API-equivalent USD of each part of a request. */
+export function costParts(r) {
+    const p = priceOf(r.model);
+    if (!p || r.source !== "claude")
+        return { input: 0, output: 0, read: 0, write: 0 };
+    const f = (scale.get(r.model) ?? 1) / 1e6;
+    return {
+        input: r.input * p[0] * f,
+        output: r.output * p[1] * f,
+        read: r.cacheRead * p[2] * f,
+        write: (r.cacheWrite5m * p[3] + r.cacheWrite1h * p[4]) * f,
+    };
+}
+export function cost(r) {
+    const c = costParts(r);
+    return c.input + c.output + c.read + c.write;
+}
+/** USD per token of reading context from the cache. */
+export function readPrice(model) {
+    return ((priceOf(model)?.[2] ?? 0) * (scale.get(model) ?? 1)) / 1e6;
+}

package/dist/report.js

@@ -0,0 +1,82 @@
+import { day, pct, units } from "./checks.js";
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const paint = (code) => (s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : s);
+const bold = paint("1");
+const dim = paint("2");
+const LEVEL = { high: paint("31"), medium: paint("33"), low: paint("36"), ok: paint("32") };
+const WIDTH = Math.min(process.stdout.columns || 100, 100);
+const PAD = 13;
+export function render(report, days) {
+    const out = [];
+    const range = days ? `last ${days} ${days === 1 ? "day" : "days"}` : `since ${day(report.since)}`;
+    out.push("", `${bold("vectiscode")} ${dim(`usage doctor · ${range}`)}`, "");
+    const c = report.claude;
+    if (c) {
+        out.push(row("Claude Code", `${units(c.units)} units over ${c.requests.toLocaleString("en-US")} requests in ${c.chats} chats`));
+        out.push(row("", `re-reading the chat ${pct(c.split.read)} · writing to cache ${pct(c.split.write)} · output ${pct(c.split.output)} · new input ${pct(c.split.input)}`));
+        out.push(row("", `by project: ${c.projects.map((p) => `${p.name} ${pct(p.share)}`).join(", ")}`));
+    }
+    const x = report.codex;
+    if (x) {
+        const plan = x.limits.find((l) => l.plan)?.plan;
+        out.push(row("Codex", `${x.turns.toLocaleString("en-US")} turns in ${x.chats} chats${plan ? ` · ${plan} plan` : ""}`));
+        const limits = [...x.limits].sort((a, b) => b.windowMinutes - a.windowMinutes || a.limit.localeCompare(b.limit));
+        const text = limits.map((l) => `${l.limit === "codex" ? "" : `${l.limit} `}${windowName(l.windowMinutes)} ${l.used}%${l.used ? ` used, resets ${when(l.resetsAt)}` : ""}`);
+        if (text.length)
+            out.push(row("", `latest reading: ${text.join(" · ")}`));
+        if (x.openWeekly > 1)
+            out.push(row("", dim(`Readings came from ${x.openWeekly} different weekly windows, usually a sign of more than one ChatGPT account. The reading above is the latest one.`)));
+        if (x.topChats.length)
+            out.push(row("", `biggest chats: ${x.topChats.map((s) => `${s.project} (${day(s.start)}) ${Math.round(s.points)}%`).join(", ")} of a weekly limit`));
+    }
+    if (!c && !x)
+        return `${out.join("\n")}No Claude Code or Codex logs found in that time.\n`;
+    if (c)
+        out.push("", dim(wrap("Units are API-equivalent dollars, used to weigh tokens against each other. They are not your bill.", 0)));
+    const problems = report.findings.filter((f) => f.level !== "ok");
+    const fine = report.findings.filter((f) => f.level === "ok");
+    if (problems.length)
+        out.push("", bold("FINDINGS"));
+    for (const f of problems) {
+        out.push("", `${LEVEL[f.level](`● ${f.level.toUpperCase().padEnd(6)}`)} ${bold(f.title)}`);
+        for (const fact of f.facts)
+            out.push(wrap(fact, 9));
+        out.push(wrap(`${bold("Fix:")} ${f.fix}`, 9));
+    }
+    if (fine.length) {
+        out.push("", bold("LOOKS FINE"), "");
+        for (const f of fine)
+            out.push(`${LEVEL.ok("✓")} ${f.title} ${dim(`(${pct(f.share)})`)}`);
+    }
+    out.push("");
+    return out.join("\n");
+}
+function row(label, text) {
+    return wrap(text, PAD, label ? bold(label.padEnd(PAD)) : " ".repeat(PAD));
+}
+/** Word-wraps `text` to the terminal width with a hanging indent. */
+function wrap(text, indent, first = " ".repeat(indent)) {
+    const lines = [];
+    let line = "";
+    for (const word of text.split(" ")) {
+        if (line && visible(line).length + 1 + visible(word).length > WIDTH - indent) {
+            lines.push(line);
+            line = word;
+        }
+        else
+            line = line ? `${line} ${word}` : word;
+    }
+    lines.push(line);
+    return lines.map((l, i) => (i ? " ".repeat(indent) : first) + l).join("\n");
+}
+const visible = (s) => s.replace(/\x1b\[\d+m/g, "");
+function windowName(minutes) {
+    if (minutes === 10_080)
+        return "weekly limit";
+    if (minutes % 60 === 0)
+        return `${minutes / 60}-hour limit`;
+    return `${minutes}-minute limit`;
+}
+function when(t) {
+    return new Date(t).toLocaleString("en-US", { weekday: "short", month: "short", day: "numeric", hour: "2-digit", minute: "2-digit", hour12: false });
+}

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "vectiscode",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Find out why your Claude Code and Codex limits drain, and what to change. Runs locally on your own logs.",
+  "keywords": [
+    "claude-code",
+    "codex",
+    "usage",
+    "rate-limits",
+    "tokens",
+    "cli"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vectiscode/vectiscode-cli.git"
+  },
+  "homepage": "https://github.com/vectiscode/vectiscode-cli#readme",
+  "bugs": "https://github.com/vectiscode/vectiscode-cli/issues",
+  "type": "module",
+  "bin": {
+    "vectiscode": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.js"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "tsc && node --test \"dist/**/*.test.js\"",
+    "doctor": "tsc && node dist/cli.js",
+    "prepublishOnly": "npm test"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "^7.0.2"
+  }
+}