agent-usage

A small, bar-agnostic CLI for displaying Codex and Claude session/week limits. It emits plain text, normalized JSON, or Waybar JSON.

Status

This is an MVP. Codex uses the documented Codex app-server API. Claude uses the same undocumented OAuth usage endpoint as Claude Code, so that provider can break when Anthropic changes its client. Linux only (x86_64-linux, aarch64-linux).

The tool reads existing local logins:

• Codex: codex app-server (run codex login first)
• Claude: ~/.claude/.credentials.json (run claude auth login first)

Claude OAuth tokens are never cached. If the access token has expired, agent-usage refreshes it and atomically updates Claude's credential file with mode 0600.

Try it without installing

With flakes enabled, run straight from GitHub:

nix run github:alioguzhan/agent-usage -- status
nix run github:alioguzhan/agent-usage -- status --format json
nix run github:alioguzhan/agent-usage -- status --format waybar

If your Nix does not have flakes enabled yet, add the feature flags:

nix --extra-experimental-features 'nix-command flakes' run github:alioguzhan/agent-usage -- status

Install

Nix profile (any distro with Nix)

nix profile install github:alioguzhan/agent-usage

NixOS (flakes)

Add the input to your system flake:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    agent-usage = {
      url = "github:alioguzhan/agent-usage";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };
}

Then reference the package in your configuration (pass inputs through specialArgs if you have not already):

environment.systemPackages = [
  inputs.agent-usage.packages.${pkgs.system}.default
];

Home Manager (flakes)

Same input as above, then:

home.packages = [
  inputs.agent-usage.packages.${pkgs.system}.default
];

Without Nix

Requires Go 1.24+:

go install github.com/alioguzhan/agent-usage/cmd/agent-usage@latest

The binary lands in $(go env GOPATH)/bin (usually ~/go/bin); make sure that is on your PATH. Or build from a checkout:

git clone https://github.com/alioguzhan/agent-usage
cd agent-usage
go build -o agent-usage ./cmd/agent-usage

Usage

agent-usage status
agent-usage status --format json
agent-usage status --format waybar
agent-usage get codex.week.used_percent
agent-usage refresh --format json

The text and waybar formats print one line per provider as LABEL session%/week%, so a Claude session near its cap stays visible even when the weekly number is higher:

C 1% · A 5%/18%

A provider that exposes only one window prints only that one, and a provider with no windows at all prints ?.

--icon-codex and --icon-claude replace the C and A labels, which is how you get glyphs into a bar without this tool depending on a particular font:

agent-usage status --icon-codex '' --icon-claude '󰚩'

From a checkout without installing, prefix with nix run . --:

nix run . -- status --format json

Results are cached for 60 seconds at $XDG_CACHE_HOME/agent-usage/status.json (or ~/.cache/agent-usage/status.json). Failed providers remain explicit in error; they are never rendered as zero usage.

Waybar

"custom/agent-usage": {
  // Drop the two --icon flags to keep the plain "C" and "A" labels.
  "exec": "agent-usage status --format waybar --icon-codex '' --icon-claude '󰚩'",
  "return-type": "json",
  "interval": 60
}

#custom-agent-usage {
  color: #cdd6f4;
  padding: 0 10px;
}

#custom-agent-usage.warning {
  color: #f9e2af;
}
#custom-agent-usage.critical,
#custom-agent-usage.error {
  color: #f38ba8;
}
#custom-agent-usage.stale {
  opacity: 0.65;
}

Ironbar and other bars

Use the plain text output for a polling script module:

agent-usage status --format text

For separate labels or progress values, query the normalized schema:

agent-usage get claude.session.used_percent
agent-usage get claude.week.used_percent
agent-usage get codex.session.used_percent
agent-usage get codex.week.used_percent

Some accounts do not expose every window. A missing window exits non-zero instead of printing 0.

Develop

nix develop
go test ./...
go run ./cmd/agent-usage status --format json

Before submitting a change:

nix develop -c gofmt -w .
nix develop -c go test ./...
nix build

License

MIT