{"_id":"@jovan158/vantage","_rev":"5-6a8b36ac931f521be66629a3b0eda425","name":"@jovan158/vantage","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@jovan158/vantage","version":"0.1.0","keywords":["ai","cli","claude","claude-code","coding-agent","proxy","observability","tokens","cost","approvals"],"license":"MIT","_id":"@jovan158/vantage@0.1.0","maintainers":[{"name":"jovan158","email":"j.celikovic07@gmail.com"}],"homepage":"https://github.com/Jovan158/vantage.ai#readme","bugs":{"url":"https://github.com/Jovan158/vantage.ai/issues"},"bin":{"vantage":"bin/vantage.mjs"},"dist":{"shasum":"a80c76de160ccdb1a098f04601c273f514ab9a62","tarball":"https://registry.npmjs.org/@jovan158/vantage/-/vantage-0.1.0.tgz","fileCount":149,"integrity":"sha512-e7in4J2LD1alHKzn7/VzFvEljST52GXGreOpyx5XVA7GDFd6y+fE9kFRwl3c1iYuBFeB5m8UKy4LaPdjYQ7Rmg==","signatures":[{"sig":"MEQCIB2hBRds/blGwc6AQnaVwhc71mgSc/RlJdnybguCBc8NAiAiALWAX0HTRUaOmqXZRl2sFiXo5hyZRjRZ/wHZ+TaE2A==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":579156},"type":"module","engines":{"node":">=22.6"},"gitHead":"16406dc47fd1fa9d3f1ebd6ec546ca16d263d5b2","scripts":{"demo":"node --experimental-strip-types src/cli.ts demo","test":"node --experimental-strip-types --test test/*.test.ts","build":"tsc -p tsconfig.build.json","clean":"node -e \"import('node:fs').then(fs=>fs.rmSync('dist',{recursive:true,force:true}))\"","prepack":"npm run clean && npm run build","vantage":"node --experimental-strip-types src/cli.ts","typecheck":"tsc --noEmit","pricing:snapshot":"node --experimental-strip-types scripts/pricing-snapshot.ts"},"_npmUser":{"name":"jovan158","email":"j.celikovic07@gmail.com"},"repository":{"url":"git+https://github.com/Jovan158/vantage.ai.git","type":"git"},"_npmVersion":"11.5.2","description":"See and control what your coding agent does: live cost and quota, approvals, secret warnings, session replay, change summaries, project memory. Currently for Claude Code.","directories":{},"_nodeVersion":"24.6.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^7.0.2","@types/node":"^26.6.1"},"_npmOperationalInternal":{"tmp":"tmp/vantage_0.1.0_1790338406729_0.12667844876236023","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@jovan158/vantage","version":"0.1.1","keywords":["ai","cli","claude","claude-code","coding-agent","proxy","observability","tokens","cost","approvals"],"license":"MIT","_id":"@jovan158/vantage@0.1.1","maintainers":[{"name":"jovan158","email":"j.celikovic07@gmail.com"}],"homepage":"https://github.com/Jovan158/vantage.ai#readme","bugs":{"url":"https://github.com/Jovan158/vantage.ai/issues"},"bin":{"vantage":"bin/vantage.mjs"},"dist":{"shasum":"14ba182239b62bfa4d226b789bbb30ca95f11fcd","tarball":"https://registry.npmjs.org/@jovan158/vantage/-/vantage-0.1.1.tgz","fileCount":149,"integrity":"sha512-YHs6ni8k8ANie9Oa8ow/TeOhUWjAiNiZYokzW5+UvFm86tXeMm/qY/0K+917G5041KMoMlslDtyCPzyiojEAog==","signatures":[{"sig":"MEQCIFCehBFWabedZDL4EhF8umWtFWSQPaNLxUdqMU1LwwQoAiALzx8a/hzimuMx3OALw53n8yHaCtAZOxxMmokA6gkQIA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIHK1pAxTPIKQcPLehf/tmhZ3tSTatOMFbvbo3Qkx1HMlAiEA7Tzu/067w5zAItRCFrBPwFN67kNmhPW1a09Ef3ag8uY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":579029},"type":"module","engines":{"node":">=22.6"},"gitHead":"1999de7ad048ea2d69a9ce6a4b6762587ff3fa68","scripts":{"demo":"node --experimental-strip-types src/cli.ts demo","test":"node --experimental-strip-types --test test/*.test.ts","build":"tsc -p tsconfig.build.json","clean":"node -e \"import('node:fs').then(fs=>fs.rmSync('dist',{recursive:true,force:true}))\"","prepack":"npm run clean && npm run build","vantage":"node --experimental-strip-types src/cli.ts","typecheck":"tsc --noEmit","pricing:snapshot":"node --experimental-strip-types scripts/pricing-snapshot.ts"},"_npmUser":{"name":"jovan158","email":"j.celikovic07@gmail.com"},"repository":{"url":"git+https://github.com/Jovan158/vantage.ai.git","type":"git"},"_npmVersion":"11.5.2","description":"See and control what your coding agent does","directories":{},"_nodeVersion":"24.6.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^7.0.2","@types/node":"^26.6.1"},"_npmOperationalInternal":{"tmp":"tmp/vantage_0.1.1_1790340357846_0.1601864352764597","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@jovan158/vantage","version":"0.1.2","keywords":["ai","cli","claude","claude-code","coding-agent","proxy","observability","tokens","cost","approvals"],"license":"MIT","_id":"@jovan158/vantage@0.1.2","maintainers":[{"name":"jovan158","email":"j.celikovic07@gmail.com"}],"homepage":"https://github.com/Jovan158/vantage.ai#readme","bugs":{"url":"https://github.com/Jovan158/vantage.ai/issues"},"bin":{"vantage":"bin/vantage.mjs"},"dist":{"shasum":"eb55ae3d3bda712b691ac333697f8f3e85792893","tarball":"https://registry.npmjs.org/@jovan158/vantage/-/vantage-0.1.2.tgz","fileCount":149,"integrity":"sha512-QfeHor4KuZ2uIezfzM9R9YLnxXdy+ZV8fPvi2xyVsWJ835x1TqqVUZAy7v7Y0LaLJb76Xu/dZy3DqlUcTsfsJg==","signatures":[{"sig":"MEYCIQCNkYSWCEWfaZBkwmJD4uBZoXK1+gHT5C0GXv6K3csiqAIhAP86mHhuehhhb3Oju5nYRXZDlm4OsBfmQEt8KZf7GZxS","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIQCiDR/zXC002w54nuUAJODyVUsOCv+UV3dqCOcpoUphhwIgXRblg4NwVwhQMDAqk5+mEBdheW3Jq1Gtj1VssJN6YVs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@jovan158%2fvantage@0.1.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":582083},"type":"module","engines":{"node":">=22.6"},"gitHead":"02c360e665705c03dbf76cbc6d4a71d065a7bf83","scripts":{"demo":"node --experimental-strip-types src/cli.ts demo","test":"node --experimental-strip-types --test test/*.test.ts","build":"tsc -p tsconfig.build.json","clean":"node -e \"import('node:fs').then(fs=>fs.rmSync('dist',{recursive:true,force:true}))\"","prepack":"npm run clean && npm run build","vantage":"node --experimental-strip-types src/cli.ts","typecheck":"tsc --noEmit","pricing:snapshot":"node --experimental-strip-types scripts/pricing-snapshot.ts"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:cf2ecfaa-7ede-445c-b2dc-19a63a2c5856"}},"repository":{"url":"git+https://github.com/Jovan158/vantage.ai.git","type":"git"},"_npmVersion":"11.20.0","description":"See and control what your coding agent does","directories":{},"_nodeVersion":"22.23.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^7.0.2","@types/node":"^26.6.1"},"_npmOperationalInternal":{"tmp":"tmp/vantage_0.1.2_1790344250403_0.029462236690435573","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"@jovan158/vantage","version":"0.1.3","keywords":["ai","cli","claude","claude-code","coding-agent","proxy","observability","tokens","cost","approvals"],"license":"MIT","_id":"@jovan158/vantage@0.1.3","maintainers":[{"name":"jovan158","email":"j.celikovic07@gmail.com"}],"homepage":"https://github.com/Jovan158/vantage.ai#readme","bugs":{"url":"https://github.com/Jovan158/vantage.ai/issues"},"bin":{"vantage":"bin/vantage.mjs"},"dist":{"shasum":"c5cbbb66e2380dc93d717044ffb47c1e09a0ff3a","tarball":"https://registry.npmjs.org/@jovan158/vantage/-/vantage-0.1.3.tgz","fileCount":54,"integrity":"sha512-LLew3IbjjVjVxaWTt8JwB8BM/VE0tr67djDg+edSeMVsaE3KDQ1ZW49AVbo3CALiYxVZ+ES2rRAFF/L6UDbmCg==","signatures":[{"sig":"MEUCIQCn7fpYfuzWO4rgLEsgJq1ilQ+y0i7Rgfwl5xts/8IQcAIgfkNrzckzEAX8o3H6TbP51oL2eWG+EJjf3e8DSSYNhuc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEQCIE8GQLR4WWAoud/avXTfiroDltHled2ZmG7OI6IdVurDAiAP9e9UPOyeKlde9l3jkjDBHUVwVQLfpZ6C7S6Qq/P8Ng==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@jovan158%2fvantage@0.1.3","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":269867},"type":"module","engines":{"node":">=22.6"},"gitHead":"98cf4460946aee5855ac5cedc0ceef288ec332bc","scripts":{"demo":"node --experimental-strip-types src/cli.ts demo","test":"node --experimental-strip-types --test test/*.test.ts","build":"tsc -p tsconfig.build.json","clean":"node -e \"import('node:fs').then(fs=>fs.rmSync('dist',{recursive:true,force:true}))\"","prepack":"npm run clean && npm run build","vantage":"node --experimental-strip-types src/cli.ts","typecheck":"tsc --noEmit","pricing:snapshot":"node --experimental-strip-types scripts/pricing-snapshot.ts"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:cf2ecfaa-7ede-445c-b2dc-19a63a2c5856"}},"repository":{"url":"git+https://github.com/Jovan158/vantage.ai.git","type":"git"},"_npmVersion":"11.20.0","description":"See and control what your coding agent does","directories":{},"_nodeVersion":"22.23.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^7.0.2","@types/node":"^26.6.1"},"_npmOperationalInternal":{"tmp":"tmp/vantage_0.1.3_1790347615325_0.06866848739700337","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"_id":"@jovan158/vantage@0.2.0","bin":{"vantage":"bin/vantage.mjs"},"bugs":{"url":"https://github.com/Jovan158/vantage.ai/issues"},"dist":{"shasum":"a68f9a805a141ad58ceb91a74f548baffeecc8e0","tarball":"https://registry.npmjs.org/@jovan158/vantage/-/vantage-0.2.0.tgz","fileCount":66,"integrity":"sha512-E9Ak7WV2jSppxdTb2ELwIxc+dm90ghZSyq6a/4QmqgGnhP4O1Aj8E+ACmSfkYu5Ol32pFz7g0V/F7hp247DXrQ==","signatures":[{"sig":"MEQCIGm7wtUvlCHeljaCxwlhqiF3fEw/xkv9QT0y+atFiaMHAiAiwifSRtJdvuK/2LOQXVwWrBg8fkwFo8OROGbbqPlEOg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCkee//nvFG8zcjEs/3Copv4Zcu+5mQN03vc6WOenf0NwIgW1mj92FJGGrTps9xFilSqOKIqK5mI+R0mrVBOy2SYa4="}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@jovan158%2fvantage@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":377792},"name":"@jovan158/vantage","type":"module","engines":{"node":">=22.6"},"gitHead":"41f7ac11432dd8e5c8389cf872901f7e7ab93e73","license":"MIT","scripts":{"demo":"node --experimental-strip-types src/cli.ts demo","test":"node --experimental-strip-types --test test/*.test.ts","build":"tsc -p tsconfig.build.json","clean":"node -e \"import('node:fs').then(fs=>fs.rmSync('dist',{recursive:true,force:true}))\"","prepack":"npm run clean && npm run build","vantage":"node --experimental-strip-types src/cli.ts","typecheck":"tsc --noEmit","pricing:snapshot":"node --experimental-strip-types scripts/pricing-snapshot.ts"},"version":"0.2.0","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:cf2ecfaa-7ede-445c-b2dc-19a63a2c5856"}},"homepage":"https://github.com/Jovan158/vantage.ai#readme","keywords":["ai","cli","claude","claude-code","codex","copilot","opencode","coding-agent","proxy","observability","tokens","cost","approvals"],"repository":{"url":"git+https://github.com/Jovan158/vantage.ai.git","type":"git"},"_npmVersion":"11.20.0","description":"See and control what your coding agent does","directories":{},"maintainers":[{"name":"jovan158","email":"j.celikovic07@gmail.com"}],"_nodeVersion":"22.23.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^7.0.2","@types/node":"^26.6.1"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/vantage_0.2.0_1790407906838_0.7535496303400204"}}},"time":{"created":"2026-09-25T12:13:26.521Z","modified":"2026-09-26T07:31:47.228Z","0.1.0":"2026-09-25T12:13:26.876Z","0.1.1":"2026-09-25T12:45:58.007Z","0.1.2":"2026-09-25T13:50:50.501Z","0.1.3":"2026-09-25T14:46:55.416Z","0.2.0":"2026-09-26T07:31:46.928Z"},"bugs":{"url":"https://github.com/Jovan158/vantage.ai/issues"},"license":"MIT","homepage":"https://github.com/Jovan158/vantage.ai#readme","keywords":["ai","cli","claude","claude-code","codex","copilot","opencode","coding-agent","proxy","observability","tokens","cost","approvals"],"repository":{"url":"git+https://github.com/Jovan158/vantage.ai.git","type":"git"},"description":"See and control what your coding agent does","maintainers":[{"name":"jovan158","email":"j.celikovic07@gmail.com"}],"readme":"
\n \n
\n\n
\n See and control what your coding agent does. \n Live cost and limits, approvals for files and commands, secret warnings and a record of every session.\n
\n\n
\n \n \n \n \n
\n\nVantage is a free, open-source cost and usage monitor, guardrail and session log for coding agents. Start your agent with `vantage run ` and work as usual: Vantage shows what the session costs and how much of your limit is left, asks before the agent touches the files and commands you care about, warns you when a secret is sent to the API, and records everything so you can look back.\n\n**Everything stays on your machine.** Vantage sends no telemetry and changes nothing in your agent's setup. The only request it makes on its own is `vantage pricing update`, and only when you run it.\n\n## Why\n\n- **Limits arrive without warning.** On a subscription, you find out you hit the 5-hour limit when the agent stops mid-task. Vantage shows your quota live, forecasts whether your pace lasts until the reset, and warns you before you hit it.\n- **\"Allow everything\" or \"ask every time\".** Vantage lets you allow `npm test`, ask before `git push --force`, and ask before anything reads `.env`.\n- **Secrets leave your machine silently.** When the agent reads a `.env` file, the password goes to the API with the next request. Vantage tells you right away what it was and where it came from, so you can rotate it.\n- **What did it actually do?** After a long session it is hard to tell what changed. Vantage ends every session with the files it changed and keeps a searchable timeline of prompts, replies and tool calls.\n\n## Features\n\n- **Cost and limits, live.** Tokens, estimated cost at the official list prices of Anthropic, OpenAI and Google, and on a subscription the 5-hour and weekly quota with a forecast.\n- **Budgets.** Past a cost or quota limit you set, every action needs your approval.\n- **Approvals by action type, file and command.** Allow, warn, ask or deny file reads, writes, shell commands and network access, or specific files and commands.\n- **Alerts in the chat.** Secret warnings, low quota and budgets appear in the agent's chat, right after the reply.\n- **Live view.** `vantage watch` in a second terminal shows what the agent is doing, from any folder, and several sessions side by side.\n- **Session replay, stats and search.** Every prompt, reply and tool call as a timeline; usage over days and projects; find the session that read a file or ran a command.\n- **Change summary.** In a git repository, every session ends with the files it changed. Or run fully isolated in a separate git worktree.\n- **Project memory.** Decisions and conventions in `.vantage/memory/`, given to the agent at every start.\n\n## Install\n\n```bash\nnpm install -g @jovan158/vantage\n```\n\nNeeds Node.js 22.6 or newer and at least one of the agents below, installed and logged in. Vantage uses that login and needs no key of its own.\n\n## Quick start\n\n```bash\nvantage doctor # check the setup once: which agents are there\nvantage policy init # optional: recommended rules, e.g. ask before reading .env\nvantage run # instead of the agent itself: claude, codex, copilot, opencode or pi\nvantage watch # live view, in a second terminal\n```\n\n## Supported agents\n\n| Agent | Start with | Tokens and cost | Usage limits | Rules that ask | Alerts in its chat |\n| --- | --- | --- | --- | --- | --- |\n| Claude Code | `vantage run claude` | yes | 5-hour and weekly (subscription) | ask | yes |\n| Codex | `vantage run codex` | yes | 5-hour and weekly (subscription) | block instead | yes |\n| Copilot CLI | `vantage run copilot` | yes | - | ask | yes |\n| OpenCode | `vantage run opencode` | yes | - | block instead | as a toast |\n| pi | `vantage run pi` | yes | - | ask | as a notification |\n\n- **Tokens and cost:** the cost is shown for Claude, GPT and Gemini models, whichever agent calls them; for other models (DeepSeek or Mistral through OpenCode, say) Vantage counts the tokens and says the price is unknown (see [Prices](#prices)).\n- **Usage limits:** only subscriptions have them (Claude Pro or Max, ChatGPT plans), and their provider reports them with every response. An API key has no 5-hour or weekly window: you pay per token, so the cost and a cost budget (`--max-cost`) are what count. Copilot's monthly premium requests are not in its responses, so Vantage cannot show them.\n- **Rules that ask:** Codex and OpenCode can block a tool call from a hook but not pause to ask. There a rule set to `ask` blocks the action, and the agent is told to leave it to you. `deny` works everywhere.\n\n## Guide\n\nHow to use each part, step by step:\n\n1. [Start a session](#start-a-session): `vantage run`, passing options to the agent, the summary at the end\n2. [Watch it live](#watch-it-live): the live view, line by line\n3. [Alerts in the chat](#alerts-in-the-chat): what Vantage tells you while the agent works\n4. [Approval rules](#approval-rules): allow, warn, ask or deny by action type, file and command\n5. [Budgets](#budgets): ask before every action past a cost or quota limit\n6. [Secret warnings](#secret-warnings): what counts as a secret, and what to do\n7. [Look back](#look-back): sessions, replay, stats and search\n8. [Review what changed](#review-what-changed): the change summary, the full diff, isolated sessions\n9. [Project memory](#project-memory): decisions and conventions the agent gets at every start\n10. [Prices](#prices): where the cost estimate comes from\n11. [Troubleshooting](#troubleshooting)\n\nAlso: [Reference](#reference) (commands, options, environment variables, how it works)\n\n### Start a session\n\nOpen a terminal in your project and run `vantage run ` instead of the agent itself. It starts as usual, with your login, your settings and your own hooks; Vantage runs alongside it. Everything after `--` is passed on to the agent:\n\n```bash\nvantage run # the agent as usual, e.g. its interactive chat\nvantage run -- # everything after -- goes to the agent\nvantage run claude -- --model claude-opus-5-5 # for example: pick the model\nvantage run codex -- exec \"fix the failing test\" # or: one prompt, no chat\n```\n\nWhen the agent exits, Vantage sums up the session: requests, tokens, estimated cost, on a subscription your quota, and in a git repository the files that changed. Each session has an id (like `2026-09-25T13-01-30-311Z_4i4f`); `vantage sessions` lists them, and the commands below take it to look back at one.\n\n### Watch it live\n\nOpen a second terminal, anywhere, and run `vantage watch`. It follows the session you started last, even in another folder, and updates twice a second.\n\n
\n \n
\n\n- **Status:** what the agent is doing right now: thinking, working on a tool (with the file or command), waiting for your approval, or replied.\n- **Limits:** on a subscription, your 5-hour and weekly quota as bars, when each resets, how much of it this session used, and whether your current pace lasts until the reset. The limits belong to your whole account, so other use counts too. With an API key there are none, and this part is left out.\n- **This session:** your messages against the model calls they caused, the estimated cost, a budget if you set one, and how many tokens the last message sent (and how much came from the cache).\n- **Activity:** the latest tool calls with the file, command or URL they touched, marked `asked` or `blocked` when a rule stepped in.\n\nWith several sessions running, `vantage watch` shows them side by side, with the limits once for all of them; `vantage watch ` shows one in detail. `Ctrl-C` stops watching; the agent keeps running.\n\n### Alerts in the chat\n\nWhile the agent's chat is open, Vantage never writes into its terminal. Alerts appear in the agent's own UI, right after the reply, as `Vantage: …` or `Vantage ALERT: …` (how exactly depends on the agent, see [Supported agents](#supported-agents)). `vantage watch` shows them live as well:\n\n- a secret was sent to the API (see [Secret warnings](#secret-warnings))\n- on a subscription: a quota window reached 90% (change the threshold with `VANTAGE_QUOTA_WARN`), or a limit was reached and requests are blocked\n- your budget was reached\n- an action type set to `warn` was used for the first time in this session\n\nEach alert comes once. Alerts still waiting when the agent exits are printed then; when the agent runs a single prompt without its chat, they are printed right away.\n\n### Approval rules\n\nWithout any setup, Vantage only notices: shell commands and network access are `warn` (a note, nothing is blocked) and everything else is `allow`. To have the agent ask you first, or to block something outright, create rules for your project:\n\n```bash\nvantage policy init # writes .vantage/policy.json with recommended rules\nvantage policy # shows the rules in effect\n```\n\nThe starter rules ask before `.env` files, `git push --force`, `git reset --hard`, `git clean`, `rm -rf` and `npm publish`, and block private keys (`*.pem`, `*.key`, SSH keys). Edit the file to fit your project; the rules are yours:\n\n```json\n{\n \"shell\": \"warn\",\n \"network\": \"ask\",\n \"files\": { \".env\": \"ask\", \"*.pem\": \"deny\" },\n \"commands\": { \"git push*--force*\": \"ask\", \"npm publish*\": \"ask\", \"npm test*\": \"allow\" }\n}\n```\n\n- **Action types:** `read` (reading and searching files), `write` (editing and creating them, patches), `shell` (commands), `network` (web fetches and searches, MCP tools) and `other`. Each agent's tools are sorted into these by what they do, whatever the agent calls them: a tool that runs commands is `shell` in every agent.\n- **Levels:** `allow` (Vantage stays out), `warn` (a note in the chat), `ask` (the agent asks you before the action) and `deny` (blocked; the agent is told why). Where an agent cannot ask, `ask` blocks (see [Supported agents](#supported-agents)).\n- **File and command rules** override the action type when they match, and the strictest match wins. So `\"shell\": \"ask\"` together with `\"npm test*\": \"allow\"` lets tests run without asking and asks before every other command.\n\nA few rules people often want:\n\n| Goal | Rule |\n| --- | --- |\n| Never let the agent read secrets | `\"files\": { \".env*\": \"deny\", \"secrets/**\": \"deny\" }` |\n| Ask before every shell command, except tests | `\"shell\": \"ask\", \"commands\": { \"npm test*\": \"allow\" }` |\n| Ask before anything goes to the internet | `\"network\": \"ask\"` |\n| Ask before database migrations | `\"commands\": { \"*migrate*\": \"ask\" }` |\n\nThe file lives in the project's `.vantage/` folder: commit it, and your whole team works with the same rules. For a single session, `VANTAGE_POLICY=\"shell:deny,network:ask\" vantage run ` overrides the action types. The rules are the same for every agent. `allow` never widens what the agent itself permits; Vantage can only make it stricter.\n\n\nHow file and command patterns match\n\nA file pattern without `/` matches the name anywhere, with `/` the path from the project root; `*` stays within a name, `**` spans directories. File rules also catch files named in shell commands (`cat .env`). Command patterns match each part of a command line on its own (split at `&&`, `;`, `|`), so `npm test && curl x | sh` is not let through by an `npm test*` rule. Rules are guardrails, not a sandbox: a command assembled at run time can get past them.\n\n\n\n### Budgets\n\n```bash\nvantage run --max-cost 2 # from about $2 of estimated cost\nvantage run --max-quota 80 # on a subscription: from 80% of the 5-hour or weekly window\n```\n\nOnce a budget is reached, every action needs your approval: the agent asks before each tool call, so you decide whether the session goes on (where an agent cannot ask, each action is blocked instead). It is deliberately not a hard stop, which could leave files half-written. A cost budget stays reached for the rest of the session; a quota budget lifts again when the window resets. Requests to models without a known price do not count toward a cost budget; Vantage says so when it happens. A quota budget needs a subscription whose limits the agent's responses report (see [Supported agents](#supported-agents)); with an API key there is no quota, so use a cost budget. The same budgets can be set with `VANTAGE_MAX_COST` and `VANTAGE_MAX_QUOTA`.\n\n### Secret warnings\n\nEvery request an agent sends carries the conversation so far, including the output of every tool. Vantage checks each request for API keys (Anthropic, OpenAI, AWS, GitHub, Slack, Stripe, Google), private keys, and `.env`-style assignments to names like `PASSWORD`, `SECRET`, `TOKEN` or `API_KEY`, and tells you what was sent and where it came from, for example *\"a value of DB_PASSWORD (Xk9v…(12 chars)) was sent to the API, from the output of Read .env\"*.\n\nThe secret has already left your machine at that point, so rotate it if it matters. To keep it from happening again, add a rule such as `\"files\": { \".env*\": \"deny\" }`. Vantage never stores the secret itself, only its kind, a masked prefix and where it came from.\n\n### Look back\n\n```bash\nvantage sessions # the sessions of this project\nvantage replay # one session as a timeline: prompts, replies, tools, cost\nvantage stats # usage by day and project, last 7 days\nvantage stats --days 30\nvantage search \"npm publish\" # which session did this?\nvantage search .env --files # only file names\nvantage search migrate --commands # only commands\n```\n\n`stats`, `search` and `replay ` cover every project on this machine, not only the current one. Sessions add up over time: `vantage sessions prune` lists the ones nobody touched for 30 days, with their size, and deletes them only with `--yes` (`--older-than 12h` / `2w` changes the age, `--all` includes every project).\n\n### Review what changed\n\nIn a git repository, every session ends with a list of the files it changed. Edits you made yourself meanwhile are included, and the list says so. Later:\n\n```bash\nvantage review # the files, with lines added and removed\nvantage review --patch # the full diff\n```\n\n`vantage review` also prints the command that undoes the session's changes. Your git index and history are never touched.\n\nTo keep the agent away from your working copy entirely, use `vantage run --isolate `. It then works in a separate git worktree on its own branch, `vantage/`. At the end, Vantage commits the work to that branch and shows what changed; you decide what happens to it:\n\n```bash\nvantage review # what changed\ngit merge --no-ff vantage/ # take it\nvantage discard # or throw it away\n```\n\n### Project memory\n\nAgents forget everything between sessions. Project memory is a few Markdown files that Vantage gives to the agent at the start of every session, whichever agent it is:\n\n```bash\nvantage memory init # creates .vantage/memory/: architecture, conventions, decisions, glossary\nvantage memory add decisions \"Use Postgres, not SQLite\"\nvantage memory show # what the agent will get\nvantage run --no-memory # a session without it\n```\n\nEdit the files directly, too; commit them to share them with your team. After a session that changed something, `vantage harvest ` suggests what might be worth recording; nothing is written without you.\n\n### Prices\n\nThe cost is an estimate: the tokens of each request at the model maker's official list price, including cache reads and writes.\n\n- **Claude models** at [Anthropic's price list](https://platform.claude.com/docs/en/about-claude/pricing), **GPT models** at [OpenAI's](https://developers.openai.com/api/docs/pricing), **Gemini models** at [Google's](https://ai.google.dev/gemini-api/docs/pricing), whichever agent calls them. The same model has the same price however an agent names it (`claude-sonnet-4.6`, `anthropic/claude-sonnet-4-6`).\n- **Standard prices**: batch, flex and priority rates are not used. Where a price depends on the prompt size (OpenAI's long-context rates above 272K tokens, Google's above 200K), the request is priced by its own size. A price change the page announces for a later day applies from that day on.\n- **Other models** (DeepSeek, Mistral, local models, …): Vantage counts the tokens and shows the cost as unknown rather than guessing.\n- **On a subscription** you do not pay per token: the cost is what the same use would cost on the API, and the quota bars are what counts. **With an API key** the cost is what you pay.\n\nA copy of the three price lists ships with Vantage and is updated with each release. `vantage pricing` shows the prices in use and their date (`vantage pricing openai` one list), and `vantage pricing update` fetches the current official lists. Vantage never fetches anything unless you run that command.\n\n### Troubleshooting\n\n- **Start with `vantage doctor`.** It checks Node.js, every agent it knows (installed or not), the approval hook, git, your rules file and the price list, and says what to do about anything that fails. `vantage doctor codex` checks one agent.\n- **\"… not found\":** set `VANTAGE_AGENT_PATH` to the agent's executable, for example `$env:VANTAGE_AGENT_PATH = \"C:\\path\\to\\agent.exe\"` in PowerShell.\n- **The agent cannot reach its API under Vantage:** Vantage forwards its requests to the provider's default address. If your plan or company uses another one (a gateway, a Copilot Enterprise address), set it with `VANTAGE_UPSTREAM`.\n- **No change summary:** the folder is not a git repository, or it has more than 2000 untracked files: add build output and dependencies to `.gitignore`.\n- **A rule does not apply:** `vantage policy` shows the rules as Vantage reads them; a file that is not valid JSON is ignored, and `vantage doctor` says so.\n- **Numbers look wrong:** `VANTAGE_DEBUG=1 vantage run ` logs what the API returns, including the format it was read as and the rate-limit headers.\n- **Found a bug?** [Open an issue](https://github.com/Jovan158/vantage.ai/issues/new/choose) with the output of `vantage doctor`.\n\n## Reference\n\n| Command | Description |\n| --- | --- |\n| `vantage run [options] [-- args]` | Start an agent through Vantage: `claude`, `codex`, `copilot`, `opencode`, `pi` |\n| `vantage watch [id]` | Live view: all running sessions side by side, or one in detail |\n| `vantage sessions` | List past sessions |\n| `vantage sessions prune [--older-than 30d] [--all] [--yes]` | Delete old sessions (lists them first; `--yes` deletes) |\n| `vantage stats [--days N]` | Usage by day and project, and the largest sessions |\n| `vantage search [--files \\| --commands]` | Which session did what: messages, files, commands, blocks |\n| `vantage replay ` | A session as a timeline |\n| `vantage review [--patch]` | Files a session changed, or the full diff |\n| `vantage discard ` | Discard an isolated session's worktree and branch |\n| `vantage memory init` · `add ` · `show` | Manage project memory |\n| `vantage harvest [id]` | Suggest what to remember from a session |\n| `vantage policy` · `vantage policy init` | Show the rules in effect · create a starter rule file |\n| `vantage pricing [provider]` · `vantage pricing update [provider]` | Show prices · fetch the current official lists (`anthropic`, `openai`, `google`) |\n| `vantage doctor [agent]` | Check the setup: agents, hook, git, rules, prices |\n\nOptions for `run`:\n\n| Option | Description |\n| --- | --- |\n| `--isolate` | Work in a separate git worktree and branch |\n| `--no-memory` | Don't pass project memory to the agent |\n| `--max-cost ` | Ask before every action once the estimated cost reaches this |\n| `--max-quota ` | The same, once a quota window is this full |\n\nEnvironment variables:\n\n| Variable | Description |\n| --- | --- |\n| `VANTAGE_POLICY` | Override the action-type levels for one session, e.g. `shell:deny,network:ask` |\n| `VANTAGE_MAX_COST`, `VANTAGE_MAX_QUOTA` | Budget, same as the `run` options |\n| `VANTAGE_QUOTA_WARN` | Quota warning threshold in percent (default 90) |\n| `VANTAGE_AGENT_PATH` | Path to the agent if it is not found on `PATH` |\n| `VANTAGE_UPSTREAM` | Send the agent's requests to this address instead of its provider's default (e.g. a company gateway) |\n| `VANTAGE_HOME` | Where Vantage keeps its own files (default `~/.vantage`) |\n| `VANTAGE_DEBUG=1` | Log upstream status and rate-limit headers |\n\n### How it works\n\n`vantage run` starts the agent with its provider's address pointing at a local proxy, through the setting the agent itself offers for it (an environment variable or a command-line option). The proxy forwards every request unchanged, WebSockets included, and reads token usage and rate-limit headers from the responses; it understands the Anthropic, OpenAI (Responses and Chat Completions) and Gemini APIs. Approvals and budgets go through each agent's own hooks, because tools run inside the agent and never pass the proxy; Vantage passes them for one session, on the command line or in the session's own folder. One `vantage hook` command speaks every agent's hook format; alerts reach the chat through the hook that runs after each reply.\n\nEach session is recorded in the project's `.vantage/sessions/`, including excerpts of prompts and replies; Vantage keeps that folder out of git with its own `.vantage/.gitignore`, so rules and project memory can still be committed. The price list and the index that `watch`, `stats` and `search` use across projects are kept in `~/.vantage`.\n\n## FAQ\n\n**Does it slow the agent down?** The proxy streams responses through as they arrive, without buffering. When rules or a budget are active, each tool call is checked by a short-lived process (about a tenth of a second); in the interactive chat, one also runs after each reply to show alerts.\n\n**Does it change my agent's setup?** No: hooks and memory are passed to each session on the command line or in the session's own folder, your settings files stay untouched, and your own hooks keep working.\n\n**Which agents does it support?** Claude Code, Codex, GitHub Copilot CLI, OpenCode and pi. See [Supported agents](#supported-agents) for what works with each.\n\n**How do I remove it?** `npm uninstall -g @jovan158/vantage`. To remove its data as well, delete `~/.vantage` and the `.vantage` folders in your projects.\n\n## Contributing\n\nIssues and pull requests are welcome. To work on Vantage, clone the repository, run `npm install` and `npm test`; Node.js runs the TypeScript source directly, without a build step. `vantage demo` runs the whole chain against a mock API, without an agent or an account; `node --experimental-strip-types scripts/e2e-agents.ts` runs every installed agent against a stand-in model API. Please report security issues privately through the repository's *Security* tab rather than in a public issue. Everyone taking part is expected to follow the [Code of Conduct](CODE_OF_CONDUCT.md).\n\n## License\n\n[MIT](LICENSE)\n","readmeFilename":"README.md"}
![\"vantage.ai\"](\"images/vantage.ai.jpg\")
\n![\"npm\"](\"https://img.shields.io/npm/v/@jovan158/vantage\")
![\"CI\"](\"https://github.com/Jovan158/vantage.ai/actions/workflows/ci.yml/badge.svg\"){kind=icon}
\n ![\"License:](\"https://img.shields.io/badge/license-MIT-blue\"){kind=icon}
![\"Node.js](\"https://img.shields.io/badge/node-%E2%89%A522.6-brightgreen\"){kind=icon}
![\"vantage](\"images/watch.png\")
\n