Skip to content
Get packs

Guide · Agent skill

How to use the CodexBar Usage Checker agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The codexbar skill teaches an AI agent to look up how much of your AI subscription quota you have left, for providers such as Codex/OpenAI, Claude and Kimi. It works by running the CodexBar command-line tool on your Mac. This guide explains what the skill does, how to install it, how to ask for it in plain language, and how to read and troubleshoot its output.

CodexBar Usage Checkersteipete/agent-scripts · MIT

Quick start

  1. 1Install the prerequisites. Install the CodexBar CLI through Homebrew and the CodexBar macOS menu bar app, then log in to each provider you want to check.
  2. 2Download and unzip the skill. Download the ZIP from this page and unzip it so you have the codexbar folder containing SKILL.md.
  3. 3Place the skill folder. Move the folder into ~/.claude/skills/, or into .claude/skills/ inside a project. Alternatively, upload it under Settings → Capabilities → Skills in the Claude apps.
  4. 4Ask in plain language. Ask something like how much Codex or Claude I have left. The agent should run the codexbar command and report percentage left, pace and reset time.
  5. 5Check the output. Confirm the figures match the providers you use. Ignore errors for providers you never configured, and troubleshoot any missing Claude session or zero-output problems.

What the skill makes the agent do

Without this skill, an agent has no reliable way to know how much of your AI subscription you have used. The skill tells the agent to run the codexbar command and report the results: percentage left, pace against expected usage, and reset times, instead of guessing.

The skill is meant for questions such as how much Codex, Claude or Kimi you have left, or which of several accounts still has capacity. It reports quota status taken from provider sessions. It is not a source of official billing records or invoices.

Install the prerequisites first

The skill only wraps other tools, so they must be in place before it does anything. The source requires the CodexBar CLI, installed via Homebrew, and the CodexBar macOS menu bar app.

You also need to be logged in to each provider you want to check. The source says fetches use existing logged-in browser sessions, OAuth caches or CLI credentials, so log in to claude.ai in a supported browser for Claude checks, or rely on the Claude CLI fallback.

Two extras are optional. claude-swap is needed only for multi-account Claude rows. A CodexBar config file is needed only for token-based providers.

  • CodexBar CLI (binary named codexbar, installed via Homebrew)
  • CodexBar macOS menu bar app
  • Logged-in sessions for each provider you check
  • Optional: claude-swap for multi-account Claude rows
  • Optional: a CodexBar config file for token-based providers

Install the skill from the ZIP

Download the ZIP for this skill from this page and unzip it. The skill is a single file named SKILL.md. Place the unzipped skill folder in ~/.claude/skills/ to make it available to your own agent sessions, or in a project's .claude/skills/ folder to limit it to that project.

Alternatively, upload the skill in the Claude apps under Settings → Capabilities → Skills.

  • Personal install: ~/.claude/skills/
  • Project install: .claude/skills/ inside your project
  • Claude apps: Settings → Capabilities → Skills

Ask for it with natural requests

You do not need a special command to trigger the skill. The skill description covers requests about AI subscription usage, rate limits, remaining credits, and questions like how much Codex, Claude or Kimi you have left. Ask in ordinary language and the agent should pick it up.

Name a provider if you only care about one, and say so if you use several accounts.

  • How much Codex do I have left this week?
  • Which of my Claude accounts still has capacity?
  • When do my Kimi limits reset?
  • Check my AI usage and tell me if I am in deficit or in reserve.

Run the commands the skill uses

The default command honors the provider toggles set in the CodexBar app. To check a specific provider, pass --provider. The source lists codex, claude, kimi, gemini, copilot, cursor and openrouter among others, and says to run codexbar --help for the full list. For multiple accounts, the source lists --account <label>, --account-index <n> and --all-accounts, the last of which works with a single provider only.

The source also notes that usage --all-accounts polls each account one after another and can take well over ninety seconds.

codexbar usage codexbar usage --format json codexbar usage --provider codex --json codexbar usage --provider claude --json

Read the output and troubleshoot common problems

Errors for providers you never configured are expected and can be ignored. The agent should report only the providers you actually use. For each one, the useful figures are percentage left, pace against expected usage, and reset time. The pace line, reading 'in deficit' or 'in reserve', is the most actionable part.

If the 'No Claude session key found in browser cookies' error appears, log in to claude.ai in a supported browser or rely on the CLI fallback. If usage --all-accounts produces zero bytes on both stdout and stderr, it may be blocked rather than slow. The CLI runs inside CodexBar.app, and a pending macOS Gatekeeper prompt can stop it with no output, so check the screen for that prompt.

Claude multi-account rows read claude-swap stored backups and can mislead. The active slot may show no stored credentials, and a last seen percentage can keep showing for accounts whose credentials are gone. A plausible percentage does not prove a working credential. Only 'refresh token yes' in the output of claude-swap list --token-status confirms that.

If the CLI is unavailable, the source says the menu bar app serves a dashboard on loopback that pulls /dashboard/v1/snapshot and /cost. The snapshot endpoint requires auth, so open the dashboard in a browser for a quick check. There is no /api/ namespace, so those paths return 404.

  • Ignore errors for providers you never set up
  • 'No Claude session key found in browser cookies': log in to claude.ai or use the CLI fallback
  • Zero output from --all-accounts: check for a macOS Gatekeeper prompt
  • Trust a Claude account only when claude-swap list --token-status shows refresh token yes
claude-swap list --token-status

Safety notes before you use it

This skill runs scripts and uses the network. The source says provider fetches ride on existing sessions and that no secrets are passed on the command line. Even so, the tool depends on logged-in browser sessions and credential stores, so anything running on the same machine can reach those account sessions.

Do not use this skill on shared or unmanaged machines. Only use it where you are comfortable with the agent reading your account status.

  • Runs scripts: yes
  • Uses network: yes
  • Avoid shared or unmanaged computers

What people use it for

  • Checking how much Codex or Claude quota remains before starting a large coding session
  • Finding which of several Claude or Codex accounts still has capacity
  • Seeing when Kimi or other provider limits reset
  • Having an agent read existing CodexBar output and summarise pace in deficit or reserve

Frequently asked questions

What do I need before installing the codexbar skill?

You need the CodexBar CLI, installed via Homebrew, and the CodexBar macOS menu bar app. You also need to be logged in to each provider you want to check, through browser sessions, OAuth caches or CLI credentials. The skill does nothing on its own without these.

Where do I put the skill files?

Download the ZIP from this page and unzip it. Put the folder in ~/.claude/skills/ for personal use, or in .claude/skills/ inside a project. You can also upload it in the Claude apps under Settings → Capabilities → Skills.

Is the codexbar skill free to use?

The source lists the skill under the MIT licence. The source does not state prices for the CodexBar tools, so check their own pages for any cost before relying on them.

Why does it say 'No Claude session key found in browser cookies'?

The Claude check reads a claude.ai session from your browser cookies. Log in to claude.ai in a supported browser, or rely on the Claude CLI fallback, and the check should work.

Why does usage --all-accounts return nothing?

If it produces zero bytes on both stdout and stderr, it may be blocked rather than slow. The CLI runs inside CodexBar.app, and a pending macOS Gatekeeper prompt can stop it with no output, so look for that prompt on screen.

Can this replace my official billing or invoices?

No. The source says the skill reports quota status from provider sessions, not official billing records. Use your provider's billing pages for invoices and real-time billing.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This skill suits developers who use several AI coding subscriptions and want an agent to report remaining limits, pace and reset times on a Mac they control. It is a poor fit if you do not already run CodexBar, use a shared machine, or need official billing data. Pick a different tool if you need invoices or real-time billing records.

Download the skill