Loombar
Download ↗
Docs/CLI

LOOMBAR CLI

One local interface for every agent on your Mac.

The Loombar CLI exposes the same Claude, Cursor, Codex, usage, and localhost signals as the native app. Its default output is made for humans; --json gives scripts a versioned contract.

Start here
loombar status
Getting started

Requirements

Loombar CLI ships inside the macOS app. It requires macOS 14 or newer and works with any combination of Claude, Cursor, and Codex installed on the same Mac.

No provider API keys.

The CLI reads local provider data. Cursor account usage is requested with the signed-in Cursor app session; if that request fails, Loombar reports context-only fidelity instead of synthesizing tokens.

Getting started

Installation

Install the Loombar app first. The repository installer creates the lowercase command automatically and leaves any existing command at the destination untouched.

From the Loombar repository
npm run install:macos

Link a downloaded app manually

If you downloaded the app, create a command that points at the executable inside the bundle. Adjust the app path if you keep Loombar in/Applications instead of ~/Applications.

Create ~/.local/bin/loombar
mkdir -p "$HOME/.local/bin"
ln -s "$HOME/Applications/Loombar.app/Contents/MacOS/Loombar" \
  "$HOME/.local/bin/loombar"

Make sure ~/.local/bin is in your PATH, then verify the installation:

Verify
loombar version
loombar doctor
Getting started

Quick start

Start with the complete snapshot, then narrow the question when you need faster or more focused output.

Common workflow
# Everything Loombar can see right now
loombar status

# Working agents as JSON
loombar agents --json

# Yesterday's billable usage
loombar usage --day 2026-08-09

# Project-like development ports
loombar ports
CommandAnswersOptions
loombar statusFull snapshot--day, --all, --json
loombar agentsLive provider activity--json
loombar usageOne local calendar day--day, --json
loombar portsLocal TCP listeners--all, --json
loombar doctorData and CLI diagnostics--json
loombar versionInstalled Loombar version--json
loombar statusThe complete local snapshot

Collects working agents, provider open counts, plan meters, usage for one day, and local development ports. Running loombar with no command is equivalent to loombar status.

Examples
loombar status
loombar status --day 2026-08-10
loombar status --all --json
--day YYYY-MM-DD

Use a specific local calendar day for usage.

--all

Include every local listener instead of development-like ports only.

--json

Return the full schema-versioned snapshot.

loombar agentsLive Claude, Cursor, and Codex activity

Shows sessions with a current working signal. Loombar does not treat every open provider window as active work; open counts are reported separately.

Examples
loombar agents
loombar agents --json

The JSON form includes project path, model, working state, timestamps, and Cursor context values when available.

loombar usageToken usage for one local day

Claude and Codex totals come from local billable history. Cursor totals come from Cursor account usage events. Context fill remains separate from token consumption.

Examples
loombar usage
loombar usage --day 2026-08-09
loombar usage --json
Fidelity is part of the result.

A Cursor slice marked contextOnly means account tokens were unavailable. It is not a zero-token day.

loombar portsProject-aware localhost discovery

By default, Loombar filters the current user's TCP listeners down to likely development servers. Use --all to include databases, infrastructure, and unrelated listeners.

Examples
loombar ports
loombar ports --all
loombar ports --json
loombar doctorA safe local setup check

Checks whether Claude, Cursor, and Codex data sources are readable, whether their companion CLIs are installed, and whether macOS port discovery is available.

Examples
loombar doctor
loombar doctor --json

Warnings are expected for providers you do not use.

Output

JSON schema

Add --json to any data command. Every response includesschema_version, command, and a generated timestamp. Consumers should branch on the schema version before relying on fields.

loombar agents --json
{
  "schema_version": 1,
  "command": "agents",
  "generated_at": "2026-08-10T08:05:35.817Z",
  "working": 1,
  "open": {
    "claude": 2,
    "cursor": 1,
    "codex": 1
  },
  "agents": [
    {
      "id": "codex:019f…",
      "platform": "codex",
      "name": "Build CLI docs",
      "status": "working",
      "cwd": "/Users/example/loombar",
      "model": "gpt-5.6"
    }
  ]
}

Pipe into other tools

Automation examples
loombar agents --json | jq '.working'
loombar ports --json | jq -r '.ports[].url'
loombar usage --json | jq '.usage[] | {platform, billable_total, fidelity}'
Output

Exit codes

0

The command completed and emitted its result.

2

The command or one of its options was invalid.

Upstream unavailability is represented in the payload rather than turned into a fabricated total. For example, a failed Cursor account request can still return valid local context data.

Output

Data sources

C

Claude

Live sessions, plan meters, and local billable JSONL history.

↗

Cursor

Composer and worker state, context fill, and signed-in account usage events.

⌁

Codex

Live thread state plus local rollout JSONL for billable history.

:

Ports

TCP listeners owned by the current macOS user, discovered with lsof.

Help

Troubleshooting

Everything is zero or missing

Run loombar doctor. If provider files exist but are unreadable, grant Full Disk Access to Loombar or the terminal application that launches the CLI, then open a new terminal session.

loombar: command not found

Confirm that ~/.local/bin is in PATH. You can also run the bundled executable directly:

Direct invocation
"$HOME/Applications/Loombar.app/Contents/MacOS/Loombar" doctor

Cursor has context but no tokens

Make sure the Cursor app is signed in. Loombar intentionally keeps context fill visible while marking account usage unavailable; it never promotes context tokens into a billable total.

Help

Legacy --dump

Existing diagnostics that invoke the app binary directly remain supported. The legacy form maps to status and accepts the same day selector.

Compatibility
Loombar --dump
Loombar --dump --day 2026-08-10
Loombar --dump --json