quota-axi 0.1.0 → 0.1.1

package/README.md

@@ -1,5 +1,7 @@
 <h1 align="center">quota-axi</h1>
 
+<h3 align="center">Your agent needs to be aware of your quota</h3>
+
 <p align="center">
   <a href="https://www.npmjs.com/package/quota-axi"><img alt="npm" src="https://img.shields.io/npm/v/quota-axi?style=flat-square" /></a>
   <a href="https://github.com/kunchenguid/quota-axi/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/kunchenguid/quota-axi/ci.yml?style=flat-square&label=ci" /></a>
@@ -8,17 +10,17 @@
   <a href="https://discord.gg/Wsy2NpnZDu"><img alt="Discord" src="https://img.shields.io/discord/1439901831038763092?style=flat-square&label=discord" /></a>
 </p>
 
-<h3 align="center">Know your local agent quota headroom without turning it into routing advice.</h3>
+Quota CLI for agents - designed with [AXI](https://axi.md) (Agent eXperience Interface).
 
 Agents need quota state before they choose where work can safely run.
 Vendor dashboards are not shaped for shell automation, and local CLIs expose different windows, resets, and auth files.
 
-quota-axi reports local Claude and Codex quota windows in one AXI-shaped call.
+quota-axi reports local Claude and Codex quota windows in one [AXI](https://axi.md)-shaped call.
 It is data only: it never routes, recommends, proxies, intercepts, logs in, imports browser cookies, or mutates provider state.
 
-- **Honest comparison ceiling** - quota-axi reports normalized quota windows, reset times, and provider credit balances when available.
-- **Local first** - it reads local Claude and Codex auth sources, calls first-party provider endpoints, and can fall back to a read-only Codex app-server probe.
-- **Agent shaped** - default stdout is compact TOON, with JSON available for callers that need the normalized model.
+- **Official sources** - quota-axi reads local Claude and Codex auth files and calls the same first-party usage endpoints the vendor CLIs use, with a read-only Codex app-server probe as fallback.
+- **Local first** - everything runs on the machine that holds the credentials; the only network calls are to Anthropic's and OpenAI's own usage endpoints, never a third-party relay.
+- **Token efficient** - default stdout is compact TOON so agents spend fewer tokens parsing quota state, with `--json` available when a caller needs the normalized model.
 
 ## Quick Start
 
@@ -26,23 +28,66 @@ It is data only: it never routes, recommends, proxies, intercepts, logs in, impo
 $ npx -y quota-axi
 bin: ~/.npm/_npx/.../quota-axi
 description: Report local agent-provider quota windows for routing-aware agents
-generatedAt: "2026-07-06T18:10:00.000Z"
+generatedAt: "2026-03-15T16:42:00.000Z"
 providers[2]{provider,plan,source,status,refreshedAt}:
-  claude,pro,oauth,fresh,"2026-07-06T18:09:55.000Z"
-  codex,plus,cli-rpc,fresh,"2026-07-06T18:09:58.000Z"
-windows[6]{provider,id,label,percentRemaining,resetsAt,state}:
-  claude,five_hour,session,82,"2026-07-06T22:15:00.000Z",fresh
-  claude,seven_day,week,64,"2026-07-10T16:00:00.000Z",fresh
-  claude,seven_day_opus,opus week,93,"2026-07-11T09:30:00.000Z",fresh
-  claude,extra_usage,extra usage,75,unknown,fresh
-  codex,five_hour,session,71,"2026-07-06T21:45:00.000Z",fresh
-  codex,weekly,week,43,"2026-07-11T09:00:00.000Z",fresh
+  claude,pro,oauth,fresh,"2026-03-15T16:41:55.000Z"
+  codex,plus,cli-rpc,fresh,"2026-03-15T16:41:58.000Z"
+windows[7]{provider,id,label,percentRemaining,resetsAt,state}:
+  claude,five_hour,session,82,"2026-03-15T21:15:00.000Z",fresh
+  claude,seven_day,week,64,"2026-03-19T15:00:00.000Z",fresh
+  claude,seven_day_opus,opus week,93,"2026-03-20T09:30:00.000Z",fresh
+  claude,"model:fable",Fable week,71,"2026-03-20T09:30:00.000Z",fresh
+  codex,five_hour,session,58,"2026-03-15T20:45:00.000Z",fresh
+  codex,weekly,week,47,"2026-03-19T09:00:00.000Z",fresh
+  codex,"model:gpt-5.1-codex:5h",GPT-5.1-Codex session,100,"2026-03-16T01:41:58.000Z",fresh
 help[3]:
   Run `quota-axi --provider claude --json` for JSON output
   Run `quota-axi --full` to include account and source-attempt details
   Run `quota-axi auth` to inspect local auth source availability without printing secrets
 ```
 
+`--json` emits the same normalized model as structured JSON instead of TOON:
+
+```sh
+$ quota-axi --provider claude --json
+{
+  "generatedAt": "2026-03-15T16:42:03.000Z",
+  "schemaVersion": 1,
+  "providers": [
+    {
+      "provider": "claude",
+      "label": "Claude",
+      "source": "oauth",
+      "plan": "pro",
+      "windows": [
+        {
+          "id": "five_hour",
+          "label": "session",
+          "kind": "session",
+          "percentUsed": 18,
+          "percentRemaining": 82,
+          "resetsAt": "2026-03-15T21:15:00.000Z"
+        },
+        {
+          "id": "model:fable",
+          "label": "Fable week",
+          "kind": "model",
+          "percentUsed": 29,
+          "percentRemaining": 71,
+          "resetsAt": "2026-03-20T09:30:00.000Z"
+        }
+      ],
+      "state": {
+        "status": "fresh",
+        "stale": false,
+        "sourcesTried": ["oauth"],
+        "refreshedAt": "2026-03-15T16:41:55.000Z"
+      }
+    }
+  ]
+}
+```
+
 ```sh
 $ quota-axi auth
 bin: ~/.npm/_npx/.../quota-axi
@@ -60,18 +105,29 @@ help[1]:
 
 quota-axi requires Node.js 20 or newer.
 
-**npm**
+**Agent skill (recommended)**
+
+Install the skill in the [Agent Skills](https://agentskills.io) format with [`npx skills`](https://github.com/vercel-labs/skills):
 
 ```sh
-npm install -g quota-axi
+npx skills add kunchenguid/quota-axi --skill quota-axi -g
 ```
 
+The skill teaches your agent to run quota-axi through `npx -y quota-axi` on demand, so nothing needs to be installed ahead of time.
+`-g` installs the skill for all projects (e.g. `~/.claude/skills/`); drop it to install for the current project only (`.claude/skills/`).
+
 **Direct use**
 
 ```sh
 npx -y quota-axi
 ```
 
+**npm**
+
+```sh
+npm install -g quota-axi
+```
+
 **From source**
 
 ```sh
@@ -82,6 +138,11 @@ pnpm run build
 pnpm run dev
 ```
 
+## Agent Skill
+
+The npm package includes `skills/quota-axi/SKILL.md`, the same installable skill recommended above.
+It is generated from `src/skill.ts`; update it with `pnpm run build:skill` and verify it with `pnpm run build:skill -- --check`.
+
 ## How It Works
 
 ```
@@ -128,7 +189,7 @@ pnpm run dev
 | `--json`                  | Emit normalized JSON instead of TOON for quota or auth |
 | `--full`                  | Include quota account identity and source attempts     |
 | `--allow-keychain-prompt` | Permit macOS Claude Keychain access that could prompt  |
-| `-h`, `--help`            | Print terse AXI help                                   |
+| `-h`, `--help`            | Print terse [AXI](https://axi.md) help                 |
 | `-v`, `-V`, `--version`   | Print version                                          |
 
 ## Output Model
@@ -170,15 +231,18 @@ Failed providers, stale providers, account identity, and source attempts are not
 ## Development
 
 ```sh
-pnpm install       # Install dependencies
-pnpm run build    # Compile TypeScript to dist/
-pnpm test         # Run fixture parser and CLI tests
-pnpm run dev      # Run the CLI with tsx
+pnpm install                    # Install dependencies
+pnpm run build                  # Compile TypeScript to dist/
+pnpm run lint                   # Run ESLint
+pnpm run format:check           # Check Prettier formatting
+pnpm test                       # Run fixture parser and CLI tests
+pnpm run build:skill -- --check # Verify the generated skill is current
+pnpm run dev                    # Run the CLI with tsx
 ```
 
-## Attribution
+## Contributing
 
-quota-axi is independently implemented from local Baby Menu quota code and public provider behavior references.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the no-mistakes PR workflow, generated-file rules, and release-please conventions.
 
 ## License
 

package/dist/src/skill.d.ts

@@ -0,0 +1,13 @@
+export declare const SKILL_DESCRIPTION: string;
+export declare const SKILL_AUTHOR = "Kun Chen (kunchenguid)";
+export declare const HERMES_TAGS: string[];
+export declare const HERMES_CATEGORY = "observability";
+/**
+ * Render the installable SKILL.md for the quota-axi skill. The body uses the
+ * same shared CLI description and help text, then adds agent-facing workflow
+ * guidance that prefers non-interactive `npx -y quota-axi ...` invocation so
+ * the CLI comes along on demand.
+ *
+ * @returns full SKILL.md contents including YAML frontmatter
+ */
+export declare function createSkillMarkdown(): string;

package/dist/src/skill.js

@@ -0,0 +1,84 @@
+import { DESCRIPTION, TOP_HELP } from "./cli.js";
+// Trigger string Claude Code (and other agents) match against to auto-load the skill.
+// Kept terse and outcome-focused so it fires on "check quota/rate limits" intents.
+export const SKILL_DESCRIPTION = "Report local Claude and Codex quota windows via the quota-axi CLI - remaining " +
+    "percentages, reset times, and provider status read from local auth files, with no " +
+    "routing, recommendation, or provider mutation. Use before deciding whether it is safe " +
+    "to keep spending a provider's quota, when the user asks about usage, rate limits, or " +
+    "remaining quota, or when comparing Claude and Codex headroom.";
+export const SKILL_AUTHOR = "Kun Chen (kunchenguid)";
+// Extended frontmatter read by Nous Research's Hermes Agent harness
+// (https://hermes-agent.nousresearch.com/docs/user-guide/features/skills).
+// Harnesses that don't know these fields (e.g. Claude Code) ignore them.
+export const HERMES_TAGS = ["quota", "rate-limits", "claude", "codex", "cli"];
+export const HERMES_CATEGORY = "observability";
+function yamlDoubleQuote(value) {
+    return JSON.stringify(value);
+}
+/**
+ * Render the installable SKILL.md for the quota-axi skill. The body uses the
+ * same shared CLI description and help text, then adds agent-facing workflow
+ * guidance that prefers non-interactive `npx -y quota-axi ...` invocation so
+ * the CLI comes along on demand.
+ *
+ * @returns full SKILL.md contents including YAML frontmatter
+ */
+export function createSkillMarkdown() {
+    return `---
+name: quota-axi
+description: ${yamlDoubleQuote(SKILL_DESCRIPTION)}
+user-invocable: false
+author: ${SKILL_AUTHOR}
+metadata:
+  hermes:
+    tags: [${HERMES_TAGS.join(", ")}]
+    category: ${HERMES_CATEGORY}
+---
+
+# quota-axi
+
+${DESCRIPTION}
+
+You do not need quota-axi installed globally - invoke it with \`npx -y quota-axi\`.
+
+quota-axi is data only: it never routes, recommends, proxies, intercepts, logs in, imports
+browser cookies, or mutates provider state. It reads local Claude and Codex auth files and
+calls first-party provider usage endpoints; it never launches the Claude CLI, so it cannot
+spend the quota it measures.
+
+## When to use
+
+Use quota-axi whenever you need local quota headroom before deciding whether it is safe to
+keep working on a provider, when the user asks about usage, rate limits, or remaining quota,
+or when comparing Claude and Codex headroom side by side.
+
+## Workflow
+
+1. Run \`npx -y quota-axi\` for compact TOON output covering both providers' quota windows.
+2. Scope to one provider with \`--provider claude\` or \`--provider codex\`.
+3. Pass \`--json\` for the normalized machine-readable model instead of TOON.
+4. Pass \`--full\` to include account identity and per-source attempt details.
+5. Run \`npx -y quota-axi auth\` to check local auth-source availability without printing
+   secret values.
+6. On macOS, Claude Keychain reads are skipped by default; pass \`--allow-keychain-prompt\`
+   to permit a Keychain prompt.
+
+## Usage
+
+\`\`\`
+${TOP_HELP.trimEnd()}
+\`\`\`
+
+## Tips
+
+- Output is TOON-encoded and token-efficient by default; pass \`--json\` only when you need
+  the normalized schema.
+- Exit code 0 means at least one provider returned data (fresh or stale); exit code 1 means
+  every provider failed; exit code 2 means a usage error.
+- Percentages are not comparable across providers - quota-axi never claims one provider's
+  percentage equals another's.
+- The cache at \`~/.cache/quota-axi/quotas.json\` only ever holds normalized non-secret
+  snapshots; nothing quota-axi prints or caches reveals credential values.
+`;
+}
+//# sourceMappingURL=skill.js.map

package/dist/src/skill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill.js","sourceRoot":"","sources":["../../src/skill.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEjD,sFAAsF;AACtF,mFAAmF;AACnF,MAAM,CAAC,MAAM,iBAAiB,GAC5B,gFAAgF;IAChF,oFAAoF;IACpF,wFAAwF;IACxF,uFAAuF;IACvF,+DAA+D,CAAC;AAElE,MAAM,CAAC,MAAM,YAAY,GAAG,wBAAwB,CAAC;AAErD,oEAAoE;AACpE,2EAA2E;AAC3E,yEAAyE;AACzE,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;AAC9E,MAAM,CAAC,MAAM,eAAe,GAAG,eAAe,CAAC;AAE/C,SAAS,eAAe,CAAC,KAAa;IACpC,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO;;eAEM,eAAe,CAAC,iBAAiB,CAAC;;UAEvC,YAAY;;;aAGT,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC;gBACnB,eAAe;;;;;EAK7B,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6BX,QAAQ,CAAC,OAAO,EAAE;;;;;;;;;;;;;CAanB,CAAC;AACF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quota-axi",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "packageManager": "pnpm@11.1.1",
   "description": "AXI CLI that reports local agent-provider quota windows without routing or mutation",
   "type": "module",
@@ -22,6 +22,7 @@
   },
   "files": [
     "dist",
+    "skills/quota-axi",
     "LICENSE",
     "README.md"
   ],
@@ -35,9 +36,13 @@
   },
   "scripts": {
     "build": "tsc",
+    "build:skill": "tsx scripts/build-skill.ts",
     "test": "vitest run",
     "test:watch": "vitest",
     "dev": "tsx bin/quota-axi.ts",
+    "lint": "eslint bin src test scripts",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
     "prepublishOnly": "npm run build"
   },
   "license": "MIT",
@@ -48,10 +53,14 @@
     "@toon-format/toon": "2.1.0"
   },
   "devDependencies": {
+    "@eslint/js": "10.0.1",
     "@types/node": "22.0.0",
+    "eslint": "10.1.0",
+    "globals": "17.7.0",
     "prettier": "3.8.1",
     "tsx": "4.0.0",
     "typescript": "6.0.3",
+    "typescript-eslint": "8.58.0",
     "vitest": "3.0.0"
   }
 }

package/skills/quota-axi/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: quota-axi
+description: "Report local Claude and Codex quota windows via the quota-axi CLI - remaining percentages, reset times, and provider status read from local auth files, with no routing, recommendation, or provider mutation. Use before deciding whether it is safe to keep spending a provider's quota, when the user asks about usage, rate limits, or remaining quota, or when comparing Claude and Codex headroom."
+user-invocable: false
+author: Kun Chen (kunchenguid)
+metadata:
+  hermes:
+    tags: [quota, rate-limits, claude, codex, cli]
+    category: observability
+---
+
+# quota-axi
+
+Report local agent-provider quota windows for routing-aware agents.
+
+You do not need quota-axi installed globally - invoke it with `npx -y quota-axi`.
+
+quota-axi is data only: it never routes, recommends, proxies, intercepts, logs in, imports
+browser cookies, or mutates provider state. It reads local Claude and Codex auth files and
+calls first-party provider usage endpoints; it never launches the Claude CLI, so it cannot
+spend the quota it measures.
+
+## When to use
+
+Use quota-axi whenever you need local quota headroom before deciding whether it is safe to
+keep working on a provider, when the user asks about usage, rate limits, or remaining quota,
+or when comparing Claude and Codex headroom side by side.
+
+## Workflow
+
+1. Run `npx -y quota-axi` for compact TOON output covering both providers' quota windows.
+2. Scope to one provider with `--provider claude` or `--provider codex`.
+3. Pass `--json` for the normalized machine-readable model instead of TOON.
+4. Pass `--full` to include account identity and per-source attempt details.
+5. Run `npx -y quota-axi auth` to check local auth-source availability without printing
+   secret values.
+6. On macOS, Claude Keychain reads are skipped by default; pass `--allow-keychain-prompt`
+   to permit a Keychain prompt.
+
+## Usage
+
+```
+usage: quota-axi [auth] [flags]
+commands[2]:
+  (none)=quota, auth
+flags[6]:
+  --provider <claude,codex>, --json, --full, --allow-keychain-prompt, --help, -v/--version
+examples:
+  quota-axi
+  quota-axi --provider claude
+  quota-axi --json
+  quota-axi --full
+  quota-axi auth
+```
+
+## Tips
+
+- Output is TOON-encoded and token-efficient by default; pass `--json` only when you need
+  the normalized schema.
+- Exit code 0 means at least one provider returned data (fresh or stale); exit code 1 means
+  every provider failed; exit code 2 means a usage error.
+- Percentages are not comparable across providers - quota-axi never claims one provider's
+  percentage equals another's.
+- The cache at `~/.cache/quota-axi/quotas.json` only ever holds normalized non-secret
+  snapshots; nothing quota-axi prints or caches reveals credential values.