agentctl sessions

agentctl-sessions

Claude Code names a session after your first prompt and records nothing else. A month in you have hundreds of them, named things like Run the shell command 'sleep 20' in the back…, and no way to find the one where you fixed that billing bug.

This plugin gives every session a name you chose, labels linking it to a ticket or repo, notes, flags, a done state, reminders and due dates — and lets Claude fill most of that in for you.

Setup

/plugin marketplace add roypadina/padina-claude-code-plugins
/plugin install agentctl-sessions@padina
brew install --cask roypadina/tap/agentctl     # 0.5.0+ for labels and due dates

The plugin checks for the CLI and offers to install it if it is missing, rather than failing quietly.

The two halves

Claude does it unprompted

When	What happens
Your first real task becomes clear	The session gets a 3–5 word name, set once, silently
Your branch is feature/RD-12345-thing	The session gets labelled RD-12345
You are clearly stopping mid-task	A one-line note is saved on where things stand

It deliberately will not mark a session done, set a reminder, or set a due date on its own. Those are judgement calls and it waits to be asked.

You just ask

"name this session billing spike" "mark this done" "remind me in 2 hours" "this is due Friday" "tag this with RD-123" "what do I need to get back to?"

The skill maps plain language onto the CLI and confirms in one line. See the command reference for every command and its flags.

Labels vs flags — what is the difference?

They are mechanically the same (both are string tags, both searchable), but they are meant for different jobs:

• Labels link a session to something durable: a Jira key, a repo, a component. They keep their case, so RD-12345 reads back exactly as typed. Claude sets these for you from your branch.
• Flags are short status markers you set for yourself: todo, later, blocked. They are lowercased and dash-joined (Follow Up → follow-up) and show as a badge in the picker.

Filtering in the agentctl picker matches both, so typing RD-12345 finds every session on that ticket regardless of which one you used.

Reminders vs due dates

• A reminder is a nudge: "poke me about this in 2 hours."
• A due date is when the work is actually due. Once it passes the session shows as overdue.

Neither pops up a notification. A due reminder shows as a red marker in the agentctl picker and is mentioned at the start of your next session. Set expectations accordingly.

The SessionStart hook

One hook, running agentctl hook session-start, on startup and resume.

On a named session it hands Claude the name, labels, note and due state — so a resumed session knows what it is and what is overdue. On an unnamed one it asks Claude to name it once your first task is clear, and points out any issue key it found in your branch. It also mentions reminders that came due on other sessions.

It prints a handful of lines, once per session start. If agentctl is not on PATH the hook is skipped entirely.

Hiding and deleting

Two ways to get a session out of your way. Neither touches the Claude Code transcript, removes anything from ~/.claude, or stops the session resuming if you address it by id — they are listing preferences stored alongside the other annotations.

	Where it still appears	Undo
Hidden	agentctl ls --hidden, v in the TUI, the GUI's view menu	agentctl hide --undo
Deleted	agentctl ls --deleted only	agentctl delete --undo

Deleted outranks hidden — a session marked both shows only in the deleted view.

In the TUI, h hides the highlighted session and x deletes it (twice, since it drops out of every view). In the GUI there are Hide and Delete buttons in the details pane, and a view menu in the toolbar.

Claude will never hide or delete a session unless you ask it to.

Where the data lives

~/.config/agentctl/annotations/<session-id>.json

One small file per session, written atomically (temp file + rename), so several Claude sessions annotating themselves at once cannot clobber each other. It lives outside ~/.claude on purpose: nothing this plugin does can corrupt a transcript.

Why renaming does not touch the transcript

Claude Code stores a session's title as custom-title lines inside its JSONL, and it is tempting to rename a session by appending one. Don't. Claude Code caches the title in memory and re-flushes it after almost every turn, so an externally-appended rename is silently reverted on the next turn of a live session — no error, no conflict. agentctl keeps the name in its own store, where it wins over the transcript title and survives any number of renames.

Uninstalling

/plugin uninstall agentctl-sessions@padina

Your annotations stay in ~/.config/agentctl. brew uninstall --cask agentctl leaves them too; only brew uninstall --zap --cask agentctl deletes them.