Commands

This is the reference for the codz command. To install it and see what it is for, start with the Overview.

codz [command] [options]

Running codz with no command is the same as codz status.

codz environment reports this Mac’s system and developer tools. Add --json to print the device environment report.

Commands

Options

--day takes an exact date such as 2026-08-10 and reads it in your Mac’s time zone. It changes only the usage figures; agents, plan meters and ports are always read as they are now.

An option on a command that does not take it is an error:

$ codz agents --all
codz: --all is not supported by 'codz agents'.
Run 'codz help' for usage.

Exit codes

On exit code 2, codz prints one of these to standard error, followed by Run 'codz help' for usage.:

On exit code 3, it prints codz: Token and cost history is part of Codz Pro. Sign in to Codz in Settings ▸ Account. See What needs Pro.

codz status

A complete snapshot of this Mac, in this order:

• the usage day
• how many agents are working, how many sessions are open for Claude, Cursor, Codex and OpenCode, the plan meters, and each working agent with its model and folder
• usage for the day, as codz usage prints it, or the Pro message when usage is locked
• local development ports, as codz ports prints them (every listener with --all)
• Agent memory: what your agents are holding in memory, grouped by kind, with how much could be reclaimed

With --json, status prints the fields of agents, usage and ports together in one object. It does not include agent memory.

codz environment

This Mac’s macOS version, selected developer directory and the versions of Node, npm, Xcode and other developer tools in Codz’s launch environment. The command works while signed out. Each observation includes its check time and result, such as available, not installed, needs setup or timed out. A failed check can retain a separately dated last successful version.

codz environment
codz environment --json

Unchanged tools can reuse cached checks. Use the observation’s own timestamp to judge its age. This is the general environment Codz uses; a project can select different tool versions.

The JSON is a device environment report with schemaVersion, revision, reporter, collectedAt, context, system, tools and coverage. Tool entries include their raw version, status, check time and discovered executable when available. Coverage describes a complete or partial check. The report contains observations from this Mac.

codz agents

The agents working right now in Claude, Cursor, Codex and OpenCode, the sessions open in each, and your plan meters: Claude’s 5-hour, 7-day and extra usage, and Codex’s windows with their reset times. In the JSON, open lists every provider, with 0 for the ones codz does not read sessions from.

{
  "agents": [
    {
      "context_limit": null,
      "context_used": null,
      "cwd": "/Users/you/Projects/storefront",
      "detail": null,
      "id": "claude:0b4f6e2a-5c1d-4f7e-9a3b-8d2c1e6f4a90",
      "model": "claude-haiku-4-5-20251001",
      "name": "Fix the login redirect",
      "platform": "claude",
      "started_at": "2026-09-29T14:02:11.482Z",
      "status": "working"
    }
  ],
  "command": "agents",
  "generated_at": "2026-09-29T14:05:37.918Z",
  "open": {
    "claude": 2,
    "codex": 1,
    "cursor": 0,
    "deepseek": 0,
    "kimi": 0,
    "opencode": 0,
    "openrouter": 0,
    "zai": 0
  },
  "plans": {
    "claude": {
      "extra_percent": null,
      "five_hour_percent": 38,
      "seven_day_percent": 12
    },
    "codex": [
      {
        "account": null,
        "account_id": null,
        "limit_id": "codex",
        "limit_name": null,
        "measured_at": "2026-09-29T13:58:40.000Z",
        "plan_type": "plus",
        "windows": [
          {
            "resets_at": "2026-09-29T17:10:00.000Z",
            "used_percent": 21,
            "window_minutes": 300
          },
          {
            "resets_at": "2026-10-03T09:00:00.000Z",
            "used_percent": 7,
            "window_minutes": 10080
          }
        ]
      }
    ],
    "cursor": {
      "cycle_percent": null,
      "included_spend_cents": null,
      "limit_cents": null,
      "message": null,
      "remaining_cents": null
    }
  },
  "schema_version": 1,
  "working": 1
}

• working is the number of entries in agents. open counts open sessions per provider.
• plans.codex has one entry per Codex login and limit pool; account names the login when there is more than one.
• plans.cursor is read only by status. In agents its fields are always null.

codz usage

Token usage for one local calendar day: an estimated total, then one line per provider with its billable tokens, its estimated cost and where the cost comes from, followed by its top models and their token buckets.

cost_source is null when no cost can be stood behind. Cursor’s tokens come from its account usage API; when that is unavailable, Cursor is listed as Cursor — Context only (account tokens unavailable), with its sessions’ context fill instead of totals.

{
  "command": "usage",
  "day": "2026-09-29",
  "generated_at": "2026-09-29T18:20:04.512Z",
  "schema_version": 1,
  "usage": [
    {
      "billable_total": 1282000,
      "context": [],
      "cost_source": "api_list_price_estimate",
      "estimated_raw_cost_usd": 3.05,
      "fidelity": "billable",
      "models": [
        {
          "estimated_raw_cost_usd": 3.05,
          "model": "gpt-5.5",
          "tokens": {
            "billable_total": 1282000,
            "cache_read": 980000,
            "cache_write": 0,
            "input": 1240000,
            "output": 42000,
            "reasoning": 18000
          }
        }
      ],
      "platform": "codex",
      "tokens": {
        "billable_total": 1282000,
        "cache_read": 980000,
        "cache_write": 0,
        "input": 1240000,
        "output": 42000,
        "reasoning": 18000
      }
    }
  ],
  "usage_locked": false
}

• usage has one entry per provider with activity that day.
• fidelity is billable, or contextOnly for Cursor without account data. A contextOnly entry has no token or cost totals, and context lists the live sessions with context_used and context_limit.
• billable_total follows each provider’s billing. Codex and OpenRouter count cached input inside input and reasoning inside output, so their total is input plus output. Claude, Cursor, OpenCode and DeepSeek report the five buckets separately, so theirs is the sum of all five.
• usage_locked is true when usage is empty because the Mac is not on Pro. You see it from codz status --json.

codz ports

The local development servers on this Mac: the port, the project it belongs to, the process and its PID. Databases, debuggers and system services are left out unless you add --all, which lists every TCP listener. Ports are the same list the Ports page shows.

{
  "command": "ports",
  "generated_at": "2026-09-29T14:06:02.311Z",
  "port_filter": "development",
  "port_scan_error": null,
  "ports": [
    {
      "address": "127.0.0.1",
      "command": "node",
      "cwd": "/Users/you/Projects/storefront",
      "display_command": "Node.js",
      "is_likely_development": true,
      "pid": 48213,
      "port": 3000,
      "project": "storefront",
      "scope": "local",
      "url": "http://localhost:3000"
    }
  ],
  "schema_version": 1
}

• port_filter is development, or all with --all.
• scope is local for a listener only this Mac can reach, or all_interfaces.
• port_scan_error says why the scan failed, when it did.

codz doctor

Checks what codz can read and which provider tools it can find. The same checks run in the app’s setup.

Codz doctor
  [ok] Claude data: Readable · /Users/you/.claude
  [warn] Cursor data: Not found or unreadable · /Users/you/Library/Application Support/Cursor/User/globalStorage/state.vscdb
  [ok] Codex data: Readable · /Users/you/.codex
  [ok] Claude CLI: Installed · /Users/you/.local/bin/claude
  [warn] Cursor CLI: Not installed
  [ok] Codex CLI: Installed · /opt/homebrew/bin/codex
  [ok] Port discovery: Available · /usr/sbin/lsof

Warnings are expected for providers you do not use.

With --json, each check is an object in checks, in the same order:

{
  "check": "Claude data",
  "detail": "Readable",
  "path": "/Users/you/.claude",
  "status": "ok"
}

status is ok or warning, and path is null when there is nothing to point at. The response also carries command, generated_at and schema_version.

“Found, but macOS blocked the read” means the data is there but macOS refused access. codz doctor checks from the terminal you run it in; if it reads your data but the app shows zeros, give the Codz app Full Disk Access. See Troubleshooting.

codz computer

Sets up computer use for agents in a terminal, such as Claude Code and Codex, and for chats in Codz. Computer use runs through the Codz app and its permissions are the app’s, so these commands ask the running app rather than checking the terminal.

Without --provider, status and setup answer for agents in a terminal. With it, they answer for a Codz chat on that agent, such as --provider deepseek.

$ codz computer status
Computer use isn't ready for agents in a terminal yet:
  • Let other apps use computer use: Codz does not let other apps use computer use yet. Turn on Let other apps use computer use in Codz ▸ Settings ▸ Browser & tools (`codz computer setup` opens it), then try again.

Run `codz computer setup` to be taken to each one.

status and setup exit 0 when computer use is ready and 1 when something is still missing or Codz is not open. codz computer setup never turns a switch on for you: it opens the page where you do.

codz version

Prints the version, the build number and the commit it was built from:

codz 0.1.0 (212, 84bcd8839cc6)

{
  "build": "212",
  "command": "version",
  "commit": "84bcd8839cc6",
  "schema_version": 1,
  "version": "0.1.0"
}

Your numbers will differ. Include this line when you contact support.

JSON output

Every command except help takes --json. The response is one JSON object:

• Keys are sorted alphabetically, and a field with no value is null rather than missing.
• Times such as generated_at, started_at and resets_at are ISO 8601 in UTC with fractional seconds.
• Percentages are numbers from 0 to 100, costs are US dollars, and Cursor’s plan amounts are in cents.
• Within schema version 1, fields keep their names and meanings; new fields may be added.

Compatibility form

Codz --dump [--day YYYY-MM-DD]

The original form runs the app binary directly and prints the same snapshot as codz status. It still works, with or without --json.

Scripts

Scripts commands use the running Codz host and the same library and execution service as the Scripts panel. Scripts is available on Free. Read Scripts for creation, repository sharing and review.

list and run default to the current terminal folder. A session selects its actual working folder, including an isolated worktree, and the source project’s personal library. When you provide both folder and session, the folder must match the session’s workspace.

run returns after launch; exit code 0 from the CLI does not mean the script has completed successfully. Inspect status for its outcome and script exit status. Control errors exit 1; invalid arguments exit 2. Unreviewed repository scripts return review_required; terminal scripts without a matching attached GUI return gui_required; a name several scripts share returns ambiguous_script with their IDs; and a script read from the project’s files that you have not run from Codz with its current command returns trust_required.

These commands support the control protocol’s JSON envelope: request ID, owner epoch, revision, and result or error. Mutations accept --request-id and --expected-revision. Raw output is not included in JSON or persisted history.

MCP server

codz computer mcp is a separate server, for computer use; see codz computer.

codz mcp runs Codz as an MCP server on stdin and stdout, for Claude Code, Claude Desktop, Cursor and Codex on this Mac. It takes no options other than --help. Read MCP server for adding it to an app and what it can do.