Skip to content
Documentation menu

Getting started

OpenLimiter is a quota meter for the AI subscriptions you already pay for. It runs on your machine, reads what your tools already wrote there, and hands your coding agents a bounded picture of what budget is left.

What you need

  • Node 24 or newer, which the workspace declares in its engines field.
  • pnpm 9.15.0, the package manager the repository pins.
  • A git clone of the repository. OpenLimiter is not published to npm yet, so there is no global openlimiter command to install.

Everything runs locally. No account is created, no key is required to start, and no request leaves your machine during any of the steps below.

Install the workspace

Run these in order on a clean clone.

terminal
pnpm install
pnpm build
pnpm typecheck
pnpm test
pnpm openlimiter demo

The build has to run before the type check, because each package resolves its neighbours through the declaration files the build produces.

pnpm openlimiter is a thin wrapper around the built entry point. Anywhere these pages write openlimiter <command>, you can run either of these from the repository root.

pnpm openlimiter <command>
node packages/cli/dist/bin.js <command>

openlimiter demo renders synthetic fixtures. It proves the binary works without touching any real account, and every number it prints is invented.

Give it something to meter

OpenLimiter never contacts a provider in this release. It parses data that something else already put in front of it. Until one of the ingestion paths runs, every command honestly reports unknown.

The path that needs no extra work is the Claude Code statusline. Claude Code runs your statusline command on every render and writes a JSON object describing the current session to that command's standard input. When that object carries a rate limit block, OpenLimiter validates it, caches it, and renders the fresh numbers in the same call.

terminal
node packages/cli/dist/bin.js statusline < session.json
OpenLimiter NEAR_CAP CLAUDE 87.5% UNKNOWN OPENROUTER,CODEX,ANTIGRAVITY,OPENCODE,MANUAL

Not every Claude Code version sends rate limit fields. If yours does not, this path stays quiet and the two manual paths still work. The ingestion page covers all three.

Wire Claude Code

Add this to your Claude Code settings.json, using the absolute path to your clone. Forward slashes work on every platform.

settings.json
{
  "statusLine": {
    "type": "command",
    "command": "node /absolute/path/to/openlimiter/packages/cli/dist/bin.js statusline"
  },
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node /absolute/path/to/openlimiter/packages/cli/dist/bin.js hook"
          }
        ]
      }
    ]
  }
}

Where next

A reasonable reading order

  1. 1Why OpenLimiter for the problem this solves.
  2. 2Supported providers for what each connector reads and how fragile it is.
  3. 3Agent context for exactly what reaches your agent.
  4. 4CLI reference for every command and exit code.