CLI reference

This page documents the root lazyagent command — the one you run to monitor agents. Maintenance and search subcommands live alongside it:

• lazyagent prune — delete old or orphaned chat files
• lazyagent compact — truncate bulky payloads in place
• lazyagent search — search transcript-file agents with highlighted snippets
• lazyagent limits — show 5-hour, weekly, and monthly usage summary; add --detailed for pace

Synopsis

lazyagent [--tui] [--gui] [--api] [--host ADDR]
          [--agent NAME] [--demo]
          [--version] [--help]

No flag at all is the most common invocation — it opens the TUI with every supported agent enabled.

Flags

--tui

Explicitly open the terminal UI. Omitting it is the same as passing it unless another mode is specified:

lazyagent                    # implicit --tui
lazyagent --tui              # explicit, same result
lazyagent --api              # API only, no TUI
lazyagent --tui --api        # TUI in foreground, API in background

See Terminal UI for keybindings.

--gui

Launch the macOS menu bar app. The process detaches from your terminal immediately — the shell prompt returns, and the app appears in the menu bar.

lazyagent --gui              # menu bar only (detached)
lazyagent --gui --api        # menu bar + API in foreground
lazyagent --tui --gui --api  # everything (TUI foreground, tray and API in background)

On non-macOS systems --gui prints an error. See macOS GUI.

--api

Start the HTTP API server.

lazyagent --api              # default bind: 127.0.0.1:7421
lazyagent --api --host :8080 # custom port, localhost only
lazyagent --api --host 0.0.0.0:7421   # expose on the network

On the very first interactive run, --api prompts for a passphrase, saves it to ~/.config/lazyagent/config.json, and prints the derived bearer token to stderr once. On subsequent runs it does not print the token; use lazyagent passphrase --show when you explicitly need it. Set LAZYAGENT_API_PASSPHRASE in the environment to override the configured value (useful for CI / launchd).

If the chosen port is busy, the default bind falls back across 7421–7431; when --host is set, there is no fallback. Full reference: HTTP API.

--host ADDR

Override the API bind address. Accepts any Go net.Listen address:

Ignored without --api.

--agent NAME

Restrict monitoring to one agent. Valid values:

lazyagent --agent claude     # only Claude
lazyagent --agent codex      # only Codex
lazyagent --agent grok       # only Grok
lazyagent --agent kilo       # only Kilo
lazyagent --agent kimi       # only Kimi Code
lazyagent --agent all        # default — every agent

To disable agents permanently (rather than per-invocation), flip them in the agents map of your config.

--demo

Replace real session discovery with a curated fake dataset — useful for screenshots, demos, or debugging the UI without cluttering your actual agent history.

lazyagent --demo             # fake TUI
lazyagent --demo --gui       # fake tray app

Combinable with any interface flag.

--version

lazyagent --version

Prints the running version and, if a newer release is available on GitHub, a hint to update.

--help

lazyagent --help

Prints the full usage text, including short keybinding reference.

Subcommand dispatch

When the first positional argument is prune, compact, search, limits, or passphrase, lazyagent switches into subcommand mode — root-level flags are ignored and the subcommand parses its own set.

lazyagent prune --days 30          # prune subcommand
lazyagent compact --agent claude   # compact subcommand
lazyagent search --agent codex api # search subcommand
lazyagent limits --agent claude    # limits subcommand
lazyagent passphrase               # rotate the API passphrase
lazyagent --agent claude prune     # ❌ wrong: prune is not a flag value

See prune, compact, search, and limits for their flag tables.

search

search runs full-text search over local agent transcripts (Claude, Codex, pi, Amp, Grok, Kimi) using an incremental SQLite FTS5 index under the user cache directory. Cursor, OpenCode, and Kilo are excluded because their history lives in third-party SQLite databases.

lazyagent search "race condition"
lazyagent search --agent codex "parser"
lazyagent search --reindex "config"

After printing results in an interactive terminal, search prompts for a result number; entering one opens that chat via the originating agent’s resume command when lazyagent knows one. Grok sessions are searchable but not directly resumable, because Grok CLI does not expose a resume command. Piped output stays non-interactive.

Full reference, including the index location, ranking, resume commands, and Grok caveat: search.

limits

limits prints a one-shot summary table of the rate-limit / billing windows exposed by Claude Code, Codex, Grok, Kimi, and Cursor. The default table labels each 5-hour and weekly/global cell as used and exp, where exp is the linear pace for elapsed window time; --detailed prints the full per-window report with reset times and the pace indicator (underutilizing / on track / overutilizing). Claude and Codex each expose a 5-hour and a 7-day window; Grok exposes a single monthly credit window; Kimi exposes the windows returned by Kimi Code CLI’s /status endpoint; Cursor exposes a single monthly window tracking its usage-based (API) spend against the plan’s included credit.

lazyagent limits                 # summary table for all supported limits providers
lazyagent limits --detailed      # detailed report with bars, reset times, and pace
lazyagent limits --agent claude  # only Claude Code
lazyagent limits --agent codex   # only Codex
lazyagent limits --agent grok    # only Grok
lazyagent limits --agent kimi    # only Kimi Code
lazyagent limits --agent cursor  # only Cursor (usage-based API pool)

Claude data comes from /api/oauth/usage on api.anthropic.com — the same undocumented endpoint Claude Code’s /status calls. Codex data comes from /backend-api/wham/usage on chatgpt.com — the same endpoint the Codex CLI’s TUI polls for its rate-limit display. Grok data comes from /v1/billing on cli-chat-proxy.grok.com — the same undocumented endpoint Grok CLI’s /usage show slash command calls. Kimi data comes from /coding/v1/usages on api.kimi.com, the endpoint Kimi Code CLI’s /status slash command calls. Cursor data comes from /api/dashboard/get-aggregated-usage-events on cursor.com — the same endpoint the Cursor dashboard’s usage summary uses — read with the session token from Cursor’s local state.vscdb; only the usage-based (API) pool is reported, not the unlimited Auto/Composer pool.

Full reference, including disclaimers and token-resolution order: limits.

passphrase

passphrase sets or rotates the passphrase that protects the HTTP API. It runs without starting the server, so you can change credentials at any time and let any future lazyagent --api pick up the new value.

lazyagent passphrase             # interactive prompt and save
lazyagent passphrase --show      # print the bearer token for the current passphrase

passphrase (no flags) always prompts (double-entry confirmation), even if a passphrase is already configured — it’s a rotation, not a setup. --show derives the token from the env var if LAZYAGENT_API_PASSPHRASE is set, otherwise from the configured value, without prompting or changing the passphrase.

--show writes the raw token to stdout (single line, no prefix) so it can be captured in a pipe: TOKEN=$(lazyagent passphrase --show). Diagnostics (passphrase source, missing-config hints) go to stderr. Other invocations do not print the token.

Restart any running lazyagent --api after rotating: the server reads the passphrase at startup, so it keeps using the old token until restarted.

Common invocations

# Terminal UI, all agents (the default)
lazyagent

# Terminal UI but only Claude
lazyagent --agent claude

# Menu bar app only
lazyagent --gui

# Menu bar app + HTTP API (ideal daily-driver combo on macOS)
lazyagent --gui --api

# HTTP API exposed on the LAN for a mobile client
lazyagent --api --host 0.0.0.0:7421

# Everything at once
lazyagent --tui --gui --api

# Demo mode for screenshots
lazyagent --demo --gui

# Search chat history
lazyagent search "api server"

Exit codes

The maintenance subcommands define their own exit codes; see their respective pages.

Environment variables