Commands

Commands

There's one command — agentctl — (no short alias). It opens the menu in New mode; -r/--resume opens it in Resume mode.

agentctl          # New-session menu (default)
agentctl -r       # Resume menu
agentctl --resume # same as -r
agentctl new            # same as bare agentctl
agentctl resume         # same as -r (with an id: resume that session)

Inside the menu, ⇥ (Tab) switches between New and Resume at any time, so you can start in either and flip.

Want per-tool shortcuts? Add your own shell aliases. The tool you launch is chosen in-menu (⇧⇥ cycles it).

Non-interactive subcommands

agentctl ls [--cwd <path>] [--active] [--json] [--sort updated|started|name] [--limit N]
            [--hidden | --deleted | --all] [--tool | --interactive]
agentctl peek <id> [--full] [--head N --tail N]   # print a transcript
agentctl recap <id> [--refresh]                   # AI summary of a session (cached)
agentctl resume <id> [--yes] [--cwd <override>] [--profile <email|name|path>]   # resume by id (prefix ≥ 4 chars)
agentctl profiles [--json]                        # list Claude accounts (for --profile)
agentctl path <id>                                # print the .jsonl path
agentctl config --setup | --edit | --path         # manage the shared config
agentctl name|note|label|flag|remind|due|done [-s <id>] …  # annotate a session (see `agentctl --help`)
agentctl hide|delete <id>… [--undo]               # tidy the list; transcripts are never touched
agentctl annotations [--due]                      # everything you annotated
agentctl --help                                   # full usage

<id> accepts a unique prefix (≥ 4 characters). resume launches claude --resume <id> --dangerously-skip-permissions in the session's working directory.

recap — what was this session doing?

agentctl recap <id> prints a short AI summary of a session (what it was working on, key decisions, current state, open follow-ups) so you can decide whether to resume it without reading the whole transcript. It feeds a token-capped head+tail excerpt to claude -p with the cheap/fast haiku model and caches the result to ~/.config/agentctl/recaps/<id>.md — re-running (or pressing r in the menu) is then instant. --refresh regenerates and overwrites the cache.

Env	Default	What
AGENTCTL_RECAP_MODEL	haiku	Model passed to claude -p --model …
AGENTCTL_CLAUDE_BIN	claude	The agent binary recap shells out to

Keyboard — New

Key	Action
↑ / ↓	Move selection
type	Fuzzy-filter the project dirs
↵	Launch the selected tool in the dir
⇥	Switch to Resume
⇧⇥	Cycle the tool (e.g. Claude ⇄ Codex)
^n	New directory (then launch)
^t	Open in tmux
^p	git pull first, then launch
^f	Reveal in Finder
^-key	Open a configured IDE, then launch
?	Full keymap overlay
esc	Clear the filter / quit

Keyboard — Resume

Key	Action
↑ / ↓ (or j / k)	Move selection
↵	Resume the selected session
p	Peek the transcript (scroll: ↑/↓, g/G, pgup/pgdn)
r	Recap the highlighted session (claude -p · haiku, cached)
/	Fuzzy-filter the list
s	Full-text search across all transcripts
^r	Refresh sessions from disk
⇥	Switch to New
?	Help overlay
q	Quit

Highlighting a row shows a details pane with its full metadata (id, status, branch, started, last used, cwd) plus the recap — no need to open the session first.

A ⚠ marks a session whose working directory couldn't be decoded with confidence — press ↵ twice to resume anyway, or use agentctl resume <id> --cwd <path>. See Architecture → cwd decoding.