Terminal picker
The package and binary are agent-eye; eye is its alias, and the examples use it. Data lives in ~/.agent-eye.
eye with no arguments (or eye pick [words]) opens a picker on the terminal. Type words, the best session is on top; Enter lands you in it. Sessions of every enabled agent are listed together (Claude Code by default; see agents.md); a session of an agent that is switched off in [agents] enabled is left out.
- A search matches word forms (
tokensfindstoken,rebrandingfindsrebrand) and fixes a mistyped word from the words your sessions already use. The last word may be half typed; half of the words are enough, and a session that has more of them, and the rarer ones, ranks higher. A word in the title counts most, then summaries and outputs (PR URLs, Jira keys), then your prompts, then replies. A pasted link finds the session that made it. - Ties go to the title with fewer extra words, then to the newest session. Status and age never lift a session, so an old session can be first; sessions you archived come last. Titles are also matched fuzzily, after the rest.
eye findand board search use the same order. - Empty query: Needs you, Running, Waiting on others, Ideas, Paused, Done. Hidden sessions and the archive are left out.
- Each row: status mark (red ● needs you, green ▶ running, blue ◷ waiting, ✦ idea, dim ‖ paused, dim ✓ done), title, project (last folder), age.
- A session that runs something on its own has a short mark after its title:
bg(bg 2for several background tasks),↻for a loop,RCwhen remote control is on. The preview names them (Running background: npm run dev · 4 min,Running ↻ every 10 min · next 14:20,Remote control on <link>), andeye lsandeye showprint the same. - The preview and
eye showhave one line for the days a session was worked on:worked 6 days · 7 h 40 m · last today 14:20(active time counts gaps between messages of up to 15 minutes). It is missing until the daemon, oreye scan, has counted a session that eye read before it kept this. - The preview (right when wide, below when narrow) shows state, next step and who acts (the label says who, so the line does not repeat its owner:
Next (you) review the PR), topics, outputs, sub-agents, tokens used ("Tokens 2.3M (sub-agents 410k)") and the resume command; for anything but the terminal astarted from: an app (sdk-ts)line, and a note when the session's folder does not exist on this machine. The preview and the conversation view name the session's agent ("Claude") where they refer to it. - A rescan (about 20-40 ms) runs before the screen opens, so results are fresh without the daemon.
Keys#
| Key | Does |
|---|---|
| Up / Down, Ctrl-P / Ctrl-N, PgUp / PgDn | move |
| Enter | resume the session (restores the transcript from the archive first if it is gone); on an idea, starts it here |
| Ctrl-F | fork the session: resume it as a new session that branches from it (for Claude Code claude --resume <id> --fork-session); the original stays as it is. No open-elsewhere question, forking a live session is fine. An agent that cannot fork says so |
| Ctrl-T | switch the preview between the summary and the conversation of the selected session (your prompts and the agent's replies, newest at the bottom; it is read from the transcript or the archive copy when you open it) |
| Shift-Up / Shift-Down | scroll the conversation view |
| Ctrl-Y | copy the resume command (pbcopy on macOS; wl-copy, xclip or xsel on Linux). With no clipboard tool the command is shown instead |
| Tab | hide or show the preview |
| Ctrl-R | remind me: a one-line input for the selected session or idea. Type when, as for eye remind: tomorrow, mon..sun, 30m, 4h, 3d, 1w, 2026-11-20 or 2026-11-20 14:00 (a day alone is 9:00), and a note after -- (tomorrow -- Ana's reply). Enter sets it, an empty line clears it, Tab switches the desktop notice for due reminders on or off (the footer says which; off by default), Esc closes the input; words it cannot read are explained and the input stays open. The row shows ⏰ due or the time (within 3 days), and the preview the reminder. A due reminder puts the row in Needs you |
| Ctrl-L | what the selected session left behind: the list opens in the preview pane (Up / Down move). s stops a server or container, r removes a scratch worktree, c copies the git command for commits not pushed or files not committed (eye never runs it), i stops listing the item, a opens the session with a first message that lists what it left. Every key but c asks y/N in the footer first, and says exactly what will happen (Stop node (pid 38090, port 4321)? y/N); anything but y cancels. (Plain L types into the search, so the key is Ctrl-L.) |
| Ctrl-X | hide the session (a useless one); on a hidden one, show it again |
| Ctrl-A | include hidden sessions and the archive |
| Ctrl-U / Ctrl-W | clear the query / delete a word |
| Esc, Ctrl-C | quit, prints nothing |
Enter on a session leaves the screen and runs the session's agent in the session's folder (for Claude Code claude --resume <id>), replacing eye in this terminal. With --print it writes the shell line (cd '<dir>' && claude --resume <id>) to stdout instead. The folder and every argument are quoted, and an id that is not plain letters, digits, -, _ or . (or starts with - or .) is refused, and so is a folder with a control character in its name. Starting an idea records the start, as eye idea start does, and sends the idea's prompt (never its notes); an idea without a prompt opens the agent waiting for you. An idea whose folder does not exist shows + before its project in the list and a line in the preview; Enter asks first (Enter again creates the folder and starts, Esc cancels). Eye creates folders only inside your home folder; for any other missing folder, or a file in the way, Enter says why and starts nothing. Ctrl-F leaves the same way with the agent's fork command (or prints that line with --print). A session that is open in another terminal asks first: Enter again resumes anyway, Esc cancels.
The preview of a session that left things behind has one more line, Leftovers: 2 servers (ports 4321, 4350), 3 commits not pushed, from what the daemon last found ([loose] in config.md).
Shell key#
Add one line to ~/.zshrc (or ~/.bashrc with bash):
eval "$(eye init zsh)"
To keep the shell starting cleanly if eye is ever uninstalled, guard it:
command -v eye >/dev/null && eval "$(eye init zsh)"
Ctrl-G then opens the picker with the current command line as the start query. The chosen command lands on the command line (nothing runs until you press Enter, and it goes into your normal history). Esc leaves the line untouched. Another key: eye init zsh --key ctrl-o. The widget calls the program under the name it was invoked as. eye doctor prints the line if it is missing.
Without a screen#
eye pick --filter "words"prints the ranked list (--limit,--all).eye pick --filter "words" --first --printprints the first hit's command; without--printit runs it.eye pick --filter "words" --first --fork [--print]forks the first hit instead.eye show <id> --conversation [-n 10]prints the last messages of a session (--jsonfor the API shape);eye resume <id> --forkprints the fork command (and opens it likeeye resume; add--dry-runto only print).eye idea start <id>on an idea whose folder does not exist asksFolder <path> does not exist. Create it? [y/N]in a terminal;--create-foldermakes it without asking (for scripts), and without a terminal and without the flag it stops with a message that names the flag.--dry-runcreates nothing.eye night on|off,eye night add idea:<n>|<session> [--prompt ...] [--limit 30%|2M|90m] [--agent claude|codex|agy|opencode] [--switch] [--isolation worktree|copy],eye night ls|cancel|log|window|parallel|bring|discard, andeye night run-now <run> --yes [--wait]plan and run the night shift (night.md). In the picker a session made by a night run saysnightin its row, and its preview has aNight runline with the status, time and branch and the first line of the report.eye loose [<session>] [--json]scans now and lists each session's leftovers (what it left behind), each with its key; the command and[loose]keep the nameloose.eye loose stop <key>,eye loose remove <key>andeye loose send <session>ask y/N first (--yesskips it; without a terminal it is required);eye loose ignore <key>stops listing an item.send --dry-runprints the command and runs nothing.eye forget <id>... [--transcript] [--yes] [--dry-run]andeye forget --folder <path> [--transcript](every session whose folder is that path or inside it) take sessions out of eye: the session, its search text, every row that belongs to it and eye's archive copy. With--transcriptthe agent's own copy goes too (Claude Code: the transcript file and its sub-agent folder; Codex: the rollout and its line insession_index.jsonl; Antigravity: the conversation folder, its database and its summary row, and its lines inhistory.jsonland the cache files, which are left alone while any Antigravity conversation is open; OpenCode: the session's rows or JSON files). It lists the sessions and asks[y/N]first (--yesskips it; without a terminal it is required),--dry-runonly lists what it would remove (and marks a session that is open now, which the real run refuses), and amanualsnapshot (eye backup ls) is taken before anything is removed. Without--transcriptthe agent's copy stays, so the next scan finds the session again. This cannot be undone. The board has FORGET… in the card menu and the panel (key X).eye usage [--days N|--week|--month] [--by project|folder|agent|model|session] [--json]prints cost, tokens and plan limits (usage.md).eye ls [--origin terminal|headless|app|desktop|ide|web|night]lists only the sessions started there (agents.md).eye statusline [--wrap '<cmd>']is an opt-in Claude Code status line that stores the plan limits Claude Code hands to it (usage.md).eye remind <id> <when> [--note TEXT]sets a reminder on a session (an id or its first 6 characters) or an idea (idea:<n>),eye remind <id> --clearremoves it andeye remind lslists them, due ones first,eye remind notify [on|off]shows or switches the desktop notice for due reminders (off by default).<when>is as for Ctrl-R above.eye showandeye ls --jsoncarry it.eye idea addandeye idea edittake--agent <id>to start an idea in a particular agent (default: the first enabled one).eye idea add --from-session <id>records the session the idea came from (an id or its first 6 characters).eye summarize [<id>...|--all] --max <n>summarizes at mostnsessions in this run;--print-excerptprints the masked excerpt that would be sent.eye archive [<id>|--all]makes the compressed copy of one transcript, or of every one that has none yet, now; the daemon does the same on its own.eye restore <id>puts a copy back.eye daemon --no-boardruns the daemon without serving the board, whatever[board] enabledsays.eye install --boardalso turns the optional board on;eye install --service-dir <folder>puts the service file in that folder instead of the default one.eye night offswitches the night shift off ([night] enabled = false); it is the other half ofeye night on.eye export [--to <folder or file>]writesagent-eye-<host>-<date>-<time>.eyepack(database, archive, transcripts not archived yet);eye import <file> [--dry-run] [--yes]reads one back, on this machine or another (see backups.md).eye export <session> [--html|--md] [--to …]writes one session as a readable page.- Without a terminal,
eyeprints the list likeeye ls.
Config and environment#
- Hidden sessions follow
[hide]inconfig.toml; which agents are followed is[agents] enabled.docs/config.mdlists every key. - The web board is optional and off by default (
[board] enabled).eye board onturns it on,eye board offturns it off; the picker never needs it. NO_COLORturns colours off.EYE_PICK_TIMING=1shows the search time in the corner.EYE_CLAUDE_BINreplaces theclaudebinary that Enter, Ctrl-F and the summaries run (used by tests).EYE_CLAUDE_DIRpoints eye at another Claude Code folder,EYE_HOMEat another eye home.--no-scanskips the rescan.