agentctl sessions command reference

agentctl-sessions — command reference

Every command targets the session you are running in. No id, no flags needed. That works because agentctl walks the parent-process chain to find the live Claude process, so it resolves correctly from any shell Claude spawns.

To act on a different session, add -s <id-or-prefix>; ids come from agentctl ls. Add --json to any command to get the resulting annotation back as JSON.

Slash commands

Command	Argument	Notes
/agentctl-name	[name]	No argument → Claude proposes one from the session so far and asks you to confirm
/agentctl-note	[text]	No argument → Claude writes a two-line status summary for you to approve
/agentctl-label	<label...>	No argument → reads the issue key from your git branch
/agentctl-flag	<flag...>	todo, later, blocked
/agentctl-remind	<when>	A nudge
/agentctl-due	<when>	When the work is due
/agentctl-done	—	--undo reopens
/agentctl-hide	—	Out of the default list; --undo unhides
/agentctl-delete	—	Out of every list; --undo restores

CLI

agentctl name   "billing spike"      # --clear removes the override
agentctl note   "waiting on review"  # --append adds a line, --clear removes
agentctl label  RD-12345 catalog     # --remove drops them
agentctl label  --auto               # take the issue key from the current git branch
agentctl flag   todo later           # --remove drops them
agentctl remind 2h                   # --clear drops it
agentctl due    "friday 17:00"       # --clear drops it
agentctl done                        # --undo reopens
agentctl hide                        # out of the default list  (--undo)
agentctl delete                      # out of every list        (--undo)

agentctl annotations                 # everything annotated
agentctl annotations --due           # reminders that fired + anything overdue
agentctl annotations --label RD-12345

agentctl ls --hidden                 # the hidden view
agentctl ls --deleted                # the deleted view
agentctl ls --all                    # everything

Time formats

Accepted by both remind and due:

Form	Example	Means
Relative	30m 2h 3d 1w	From now
Tomorrow	tomorrow	Tomorrow 09:00
Tomorrow + clock	tomorrow 9am tomorrow 17:30
Clock	17:00 9am	Today, or tomorrow if it already passed
ISO	2026-09-01T08:00:00Z	Exact

A bare number is rejected — agentctl remind 45 is a forgotten unit, not the year 2045, and the CLI asks you to be clearer rather than silently scheduling something 19 years out.

Badges in the picker

Mark	Meaning
✓	done
⚑	has flags
✎	has a note
◆	reminder set — red once it has come due
✱	due date set — red once overdue

Keys in the TUI

Highlight a session in agentctl -r, then:

Key	Does
e	edit the name
n	edit the note
l	edit labels — pre-filled with the issue key from that session's branch
f	edit flags
t	set a reminder
u	set a due date
d	toggle done
H	show/hide done sessions
h	hide this session
x	delete this session (press twice to confirm)
v	cycle view: normal → hidden → deleted

Exit codes

Code	Meaning
0	fine
1	nothing matched (e.g. --auto with no issue key in the branch)
2	bad input — an unparseable time, a missing argument, or no session to target