# Agent sessions A popup that finds any past Claude Code or Codex session, across every project, by its title, folder or what was said in it. It previews the selected session's last exchanges and brings it back in a new tab in its own folder, forks it into a new session, or goes to it when it is still running in a Herdr terminal. It can also paste an exchange from it into the prompt of the agent you're working with, unsent, so you can carry context from one session to another. ![Agent sessions](preview.png) ## What you see - **The popup**, 920 by 560px, 40px from the top of the window, on `popover`, with 14px padding and 10px gaps. - A heading row. On the left, "Sessions" (or "Search transcripts" in text search) in 15px semibold `foreground`, then "N live" in 12px `dim` when any session is running. On the right, "shown of total" in 12px `muted`. - A 36px input with 9px corners and an `accent` border on `raised`, with a 14px Lucide icon (`search`, or `text-search` in text search) in `muted`. Placeholder: `Find a session… /text searches what was said`. - The body, side by side: - **The list**, 450px wide. Rows are 50px tall with 7px corners and 2px between them; the selected row is `selected` and hovered rows are `hover`. Each row has: - the agent's 16px mark on the left (Herdr's own `icons/claude.svg` or `icons/codex.svg`, drawn with `image()`) - the title or first prompt in 13px `foreground`, truncated, over the project folder's name and branch in 12px `dim` (`acme-api · feat/rate-limits`). The home folder shows as `~`. - on the right, how long ago in 12px `muted` (`now`, `27m`, `5h`, `4d`, `Oct 12`), over the turn count in 11px `dim` (`4 turns`) - a running session shows a 7px dot in its status color (`working`, `blocked`, `done`, `idle`) and the word `live` in `foreground` instead of the age - In text search, the second line is the project, then the text that matched, in `muted`. The list shows as many rows as fit its measured height and keeps the selection in the middle. - **The preview** fills the rest, with a 1px `border` line on its left and 14px padding. - The agent's 18px mark and the headline in 14px semibold. When the headline isn't the first prompt word for word, the prompt follows in 12px `muted` (up to 160 characters). - Meta lines, each a 13px Lucide icon in `dim` and 12px text: `folder` and the folder (home as `~`), `git-branch` and the branch, `clock` and `Claude Code · 4m ago · 4 turns`, `hash` and the session id in `dim`. A running session adds an 8px status dot and `Running in / · `. - A row of 24px buttons with 6px corners, a 1px `border` outline and 12px text, `hover` on hover: **Resume** (**Show** for a running session), **Fork**, **Send to ** (named after the program in the terminal the popup opened over, e.g. `Send to Claude Code`; `dim` and inert when there is none or nothing to preview) and **Copy id**. - A 1px `border` divider, then the last exchanges, oldest first: a 11px semibold label (`YOU` in `accent`, the agent's name in caps in `muted`) with a small **Send** link on the right (11px `dim`, `accent` on `hover` when hovered), over the text in 12.5px (`foreground` for you, `muted` for the agent). Your messages are cut at 280 characters and the agent's at 420 on screen; Send uses the whole message. - A footer in 12px `dim`: `Enter resume · Shift+Enter split · Ctrl+O fork · Ctrl+S send last exchange · ⌘/Ctrl+Enter copy id · Tab search transcripts`. ## How it behaves - `ctrl-b h` opens the popup (`mod.open:sessions`); pressing it again closes it. - The list is every session, newest first by file time. It appears at once from the index saved last time, then updates with any transcript that changed since. - Typing filters the list. Every word must appear in the title, the first prompt, the folder path, the branch or the agent's name (`codex` lists Codex sessions). - `/words` searches inside every transcript, case-insensitively, 180ms after typing stops. Only what was said counts: your typed prompts and the agent's text, not tool calls, tool output, hook output or request logs. Each session shows the first match, with about 60 characters before it and 100 after. Tab switches between filtering and text search. - Up/Down, Ctrl+N/P, Ctrl+J/K (from `keys.json`) and the scroll wheel move the selection, which wraps around. Page Up/Down move a page. A click selects a row; clicking the selected row acts on it, with the same modifiers as Enter. - The preview loads 90ms after the selection rests, from the last 256 KB of the transcript. When an agent wrote several messages in a row, only its last one in that turn is shown. When the tail has none of your prompts, the first prompt from the index stands in. - **Enter** on a session that isn't running opens a new tab named after it (32 characters at most) in the session's folder, running `claude --resume ` or `codex resume `. **Shift+Enter** opens it in a split to the right of the focused pane instead. **Cmd+Enter** (Ctrl+Enter elsewhere) copies the session id and shows a toast. - If the session's folder no longer exists (a removed worktree), Enter shows an error toast naming the folder and the resume command, and starts nothing. - **Enter or Shift+Enter on a live session** runs `agent.focus` on its terminal, switching to its space and tab, instead of starting a second copy. The Resume button reads **Show** then. - **Fork** (Ctrl+O or the Fork button) opens a new tab named `fork: ` in the session's folder running `claude --resume --fork-session` or `codex fork `. The fork gets a new session id and the original transcript is left as it was. A running session can be forked too. - **Send** pastes into the terminal that had focus when the popup opened, and closes the popup there. Ctrl+S (or the Send to button) sends the last exchange: your last prompt in the preview and the agent's answer to it. A message's own Send link sends just that message. The text is: ``` From a past session (, ): You: Claude Code: ``` It arrives as one paste and is not submitted, so you can add to it and press Enter. Opening the popup over a mod pane leaves Send inert. - The preview leaves out replies to messages a tool or another session injected as "user" messages, so an exchange is always your prompt and the answer to it. - Live marks refresh every 4 seconds while the popup is open. Agent statuses (working, blocked, done, idle) show as the dot's color, in the list and the preview. - Escape closes the popup. - **Titles.** The headline is, in order: the title Claude Code generated (`ai-title`), a title you gave the session (`custom-title`, unless it only repeats the folder name, like `--name api` or `api (main)`), a `summary` record (written by older Claude Code versions), Codex's thread name from `session_index.jsonl`, then a short title made from the first prompt you typed, with no model call: pasted text (``) is left out when you also wrote something, then code blocks and leading Markdown markers (`#`, `-`, `>`, `1.`); the first line with words is cut at its first sentence end (`.`, `?` or `!` followed by a space), unless that leaves fewer than 16 characters; then cut at a word boundary to 80 characters with `…`. A session whose only prompts are slash commands is headed by the first one (`/dream --full`). - **Turns** are the prompts you typed, slash commands included, and not what tools or other sessions injected as user messages. ## Built from - One mod, `mods/sessions/`. `mod.json` is `{ "place": "none", "overlay": { "kind": "popup", "at": "top", "offset": 40, "width": 920, "height": 560 } }`, so nothing docks into a layout. - `main.js` is the popup view. `sessions.js` holds the rest: finding the folders, listing, indexing and caching, matching, transcript search, the preview, live detection, resuming and copying. - Where the sessions are: `sessions.json` in Herdr's home (`{ "claude": "~/.claude", "codex": "~/.codex" }`, both optional), else `$CLAUDE_CONFIG_DIR` and `$CODEX_HOME` (read once with `sh -c printf`), else `~/.claude` and `~/.codex`. - **Claude Code** keeps `/projects//.jsonl`, one JSON record per line. Sub-agents are in `/subagents/`, a level deeper, and are left out. The slug is lossy, so the folder comes from the records' `"cwd"` and the branch from `"gitBranch"`. A typed prompt is a record with `"message":{"role":"user","content":""}`; tool results have an array there. Titles are lines that start `{"type":"ai-title","aiTitle":…}`, `{"type":"custom-title","customTitle":…}` or (older versions) `{"type":"summary","summary":…}`, and the last of each kind wins. The patterns are anchored to the line start, because tool inputs such as SendMessage's carry a `"summary"` key too. - **Codex** keeps `/sessions/YYYY/MM/DD/rollout-