{"_id":"@adarshsingh05/agent-guard","_rev":"5-4e646a64b33c44850cd59a9a14bc4559","name":"@adarshsingh05/agent-guard","dist-tags":{"latest":"0.1.4"},"versions":{"0.1.0":{"name":"@adarshsingh05/agent-guard","version":"0.1.0","keywords":["llm","openai","anthropic","spend-cap","audit-log","agent","cost"],"author":{"name":"adarshsingh05"},"license":"MIT","_id":"@adarshsingh05/agent-guard@0.1.0","maintainers":[{"name":"adarshsingh05","email":"adarshashokbaghel@gmail.com"}],"bin":{"agent-guard":"bin/cli.js"},"dist":{"shasum":"22abf24c801fd9d4f6291bb3405da557d0a7f537","tarball":"https://registry.npmjs.org/@adarshsingh05/agent-guard/-/agent-guard-0.1.0.tgz","fileCount":12,"integrity":"sha512-kX0AjooFqNMVDsGgvPYuN/DvE4X4j7oo7OzdEh+jbGCFGPZbx3kJY6Bm03RjrclleJFK+EtBRf7eqZfcqNzjQQ==","signatures":[{"sig":"MEUCIFP1zmV4PMAew2rEzfNso5wk+BcNF/IqHsE2wh2bxfe7AiEAqcrMh8wswrLuVggDpbYc07cE+mJQd1YQJzYsnI7bTZc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":190730},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"gitHead":"c4dd14aa456f4e1ed9f7b9c0701b07b35e498a6e","scripts":{"test":"vitest run","build":"tsup","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"adarshsingh05","email":"adarshashokbaghel@gmail.com"},"_npmVersion":"11.6.2","description":"A drop-in spend cap and audit log for LLM API calls","directories":{},"_nodeVersion":"24.12.0","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.4.0","vitest":"^3.0.9","typescript":"^5.8.2","@types/node":"^22.13.10"},"_npmOperationalInternal":{"tmp":"tmp/agent-guard_0.1.0_1783774418706_0.2423482470695868","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@adarshsingh05/agent-guard","version":"0.1.1","keywords":["llm","openai","anthropic","spend-cap","audit-log","agent","cost"],"author":{"name":"adarshsingh05"},"license":"MIT","_id":"@adarshsingh05/agent-guard@0.1.1","maintainers":[{"name":"adarshsingh05","email":"adarshashokbaghel@gmail.com"}],"bin":{"agent-guard":"cli.js"},"dist":{"shasum":"bb066fa28292090e1ed7acf19c495376452d4d96","tarball":"https://registry.npmjs.org/@adarshsingh05/agent-guard/-/agent-guard-0.1.1.tgz","fileCount":15,"integrity":"sha512-baiZxBU69xEFJWYuBPg2f+Lnbe6jTTj4Ot5pjfjlplf2F9V59FCn/QgizuC+6eZOmpJONCDtAyvEmu9/YmYLYQ==","signatures":[{"sig":"MEYCIQD05i9kHkFwV8WHkH8eJkWbzVR+Y/n/yIYvM96iO6h+PAIhAOVmivGnnvM+gU0/qZoPAwlv4lH1wz7BVSitTKrKk03q","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1887275},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"gitHead":"c4dd14aa456f4e1ed9f7b9c0701b07b35e498a6e","scripts":{"test":"vitest run","build":"tsup","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"adarshsingh05","email":"adarshashokbaghel@gmail.com"},"_npmVersion":"11.6.2","description":"A drop-in spend cap and audit log for LLM API calls","directories":{},"_nodeVersion":"24.12.0","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.4.0","vitest":"^3.0.9","typescript":"^5.8.2","@types/node":"^22.13.10"},"_npmOperationalInternal":{"tmp":"tmp/agent-guard_0.1.1_1783774891172_0.9568578469744977","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@adarshsingh05/agent-guard","version":"0.1.2","keywords":["llm","openai","anthropic","spend-cap","audit-log","agent","cost"],"author":{"name":"adarshsingh05"},"license":"MIT","_id":"@adarshsingh05/agent-guard@0.1.2","maintainers":[{"name":"adarshsingh05","email":"adarshashokbaghel@gmail.com"}],"bin":{"agent-guard":"cli.js"},"dist":{"shasum":"d63be3fb22b9d30b3d0660845befa2eddc789d60","tarball":"https://registry.npmjs.org/@adarshsingh05/agent-guard/-/agent-guard-0.1.2.tgz","fileCount":15,"integrity":"sha512-V+IMdEys+bBtpNxEaGcxZfidkwxwjIBSnL7WodO+5Fn3DeXsO704/k9Gu89Ni8U9btCFYyKlm1b4GfvHU0YiaQ==","signatures":[{"sig":"MEYCIQCTDPhCMEe8FFJ4Ef7uRKtd0ejbpDk2pPgd1464FwBuegIhAODKPk6lSk+3lUIVXNBasnjc7THWjwFXmKH16WZ5GtIl","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1887275},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"gitHead":"c4dd14aa456f4e1ed9f7b9c0701b07b35e498a6e","scripts":{"test":"vitest run","build":"tsup","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"adarshsingh05","email":"adarshashokbaghel@gmail.com"},"_npmVersion":"11.6.2","description":"A drop-in spend cap and audit log for LLM API calls","directories":{},"_nodeVersion":"24.12.0","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.4.0","vitest":"^3.0.9","typescript":"^5.8.2","@types/node":"^22.13.10"},"_npmOperationalInternal":{"tmp":"tmp/agent-guard_0.1.2_1783775179134_0.516393179945791","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"@adarshsingh05/agent-guard","version":"0.1.3","keywords":["llm","openai","anthropic","spend-cap","audit-log","agent","cost"],"author":{"name":"adarshsingh05"},"license":"MIT","_id":"@adarshsingh05/agent-guard@0.1.3","maintainers":[{"name":"adarshsingh05","email":"adarshashokbaghel@gmail.com"}],"bin":{"agent-guard":"cli.js"},"dist":{"shasum":"738985e4279b04e8b14b26635eee8882a027f04b","tarball":"https://registry.npmjs.org/@adarshsingh05/agent-guard/-/agent-guard-0.1.3.tgz","fileCount":15,"integrity":"sha512-lfvGwwN2rNp3V9EXCCrKJ3rOkNNK3I8qwCtogWb4ineiAYNK3w2sd4lqezzV+Re3/lc8L6ga2H8NQ5fdy/Hf+A==","signatures":[{"sig":"MEYCIQDlyGrub1KSImfPDxI83Ny0ZJQf1euaeD9EMsl0s3WJOAIhAKMTqJnHBvitKulkh1K80UV1iMnymWcjmp0H/hmnzYCj","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":287087},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"gitHead":"c4dd14aa456f4e1ed9f7b9c0701b07b35e498a6e","scripts":{"test":"vitest run","build":"tsup","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"adarshsingh05","email":"adarshashokbaghel@gmail.com"},"_npmVersion":"11.6.2","description":"A drop-in spend cap and audit log for LLM API calls","directories":{},"_nodeVersion":"24.12.0","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.4.0","vitest":"^3.0.9","typescript":"^5.8.2","@types/node":"^22.13.10"},"_npmOperationalInternal":{"tmp":"tmp/agent-guard_0.1.3_1783775380760_0.8415175798462482","host":"s3://npm-registry-packages-npm-production"}},"0.1.4":{"name":"@adarshsingh05/agent-guard","version":"0.1.4","description":"A drop-in spend cap and audit log for LLM API calls","license":"MIT","author":{"name":"adarshsingh05"},"keywords":["llm","openai","anthropic","spend-cap","audit-log","agent","cost"],"type":"module","engines":{"node":">=18"},"main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"bin":{"agent-guard":"cli.js"},"scripts":{"build":"tsup","test":"vitest run","test:watch":"vitest","prepublishOnly":"npm run build"},"devDependencies":{"@types/node":"^22.13.10","tsup":"^8.4.0","typescript":"^5.8.2","vitest":"^3.0.9"},"gitHead":"c4dd14aa456f4e1ed9f7b9c0701b07b35e498a6e","_id":"@adarshsingh05/agent-guard@0.1.4","_nodeVersion":"24.12.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-FTX50ZEv0nH34s6G7UvmcuIfepAQijhcC5ZMUBuphHxlLsQJtOXZ09jsujXSkuPky5m8Ybkf6egvpn6fzftlXQ==","shasum":"fd9e5c181e7a291f0803dbf298700f7dd2d100ae","tarball":"https://registry.npmjs.org/@adarshsingh05/agent-guard/-/agent-guard-0.1.4.tgz","fileCount":15,"unpackedSize":287211,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDnVou6jL3P+KKGAeMSHabUwVD7AXlwdMVrrpQVx5mN1AiEA8foPkKDD7TivTZUN1vuW59KWEDESGmwtQqvsV1BpZAM="}]},"_npmUser":{"name":"adarshsingh05","email":"adarshashokbaghel@gmail.com"},"directories":{},"maintainers":[{"name":"adarshsingh05","email":"adarshashokbaghel@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent-guard_0.1.4_1783775457073_0.113398055352808"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-11T12:53:38.612Z","modified":"2026-07-11T13:10:57.324Z","0.1.0":"2026-07-11T12:53:38.840Z","0.1.1":"2026-07-11T13:01:31.361Z","0.1.2":"2026-07-11T13:06:19.356Z","0.1.3":"2026-07-11T13:09:40.969Z","0.1.4":"2026-07-11T13:10:57.230Z"},"author":{"name":"adarshsingh05"},"license":"MIT","keywords":["llm","openai","anthropic","spend-cap","audit-log","agent","cost"],"description":"A drop-in spend cap and audit log for LLM API calls","maintainers":[{"name":"adarshsingh05","email":"adarshashokbaghel@gmail.com"}],"readme":"# agent-guard\n\n**A drop-in spend cap and local audit log for LLM API calls.**\n\nIn 2026, a misconfigured agent loop on Cloudflare Durable Objects generated a **$34,000 bill in 8 days** — because there was no real-time spending safeguard. `agent-guard` wraps your LLM calls, enforces a hard dollar ceiling, and keeps a receipt on disk.\n\n- No account  \n- No hosted dashboard  \n- No telemetry leaving your machine  \n- **Zero runtime dependencies**\n\n---\n\n## See it in action\n\n**1. Cap blocks the next call**\n\n![Spend cap exceeded in the terminal](https://cdn.jsdelivr.net/npm/@adarshsingh05/agent-guard@0.1.3/docs/cap-hit.png)\n\n**2. Local spend summary**\n\n![agent-guard log --summary output](https://cdn.jsdelivr.net/npm/@adarshsingh05/agent-guard@0.1.3/docs/log-summary.png)\n\n---\n\n## Table of contents\n\n1. [See it in action](#see-it-in-action)\n2. [What it does](#what-it-does)\n3. [How to test locally](#how-to-test-locally)\n4. [Requirements](#requirements)\n5. [Step 1 — Install from npm](#step-1--install-from-npm)\n6. [Step 2 — Initialize](#step-2--initialize)\n7. [Step 3 — Wrap your LLM calls](#step-3--wrap-your-llm-calls)\n8. [Step 4 — Handle the spend cap](#step-4--handle-the-spend-cap)\n9. [Step 5 — Monitor spend (CLI)](#step-5--monitor-spend-cli)\n10. [Cap scopes](#cap-scopes)\n11. [Privacy](#privacy)\n12. [Pricing updates](#pricing-updates)\n13. [API reference](#api-reference)\n14. [Known limitations](#known-limitations)\n15. [FAQ](#faq)\n\n---\n\n## What it does\n\n| Feature | Behavior |\n|--------|----------|\n| **Spend cap** | Before each wrapped call, if spend `>= maxSpend`, throws `SpendCapExceededError` and **does not** call the API |\n| **Audit log** | Every call is recorded locally (model, tokens, cost, latency, success/fail, prompt hash) |\n| **Model pin warning** | Warns once if you use a floating alias like `gpt-4o` or `*-latest` |\n\n**Flow**\n\n```\nyour agent  →  guard(wrapped SDK call)  →  check budget\n                                         →  call LLM (if under cap)\n                                         →  write local log + add $\n                                         →  throw if next call would exceed cap\n```\n\n---\n\n## How to test locally\n\n### A) From this repo (no npm install needed)\n\n```bash\ncd agent-guard\nnpm install\nnpm test          # unit tests\nnpm run build\n\nnode --input-type=module -e '\nimport { guard, SpendCapExceededError } from \"./dist/index.js\";\n\nconst fake = async () => ({\n  model: \"gpt-4o-mini\",\n  usage: { prompt_tokens: 500000, completion_tokens: 500000 },\n});\n\nconst g = guard(fake, { maxSpend: 0.05, provider: \"openai\", onWarn: () => {} });\n\ntry {\n  await g({ model: \"gpt-4o-mini\", messages: [{ role: \"user\", content: \"hi\" }] });\n  await g({ model: \"gpt-4o-mini\", messages: [{ role: \"user\", content: \"hi\" }] });\n} catch (e) {\n  console.log(e instanceof SpendCapExceededError ? \"CAP HIT:\" : \"ERR:\", e.message);\n}\n'\n\nnode dist/cli.js log --summary\n```\n\n**Expected:** `CAP HIT: ...` then a summary with `Calls: 1` and `Total spend: $0.375000`.\n\n### B) As an end user (after the package is public on npm)\n\n```bash\nmkdir /tmp/ag-demo && cd /tmp/ag-demo\nnpm init -y\nnpm install @adarshsingh05/agent-guard\n```\n\nThen create `test.mjs`:\n\n```js\nimport { guard, SpendCapExceededError } from \"@adarshsingh05/agent-guard\";\n\nconst fake = async () => ({\n  model: \"gpt-4o-mini\",\n  usage: { prompt_tokens: 500000, completion_tokens: 500000 },\n});\n\nconst g = guard(fake, { maxSpend: 0.05, provider: \"openai\", onWarn: () => {} });\n\ntry {\n  await g({ model: \"gpt-4o-mini\", messages: [{ role: \"user\", content: \"hi\" }] });\n  await g({ model: \"gpt-4o-mini\", messages: [{ role: \"user\", content: \"hi\" }] });\n} catch (e) {\n  console.log(e instanceof SpendCapExceededError ? \"CAP HIT:\" : \"ERR:\", e.message);\n}\n```\n\n```bash\nnode test.mjs\nnpx agent-guard log --summary   # if CLI bin is present\n```\n\nIf `npm install` says **404 Not Found**, open [npm → Staged Packages](https://www.npmjs.com/) and **approve / publish** the staged release first.\n\n### Capture screenshots for the README (macOS)\n\n1. Run the local demo above so `CAP HIT` and `log --summary` are on screen.\n2. Press **`Cmd + Shift + 4`**, drag over the terminal.\n3. Save / move files to:\n   - `docs/cap-hit.png`\n   - `docs/log-summary.png`\n4. Commit and push — GitHub (and npm, if `docs/` is in the package) will show them.\n\n---\n\n## Requirements\n\n- **Node.js** `>= 18`\n- Prefer **Node ≥ 22.5** for SQLite logging (`node:sqlite`). Older Node falls back to JSON-lines automatically.\n- An existing OpenAI, Anthropic, or similar SDK call you can wrap\n\n---\n\n## Step 1 — Install from npm\n\nIn your project (Cursor terminal, VS Code terminal, or any shell):\n\n```bash\nnpm install @adarshsingh05/agent-guard\n```\n\nOr with pnpm / yarn:\n\n```bash\npnpm add @adarshsingh05/agent-guard\nyarn add @adarshsingh05/agent-guard\n```\n\nVerify the CLI is available:\n\n```bash\nnpx agent-guard --help\n```\n\nImport from the scoped package name:\n\n```js\nimport { guard, SpendCapExceededError } from \"@adarshsingh05/agent-guard\";\n```\n\n---\n\n## Step 2 — Initialize\n\nRun once per project:\n\n```bash\nnpx agent-guard init\n```\n\nThis creates:\n\n```\n.agent-guard/\n  config.json     # default maxSpend: $5\n  log.db          # created when the first call is logged (or log.jsonl on older Node)\n```\n\nAdd `.agent-guard/` to `.gitignore` if you do not want logs in git (init tries to append this automatically when a `.gitignore` already exists).\n\n---\n\n## Step 3 — Wrap your LLM calls\n\nKeep your existing SDK. Wrap the method you call in a loop.\n\n### OpenAI\n\n```js\nimport { guard, SpendCapExceededError } from \"@adarshsingh05/agent-guard\";\nimport OpenAI from \"openai\";\n\nconst client = new OpenAI(); // uses OPENAI_API_KEY\n\nconst create = guard(\n  client.chat.completions.create.bind(client.chat.completions),\n  {\n    maxSpend: 5.0,       // hard ceiling in USD\n    provider: \"openai\",  // used for pricing lookup\n    scope: \"session\",    // or \"global\" | \"day\"\n  },\n);\n\n// Use `create` everywhere you used to call chat.completions.create\nconst completion = await create({\n  model: \"gpt-4o-2024-08-06\", // prefer a pinned/dated model\n  messages: [{ role: \"user\", content: \"Hello\" }],\n});\n\nconsole.log(completion.choices[0].message.content);\n```\n\n### Anthropic\n\n```js\nimport { guard, SpendCapExceededError } from \"@adarshsingh05/agent-guard\";\nimport Anthropic from \"@anthropic-ai/sdk\";\n\nconst client = new Anthropic(); // uses ANTHROPIC_API_KEY\n\nconst create = guard(client.messages.create.bind(client.messages), {\n  maxSpend: 5.0,\n  provider: \"anthropic\",\n});\n\nconst response = await create({\n  model: \"claude-sonnet-4-20250514\",\n  max_tokens: 1024,\n  messages: [{ role: \"user\", content: \"Hello\" }],\n});\n\nconsole.log(response.content);\n```\n\n### Tip for Cursor users\n\n1. Open your agent project in Cursor.\n2. Run Steps 1–2 in the integrated terminal.\n3. Change your agent code to call the wrapped function instead of the raw SDK method.\n4. Run the agent as usual — when the budget is hit, the loop stops with `SpendCapExceededError`.\n\n---\n\n## Step 4 — Handle the spend cap\n\nWhen the running total reaches `maxSpend`, the **next** wrapped call is blocked:\n\n```js\ntry {\n  const result = await create({ /* ... */ });\n} catch (err) {\n  if (err instanceof SpendCapExceededError) {\n    console.error(\n      \"Budget reached — stopping agent.\",\n      `spent $${err.currentSpend.toFixed(4)} / max $${err.maxSpend}`,\n    );\n    process.exit(1); // or break your loop cleanly\n  }\n  throw err;\n}\n```\n\nExample terminal output:\n\n```text\nSpend cap exceeded: current $0.375000 >= max $0.05. Call blocked.\n```\n\n---\n\n## Step 5 — Monitor spend (CLI)\n\nAll monitoring is **local** — open your project terminal and use the CLI.\n\n### See a summary (most common)\n\n```bash\nnpx agent-guard log --summary\n```\n\nExample:\n\n```text\nCalls: 12 (11 ok / 1 fail)\nTotal spend: $1.842100\nBy model:\n  openai/gpt-4o-mini: 8 calls, $0.410000, in=12000 out=8000\n  anthropic/claude-sonnet-4-20250514: 4 calls, $1.432100, in=9000 out=5000\n```\n\n### Calls from today only (UTC)\n\n```bash\nnpx agent-guard log --today\n```\n\n### Full call list (today)\n\n```bash\nnpx agent-guard log --today\n# without --summary, prints one line per call\n```\n\nPer-line fields include timestamp, provider/model, cost, tokens, latency, ok/fail, and a short prompt hash.\n\n### Clear the log and day counters\n\n```bash\nnpx agent-guard reset\n```\n\nUse this when starting a fresh experiment or after testing.\n\n### Where is the data?\n\n| File | Purpose |\n|------|---------|\n| `.agent-guard/log.db` | SQLite audit log (Node ≥ 22.5) |\n| `.agent-guard/log.jsonl` | JSON-lines fallback |\n| `.agent-guard/config.json` | Defaults from `init` |\n| `.agent-guard/pricing.json` | Optional cached pricing from `update-pricing` |\n\nOverride the directory:\n\n```bash\nexport AGENT_GUARD_DIR=/path/to/my-guard-data\nnpx agent-guard log --summary\n```\n\n---\n\n## Cap scopes\n\nPass `scope` when calling `guard()`:\n\n| Scope | Meaning |\n|-------|---------|\n| `session` / `global` | Counter lives for this process only (resets when the process exits) |\n| `day` | Counter is persisted by UTC calendar day — restarts the same day share the same budget |\n\nExample — daily budget of $2:\n\n```js\nconst create = guard(fn, {\n  maxSpend: 2.0,\n  provider: \"openai\",\n  scope: \"day\",\n});\n```\n\n---\n\n## Privacy\n\nBy default:\n\n- Prompt and response **text are not stored**\n- Only a **SHA-256 hash** of the prompt payload is logged\n\nTo store truncated previews (opt-in):\n\n```js\nguard(fn, {\n  maxSpend: 5,\n  provider: \"openai\",\n  logPayloads: true,\n});\n```\n\n---\n\n## Pricing updates\n\nCosts use a bundled pricing table. Runtime **never** calls the network.\n\nRefresh the local cache (this CLI command may use the network):\n\n```bash\nnpx agent-guard update-pricing\n```\n\nUnknown models are recorded as `$0` with a one-time warning. Prefer pinned model IDs that exist in the table.\n\n---\n\n## API reference\n\n```ts\nimport { guard, SpendCapExceededError } from \"@adarshsingh05/agent-guard\";\n\nguard(fn, {\n  maxSpend: number;           // required — USD ceiling\n  provider: string;           // required — \"openai\" | \"anthropic\" | ...\n  scope?: \"global\" | \"session\" | \"day\";  // default \"global\"\n  logDir?: string;            // default: .agent-guard under cwd\n  forceJsonl?: boolean;       // force JSON-lines even if SQLite works\n  pricingPath?: string;       // custom pricing JSON path\n  logPayloads?: boolean;      // store truncated prompt/response (default false)\n  onWarn?: (message: string) => void;  // custom warning sink\n});\n```\n\n### CLI commands\n\n```bash\nnpx agent-guard init                 # create .agent-guard/ + config\nnpx agent-guard log --summary        # totals + breakdown by model\nnpx agent-guard log --today          # filter to UTC today\nnpx agent-guard reset                # clear log + day counters\nnpx agent-guard update-pricing       # refresh pricing cache (network)\nnpx agent-guard --help\n```\n\n### Environment variables\n\n| Variable | Purpose |\n|----------|---------|\n| `AGENT_GUARD_DIR` | Override `.agent-guard` directory |\n| `AGENT_GUARD_PRICING_URL` | Override URL used by `update-pricing` |\n\n---\n\n## Known limitations\n\n- **Streaming:** the cap is checked **before** each call, not mid-stream. One large call can slightly overshoot; the **next** call is blocked.\n- **No LangChain / framework adapters** in v0.1 — wrap the raw SDK method.\n- **No hosted UI** — monitoring is CLI + local files only (by design).\n\n---\n\n## FAQ\n\n**Do I need an agent-guard account?**  \nNo.\n\n**Does it send my prompts anywhere?**  \nNo. Everything stays on disk under `.agent-guard/` (hash only, by default).\n\n**Will this work inside Cursor?**  \nYes. Install and run it in your project terminal like any npm package. Cursor Cloud Agents / scripts that call LLM APIs the same way can wrap those calls too.\n\n**Why is the package scoped (`@adarshsingh05/agent-guard`)?**  \nThe unscoped name `agent-guard` is already taken on npm. Install and import the scoped name above.\n\n**How do I smoke-test without spending money?**  \nWrap a fake async function that returns OpenAI-shaped `usage`, set a tiny `maxSpend`, call it twice, then run `npx agent-guard log --summary`.\n\n---\n\n## License\n\nMIT\n","readmeFilename":"README.md"}