{"_id":"@agentopssec/agent-cost-lens","name":"@agentopssec/agent-cost-lens","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@agentopssec/agent-cost-lens","version":"1.0.0","description":"Local cost analytics for AI agent workflows.","type":"module","homepage":"https://AgentOpsSec.com/projects/agent-cost-lens","repository":{"type":"git","url":"git+https://github.com/AgentOpsSec/agent-cost-lens.git"},"bugs":{"url":"https://github.com/AgentOpsSec/agent-cost-lens/issues"},"bin":{"agent-cost":"bin/agent-cost.js"},"scripts":{"test":"node --test","check":"node --check bin/agent-cost.js && node --test"},"keywords":["agent","cost","tokens","analytics","cli"],"license":"MIT","engines":{"node":">=20"},"publishConfig":{"access":"public"},"author":{"name":"Aunt Gladys Nephew","url":"https://auntgladysnephew.com"},"gitHead":"7af4d1fb33d6d7ec2e2093dc17decca82894ee3c","_id":"@agentopssec/agent-cost-lens@1.0.0","_nodeVersion":"25.6.1","_npmVersion":"11.9.0","dist":{"integrity":"sha512-5vMxaEI7YDy5Bz/76/emRrRiZK1sNlXW6xqC99put5DsFTmQeDa2+WBDsu2i/yYnQSuPB++6GCRDcW8D415oow==","shasum":"07610cfa9132b0f10eaeaca106c8504352a15c51","tarball":"https://registry.npmjs.org/@agentopssec/agent-cost-lens/-/agent-cost-lens-1.0.0.tgz","fileCount":13,"unpackedSize":45740,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIB6xOXgISg31lYHw+TBJs2fM88qBXBYJLwTzY3zoIkVWAiEAzs87Pnd+rOBNAw81gsENRt/1rA2WJvGi/Lhcnr4gyho="}]},"_npmUser":{"name":"agentopssec","email":"agentopssecurity@gmail.com"},"directories":{},"maintainers":[{"name":"agentopssec","email":"agentopssecurity@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent-cost-lens_1.0.0_1777236609664_0.8656802575752833"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-26T20:50:09.590Z","1.0.0":"2026-04-26T20:50:09.797Z","modified":"2026-04-26T20:50:09.993Z"},"maintainers":[{"name":"agentopssec","email":"agentopssecurity@gmail.com"}],"description":"Local cost analytics for AI agent workflows.","homepage":"https://AgentOpsSec.com/projects/agent-cost-lens","keywords":["agent","cost","tokens","analytics","cli"],"repository":{"type":"git","url":"git+https://github.com/AgentOpsSec/agent-cost-lens.git"},"author":{"name":"Aunt Gladys Nephew","url":"https://auntgladysnephew.com"},"bugs":{"url":"https://github.com/AgentOpsSec/agent-cost-lens/issues"},"license":"MIT","readme":"# Agent Cost Lens\n\n**Know what every AI agent run actually costs.**\n\nAgent Cost Lens tracks token usage, model usage, retries, latency, and estimated\ncost across AI agents, CLI coding tools, API providers, and MCP-powered\nworkflows.\n\nThink of it as:\n\n```txt\nCost analytics for AI agent workflows\n```\n\n## Why This Exists\n\nAI coding costs are often spread across multiple tools, providers, repositories,\nmodels, retries, and failed runs. Developers and teams need visibility before\nusage becomes hard to explain.\n\nAgent Cost Lens answers questions like:\n\n- How much did agent runs cost today?\n- Which repo is the most expensive?\n- Which model or provider is driving spend?\n- How much cost came from retries?\n- Which runs failed after spending tokens?\n- Are prompts or tool loops causing waste?\n- Which tasks should use a cheaper model?\n- How should cost be exported for reporting?\n\nAgent Cost Lens turns scattered agent usage into local cost reports.\n\n## Install\n\n```bash\nnpm install -g @agentopssec/agent-cost-lens\n```\n\nOr run it without installing:\n\n```bash\nnpx -y @agentopssec/agent-cost-lens today\n```\n\n## Update\n\n```bash\nagent-cost update          # check the registry, prompt before installing\nagent-cost update --yes    # update without prompting\n```\n\n## Primary Workflow\n\nAgent Cost Lens starts with local summaries:\n\n```bash\nagent-cost today\n```\n\nThe workflow should do three things well:\n\n1. Collect cost and usage data from local agent runs.\n2. Summarize spend by repo, model, provider, and time period.\n3. Identify expensive runs and retry waste.\n\n## CLI\n\n```bash\nagent-cost day\nagent-cost today\nagent-cost week\nagent-cost month\nagent-cost by-model\nagent-cost by-provider\nagent-cost by-repo\nagent-cost expensive-runs\nagent-cost export --csv\nagent-cost budget set 50\nagent-cost budget check --period month --ci\nagent-cost pricing init\nagent-cost explain run_001\nagent-cost record --runId run_001 --inputTokens 1000 --outputTokens 500\nagent-cost run -- codex \"fix tests\"\neval \"$(agent-cost init-shell)\"\nagent-cost update [--yes]\n```\n\n## Using Existing Repos\n\nAgent Cost Lens is local-first and repo-scoped. Run it from the repository you\nwant to measure:\n\n```bash\ncd ~/code/my-app\nagent-cost month\n```\n\nThat command reads local data from:\n\n```txt\n.agent-cost/records.jsonl\n.agent-flight/runs/*.json\n```\n\nIf those files do not exist yet, the report will be empty. Agent Cost Lens\ncannot infer historical API spend from a git repo by itself; it needs either\nrecorded agent runs or manually added cost records.\n\nThere are three normal ways to populate data. Agent Flight Recorder is optional,\nnot required.\n\nWrap an agent command directly with Agent Cost Lens:\n\n```bash\ncd ~/code/my-app\nagent-cost run --provider openai --model gpt-5.2 --inputTokens 18400 --outputTokens 2400 -- codex \"fix the failing tests\"\nagent-cost month\n```\n\nInstall shell shims so normal CLI commands are recorded:\n\n```bash\neval \"$(agent-cost init-shell)\"\ncodex \"fix the failing tests\"\nclaude \"review this repo\"\ngemini \"write unit tests\"\nopencode \"fix the failing tests\"\nagent-cost month\n```\n\nAdd the `eval` line to your shell profile if you want this behavior in every\nterminal session.\n\nRecord new work through Agent Flight Recorder:\n\n```bash\ncd ~/code/my-app\nagent-flight run -- codex \"fix the failing tests\"\nagent-cost month\n```\n\nAdd a known cost record manually:\n\n```bash\ncd ~/code/my-app\nagent-cost record --runId run_001 --agent codex --repo my-app --provider openai --model gpt-5.2 --inputTokens 18400 --outputTokens 2400\nagent-cost month\n```\n\nYou can also point at a repo without changing directories:\n\n```bash\nagent-cost month --cwd ~/code/my-app\nagent-cost by-repo --cwd ~/code/my-app\n```\n\nFor existing repos, the first run will usually show zero until you begin\nrecording new agent sessions or add known usage as records.\n\nAgent Cost Lens is standalone. It does not require Agent Flight Recorder. In the\nfull AgentOpsSec stack, it can also import local Agent Flight Recorder and Agent\nSandbox run files as optional sources:\n\n```txt\n.agent-flight/runs/*.json\n.agent-sandbox/runs/*.json\n```\n\n## What Agent Cost Lens Tracks\n\nAgent Cost Lens records and summarizes:\n\n- Cost per run\n- Cost per repo\n- Cost per pull request\n- Cost per model\n- Cost per provider\n- Cost per developer when available\n- Input tokens\n- Output tokens\n- Cache tokens\n- Retry count\n- Failed run cost\n- Latency\n- Tool-call overhead\n- Expensive prompts\n- Budget thresholds\n\n## Example Summary\n\n```txt\nAgent Cost Lens Today by github.com/AgentOpsSec\n\nToday:\n- Total cost: $18.42\n- Most expensive repo: dashboard-app\n- Most expensive model: Claude Sonnet\n- Highest waste: 34% retries\n- Most expensive run: $2.14\n- Recommended optimization: use a cheaper model for test generation\n```\n\n## Cost Record Shape\n\n```json\n{\n  \"tool\": {\n    \"name\": \"Agent Cost Lens\",\n    \"by\": \"github.com/AgentOpsSec\",\n    \"repository\": \"github.com/AgentOpsSec/agent-cost-lens\"\n  },\n  \"runId\": \"run_001\",\n  \"agent\": \"codex\",\n  \"repo\": \"dashboard-app\",\n  \"provider\": \"openai\",\n  \"model\": \"gpt-5.2\",\n  \"inputTokens\": 18400,\n  \"outputTokens\": 2400,\n  \"cacheTokens\": 0,\n  \"toolCallCount\": 12,\n  \"latencyMs\": 252000,\n  \"retryCount\": 2,\n  \"estimatedCost\": 0.42,\n  \"timestamp\": \"2026-04-25T10:04:12Z\",\n  \"taskLabel\": \"fix failing tests\"\n}\n```\n\n## Reports and Exports\n\nAgent Cost Lens is designed to support:\n\n- Daily summaries\n- Weekly summaries\n- Monthly summaries\n- Provider reports\n- Model reports\n- Repo reports\n- Expensive run detection\n- Budget thresholds\n- CSV export\n- JSON export\n\n## Budgets and Pricing\n\n```bash\nagent-cost pricing init\nagent-cost budget set 50\nagent-cost budget check --period month --ci\n```\n\n`pricing init` writes `.agent-cost/pricing.json` so teams can tune local\nprovider/model prices. `budget check` owns the CI decision for cost budgets and\nexits nonzero with `--ci` when spend exceeds the configured budget.\n\n## Design Principles\n\n- Local-first\n- Open-source\n- No telemetry by default\n- Transparent pricing config\n- Useful estimates when exact usage is missing\n- Clear budget reporting\n- Exportable data\n- Integration-friendly run records\n\n## Initial Release Scope\n\nThe initial release includes local cost tracking, pricing configuration,\nsummaries by time period and dimension, expensive run detection, budgets, and\nexports.\n\n### 1.0: Local Cost Records\n\n- Store local run cost records\n- Import usage from recorded agent runs where available\n- Estimate cost when exact usage is missing\n- Track provider, model, repo, and timestamp\n- Support a local provider pricing config\n- Explain how a cost estimate was calculated\n\n### 1.0: Summaries and Budgets\n\n- Show today's total cost\n- Show weekly and monthly summaries\n- Break down cost by model\n- Break down cost by provider\n- Break down cost by repo\n- Set and read budget thresholds\n- Highlight failed run cost\n\n### 1.0: Waste Detection and Export\n\n- Detect expensive runs\n- Track retry waste\n- Identify token spikes\n- Show high-latency runs\n- Export reports as CSV\n- Export reports as JSON\n- Link costs back to run IDs for inspection\n\n\n## Output\n\nReports use plain-language status words rather than raw exit codes:\n\n- `ok` — the step ran successfully (green).\n- `failed (exit N)` — the step exited non-zero (red); the original code is preserved.\n- `skipped (reason)` — the step was not applicable (dim).\n\nSeverity colors follow the AgentOpsSec palette (safe = green, warning = amber, risk = red). The palette honors `NO_COLOR` and `FORCE_COLOR`, and JSON / CSV output stays plain.\n\n\n- Repo: https://github.com/AgentOpsSec/agent-cost-lens\n- npm: https://www.npmjs.com/package/@agentopssec/agent-cost-lens\n- AgentOpsSec stack: https://github.com/AgentOpsSec/stack\n- Website: https://AgentOpsSec.com\n\n## Author\n\nCreated and developed by **Aunt Gladys Nephew**.\n\n- Website: https://auntgladysnephew.com\n- GitHub: https://github.com/auntgladysnephew\n- X: https://x.com/AGNonX\n","readmeFilename":"README.md","_rev":"1-a1bf935da3bf80354e6e1bcaa85fa11d"}