Getting Started

Quickstart

Launch lazyagent for the first time and pick an interface.

Once lazyagent is installed, a five-minute tour gets you oriented. For the exhaustive flag reference, jump straight to the CLI reference.

First launch

With no arguments, lazyagent opens the terminal UI and scans every supported agent:

lazyagent

You’ll see a list of sessions on the left and a detail panel on the right. Use ↑/↓ to navigate, tab to switch focus between panels, and q to quit. The full keybinding list lives in Terminal UI.

The three interfaces

lazyagent is a single binary with three interfaces, selectable by flag:

lazyagent              # Terminal UI (default)
lazyagent --gui        # macOS menu bar app (detaches from the terminal)
lazyagent --api        # HTTP API on http://127.0.0.1:7421 (Bearer-token protected)

They’re combinable — on a typical macOS setup:

lazyagent --gui --api

runs the menu bar app and the API side by side from a single process. See Recipes for more combinations.

The first time you launch --api, lazyagent prompts for a passphrase, derives a Bearer token from it (PBKDF2-SHA256), and prints the token to stderr once. Clients can fetch the public salt from /api/auth and derive the same token locally — see HTTP API → Authentication.

Scope to one agent

lazyagent --agent claude    # Claude Code CLI + Desktop
lazyagent --agent codex     # Codex CLI only
lazyagent --agent all       # every agent (default)

Every value for --agent is documented in CLI reference.

Maintenance at a glance

Two subcommands keep chat transcripts under control:

lazyagent prune --days 30        # delete sessions idle for >30 days
lazyagent compact                # shrink session files in place

Both support --dry-run and an interactive agent picker. Full reference:

Next steps