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 and weekly rate-limit usage with a pace indicator

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 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, and limits for their flag tables.

search

search runs full-text search over local agent transcripts (Claude, Codex, pi, Amp) using an incremental SQLite FTS5 index under the user cache directory. Cursor and OpenCode 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. Piped output stays non-interactive.

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

limits

limits prints a one-shot snapshot of the 5-hour and weekly rate-limit windows for Claude Code and Codex, with a pace indicator that compares actual consumption to a perfectly linear pace (underutilizing / on track / overutilizing).

lazyagent limits                 # both agents
lazyagent limits --agent claude  # only Claude Code
lazyagent limits --agent codex   # only Codex

Claude data comes from /api/oauth/usage on api.anthropic.com — the same undocumented endpoint Claude Code’s /status calls. Codex data is read from the latest rollout JSONL under ~/.codex/sessions/ (no network call).

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