Recipes - Docs - lazyagent

Concrete, copy-pasteable recipes for the workflows people actually run.

Daily driver setup (macOS)

You want the menu bar app always running, the API available for a mobile companion, and the TUI available in the terminal when you need a denser view.

# In a LaunchAgent or at terminal startup — detaches immediately
lazyagent --gui --api

# When you want a denser session list in the terminal:
lazyagent --tui

The tray and API share the same engine, so the TUI sees the same data they do. Quitting the TUI doesn’t touch the tray or API. See macOS GUI and HTTP API.

Monitor only one agent

Scope the scan to a single agent with --agent:

lazyagent --agent claude   # Claude Code CLI and Desktop
lazyagent --agent codex    # Codex CLI only

To permanently hide an agent without passing --agent every time, set it to false in the agents config block.

Mobile companion on the same Wi-Fi

# On your laptop
lazyagent --api --host 0.0.0.0:7421

# On your phone (same network)
# Connect to http://<laptop-ip>:7421/api/events

The API exposes an SSE stream that updates in real time. See the React Native example for a full client snippet.

The mobile app fetches the public salt from /api/auth, then derives the bearer token from the same passphrase you configured on the laptop, so pairing is just “type the passphrase once”. Traffic is plain HTTP — keep it on a trusted network or front it with HTTPS.

Check rate-limit usage before a long run

Before starting an agent task that might burn through quota, snapshot where you stand on the 5-hour and weekly windows:

lazyagent limits                 # both Claude Code and Codex
lazyagent limits --agent claude  # just Claude

The Pace line tells you whether you’re consuming faster than linear (overutilizing), in line, or slower (underutilizing). If Claude reports overutilizing on the 5-hour window with hours still to go, that’s a strong hint to defer the run or fan it out across days.

Claude data comes from an undocumented endpoint Anthropic uses for /status — the command is on-demand only and never polled. Codex data is read locally from the latest session rollout, no network call. See limits for the full disclaimer.

Quick status check from the shell

When you just want to see active sessions without opening a full UI:

# Print the bearer token explicitly, then reuse it.
TOKEN=$(lazyagent passphrase --show)

curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:7421/api/stats
# → {"total_sessions":5,"active_sessions":2,"window_minutes":30}

curl -s -H "Authorization: Bearer $TOKEN" \
  'http://127.0.0.1:7421/api/sessions?filter=active' \
  | jq -r '.[] | "\(.activity)\t\(.short_name)"'
# → thinking  …/projects/myapp
# → writing   …/projects/worker

Requires that lazyagent --api is running somewhere on your machine and that you’ve configured an API passphrase. See HTTP API → Authentication.

Find sessions waiting for your input

# TUI: press `f` until the filter lands on "waiting"

# API:
curl -s -H "Authorization: Bearer $TOKEN" \
  'http://127.0.0.1:7421/api/sessions?filter=waiting' \
  | jq '[.[].short_name]'

Pair with notifications: true in the config so the GUI nudges you proactively.

Weekly tidy-up

The Maintenance commands shine when run on a cadence. A safe weekly routine:

# 1. Preview what's stale — projects you haven't touched in a month
lazyagent prune --days 30 --orphaned --dry-run

# 2. If you like what you see, actually delete
lazyagent prune --days 30 --orphaned

# 3. Shrink whatever's left but still bulky (>512 KiB)
lazyagent compact --days 14 --dry-run

# 4. Commit to it
lazyagent compact --days 14

Each step asks for confirmation before mutating anything. Compact writes .bak sidecars by default — if a specific rewrite causes trouble, mv session.jsonl.bak session.jsonl rolls it back.

Reclaim disk space aggressively

For maximum savings on Claude transcripts with large embedded images and tool snapshots:

lazyagent compact \
  --agent claude \
  --min-size-kb 100 \
  --threshold-kb 5 \
  --dry-run

Then drop --dry-run. Typical savings on a full ~/.claude/projects/ tree are 60–80% on the biggest transcripts.

Purge a single project

You deleted ~/projects/abandoned-app and want every session associated with it gone:

# Preview
lazyagent prune --orphaned --dry-run-verbose | grep abandoned-app

# Commit
lazyagent prune --orphaned --agent claude,codex,pi

--orphaned catches anything whose CWD no longer resolves — the exact case here.

Running in a scheduled task

cron, launchd, or a shell loop can automate maintenance. Always include --yes to skip the interactive disclaimer:

# In crontab: compact Claude sessions every Sunday at 03:00
0 3 * * 0  /usr/local/bin/lazyagent compact --agent claude --days 7 --yes >> ~/.local/state/lazyagent-compact.log 2>&1

Script-friendly invariants:

Exit code 0 on success (including “nothing to do”), 1 on partial failure, 2 on invalid flags — pair with set -e safely.
stderr carries warnings and failures; stdout carries the summary tables.
--agent is accepted, so non-interactive use never has to deal with the picker.

Rebuilding session display names

You renamed a session via the TUI and regret it:

# TUI / GUI: press `r` on the session, submit empty → resets to default
# API:
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:7421/api/sessions/<session-id>/name

Session names live in ~/.config/lazyagent/session-names.json and are shared across all interfaces in real time.

Dev loop on lazyagent itself

git clone https://github.com/illegalstudio/lazyagent
cd lazyagent
make tui                           # builds the TUI-only binary
./lazyagent --demo                 # quick sanity check with fake data
./lazyagent --tui --api            # real data + API

Full build instructions (including the Svelte frontend for the tray) live in Development.