claude-focus

One priority queue over all your running Claude Code sessions, in iTerm2 or herdr.

If you run ten or twenty Claude Code sessions at once, a lot of time goes into finding the one that needs you. claude-focus watches every session, scores what each one needs from you, and shows them in one list: what needs you first, then your to-dos, the sessions that wait for something external, the ones that work, the ones that are done, and your free terminals. Enter takes you to the selected session's pane. When you answer, the session works on, and the next one is selected.

It also lets a session wait for something external (a reply, a deploy, a date) without sitting in your queue. When the time comes or a check command succeeds, claude-focus types a wake-up message into the session, and Claude continues by itself.

What it does:

• One queue over every Claude Code session, ranked by how much each one needs you, with the one-line request it has for you.
• Scoring by a headless claude -p call on your own Claude Code login, or by the much cheaper jev model with a TypeSafe or OpenRouter key (see "Scoring").
• Pending waits: a session waits for a time or a check command, leaves your queue, and is woken up with a message in its prompt.
• Free terminals: panes at a bare shell, where a new session starts in a folder you pick by typing a few letters.
• iTerm2: global hotkeys, a green profile for free panes, and a restore of every window after a crash or a restart.
• herdr: the queue in herdr's own sidebar, herdr keys to jump to the session that needs you most, and no setup in the terminal itself.

iTerm2 and herdr

claude-focus finds each session's pane, reads its screen, types wake-up messages and brings panes to the front through the terminal's API: the iTerm2 Python API or herdr's socket API. Everything else (the queue, the scoring, the waits) is the same in both.

iTerm2 is a terminal of its own. herdr runs in any terminal (Ghostty, Terminal.app, Warp, iTerm2, ...), so with herdr any terminal works; without it, only iTerm2 does. Sessions that run inside tmux, in another herdr session or on a remote machine show without a pane.

Which terminal

Config terminal ("auto", "iterm" or "herdr") decides first. With "auto" (the default), a focus screen or command inside an iTerm2 pane uses iTerm2, and one inside a herdr pane uses herdr. A herdr pane can carry iTerm2's variables too (when iTerm2 started the herdr server); then herdr wins.

The background service runs in neither, so it asks both. When only one runs, it takes that one. When both run, it takes the one that runs more of the live Claude sessions, by their parent processes: a pane's shell is a child of iTerm2 or of the herdr server. This needs no API and no permission. The service looks again every minute and restarts on the other terminal when your sessions move there. claude-focus status says which terminal it uses, and whether it was detected or set in the config.

Requirements

• macOS.
• iTerm2 with its Python API on, or herdr (tested with 0.9.5, API protocol 22).
• Python 3.10 or newer.
• Claude Code (tested with 2.1.29x to 2.1.306). claude-focus reads Claude Code's own session files, which are not a public API, so a Claude Code update can break it.

This is an early release. It runs every day on one Mac with about 20 sessions; expect rough edges elsewhere, and please open an issue.

Install

In iTerm2, first turn on its Python API (Settings > General > Magic > Enable Python API), then run these two commands in iTerm2. In herdr, run them in one of its panes:

brew install nejko/tap/claude-focus
claude-focus setup

Homebrew brings its own Python. Without Homebrew, install it with uv: uv tool install claude-focus (see docs.astral.sh/uv), or with pipx: pipx install claude-focus. The newest code from GitHub, before it is released: uv tool install git+https://github.com/nejko/claude-focus.

claude-focus setup does the rest and tells you what it did. You can run it again at any time; it skips what is done. It:

1. checks for macOS, the terminal and claude, and connects to the terminal. The first time in iTerm2, macOS asks whether claude-focus may control iTerm2: allow it.
2. asks your name, for the messages to sessions (~/.claude-focus/config.json).
3. adds the prompt hook to ~/.claude/settings.json (see "Pending waits").
4. adds a short rule to ~/.claude/CLAUDE.md, so that sessions know how to wait (the text is in claude_focus/claude_md_rule.md).
5. sets up the terminal:
   • iTerm2: asks whether you want free terminals, adds a green iTerm2 profile and lets claude-focus switch panes to it (see "iTerm2").
   • herdr: offers herdr's Claude Code integration (herdr integration install claude), and two herdr keys in ~/.config/herdr/config.toml (see "herdr").
6. starts the background service, a LaunchAgent that starts at login and restarts after a crash or when the terminal restarts. It gets the PATH of the shell you run setup from: the scorer needs claude, and your check commands need their tools.
7. opens the focus screen in a new iTerm2 window or herdr tab. Keep it open.

Before it changes settings.json, CLAUDE.md or herdr's config.toml the first time, setup keeps a copy next to it (.before-claude-focus). claude-focus setup --dry-run shows what it would do; --yes takes the defaults without asking.

The scorer follows the rules in ~/.claude-focus/priorities.md. Edit them to say what matters to you.

Upgrade

brew upgrade claude-focus && claude-focus setup, or with uv uv tool upgrade claude-focus && claude-focus setup (setup restarts the service on the new code).

Uninstall

claude-focus uninstall removes the service, the hook, the CLAUDE.md rule, the green iTerm2 profile and the herdr keys, and keeps your state in ~/.claude-focus (--purge removes it too). Then brew uninstall claude-focus, or uv tool uninstall claude-focus.

Development

Clone the repo, python3 -m venv .venv && .venv/bin/pip install -e '.[jev]', and run .venv/bin/claude-focus (or link bin/claude-focus onto your PATH).

Commands

claude-focus                  # the focus screen (in its own iTerm2 window or herdr tab)
claude-focus setup            # set everything up, or check it again
claude-focus list             # print the queue once
claude-focus go               # go to the session at the top of the queue
claude-focus show             # bring the focus screen to the front, or open one
claude-focus pending ...      # from inside a session: wait for something external
claude-focus restore          # iTerm2, after a crash: open the sessions of the last iTerm2 run again
claude-focus reboot           # iTerm2, before a planned restart: save the layout, stop working sessions
claude-focus cost             # scorer calls and spend per day
claude-focus status           # which terminal, and is the service running?
claude-focus uninstall        # undo setup

go and show work in both terminals; the herdr keys run them.

The focus screen

The sections, top to bottom:

• NEED YOU: the session waits for your answer, ranked by priority. A session whose turn ended with a request to you while its background shells still run (a page to pick from, a dev server to try) is here too, marked ◌ shells.
• YOUR TO-DOS: the session waits for something external and left you a task meanwhile (send a draft, sign, pay). Oldest first.
• PENDING: the session waits for a time or a check, or you snoozed it. Next wake-up first.
• WORKING: the session is busy, or its background shells still run and it only waits for them: when they end, it continues by itself. The scorer reads such a turn too, and it moves to NEED YOU when it asks you for something.
• FREE: nothing is needed; you can close or reuse the terminal.
• AVAILABLE TERMINALS: free panes, ready for a new session (see "Free terminals").

Every section uses one grid, so each column is always in the same place: a lead (in NEED YOU the priority as a number and a bar whose length is the priority; in PENDING the wake time), an age (how long it has waited for you, worked or slept; in PENDING the time until it wakes), the name, the folder the session runs in, a kind (decision, action, check, wait, snoozed, busy, shells, ...) and the text. The folder column is as wide as the longest folder on the screen, at most 40 columns; a longer folder keeps its end. Windows narrower than 110 columns drop the folder column (WORKING then shows the folder as its text), and below 100 columns also the kind column.

Each section has its own color. A priority of 80 or more is red, of 60 or more amber, and the rest grey. Alerts are red: a wake-up that could not be typed, a duplicate window, a session without a pane. What needs you is bright, PENDING and WORKING are softer, and FREE is grey. The selected row has a tinted background and a ▌ at the left. The screen uses 24-bit color and follows the terminal's dark or light appearance: iTerm2's, or macOS's in herdr.

Themes

t shows the next theme on the screen at once, and T the one before (the arrow keys step too). The key line says which theme it is. Enter keeps it in the config ("theme"), and Esc goes back to the theme you had.

The retro themes paint their own background, so they look the same in a dark and a light terminal. Their colors come from the programs where a source exists: the MS-DOS 6.0 source for QBasic, TURBO.EXE 7.01 for Turbo Pascal, WordPerfect's default Setup colors, a screenshot for Award BIOS, the Pepto palette for the C64, LADDER.COM 1.30 for Ladder, and Claude Code 2.1.306 for Claude Code. For COBISS, IZUM's newsletters confirm the DEC VT terminals, but no picture of the text-mode OPAC was found.

A theme is a palette in claude_focus/themes.py. Its docstring lists the keys that change how the screen is drawn: paint, frame, box, title, select, marker, bar, keys, rule, status and upper.

The selection starts on the first row of NEED YOU (else of YOUR TO-DOS). After Enter, it goes back there. The rows never move when the selection moves; a long list scrolls to keep the selected row visible. While the focus screen has the keys, its title bar is green (in a theme, the theme's color).

Keys

From anywhere: in iTerm2, two optional global hotkeys ("hotkeys": true in the config): ⌃⌥N goes to the top session and ⌃⌥F brings the focus screen to the front. In herdr, prefix+a and prefix+f do the same (setup adds both keys).

There is no free skip: to move the top session down, snooze it. Its row shows how many times you did.

After Enter on a session that asks a question (AskUserQuestion), the focus screen comes back to the front when you submit the answers. It stays in the session when you press Esc or pick "Chat about this", when the dialog was a permission prompt, and when you went to another pane or app first.

Scoring

When a session has waited for 15 s, and you are not in its pane, a scorer reads the bottom of its screen, its last message and your ~/.claude-focus/priorities.md, and rates how much it needs you now:

• a priority from 1 to 100 (five levels, from "nothing needed" to "drop everything"),
• a kind: decision, action, login, review, info or nothing,
• the effort in minutes.

The same scorer rates every session, so the numbers can be compared. A session is scored again every 12 hours. The rank is the score plus 0.15 per hour of waiting (at most +10), so a neglected session cannot sink forever, but a medium item never passes a critical one. A session that asks a question is always in NEED YOU, whatever its score.

There are two scorers (config scorer):

• claude (the default): a headless claude -p call with your own Claude Code login, on Sonnet 5.5 (scorer_model). It also writes the one-line request, a reason, deadlines and wake-up times. About $0.010 per call (no CLAUDE.md, memory, MCP servers or thinking; a 5-minute cache).

• jev: TypeSafe's jev model answers typed questions with probabilities. About $0.0001 per call. It needs a key and the jev extra, which needs the uv install: uv tool install --force 'claude-focus[jev]'.

  jev works with OpenRouter. Give it either key, in the environment or in ~/.config/claude-focus/credentials (one NAME=value per line, mode 600):

  • TYPESAFE_API_KEY: jev through TypeSafe.
  • OPENROUTER_API_KEY: jev through OpenRouter, at the same price, billed to your OpenRouter account.

  A TypeSafe key wins when both are set.

  jev writes no text. An open question shows with its own text. Otherwise, when jev says the session needs you, Claude Haiku 5.5 (ask_model) writes the one-line request from the last message and the screen: the immediate next step, in the message's language. That is a second claude -p call for those sessions only, measured at $0.0002 to $0.0006. With "ask_model": "", or when that call fails, the line comes from the session itself: the first item under a "Needed from you" style heading, a "nothing needs you" sentence, Claude Code's recap line, or the first sentence of the last message.

At 150 to 350 calls a day, the claude scorer costs about $45 to $105 per 30 days, jev about $0.50 to $1. claude-focus cost shows the real numbers. When the scorer fails, the focus screen shows the error in red, and new sessions wait unscored at 50.

Pending waits

A session that waits for something external runs this from its Bash tool:

claude-focus pending --until 09:00 --note "launch check"
claude-focus pending --check '<command; exit 0 = it happened>' --every 10 --until "2026-10-02 18:00" --note "the v2.0 tag"
claude-focus pending --check '<command>' --until "+1d" --note "the export" --needs "Review and send the draft"
claude-focus pending --show | --clear

The session leaves your queue and shows under PENDING. When the time comes or the check exits 0, the engine types a one-line wake-up message into the session's prompt and submits it, so Claude continues by itself. The message tells Claude to ask you before any irreversible or outward-facing step.

With --needs, the session shows under YOUR TO-DOS with that request until you press d, and the wait still wakes it.

A wait set in a turn that answers your message gets the to-do "Read its answer to your message", so the answer does not go straight to PENDING unread. The to-do is done when your keys are in the session's pane after the turn ended. The same holds when a background task started a later turn and that turn set the wait.

When you type into a waiting session, the wait ends. Other prompts keep it: a background task notification, a message from another session, the answer to a question dialog, and an idle compaction that Claude Code starts by itself. When the status changes after a wait was set, the engine reads the transcript, and only a prompt that you typed ends the wait.

The UserPromptSubmit hook tells Claude at once that your typing ended its wait, and gives it the exact command to set the same wait again. Without the hook, the engine still ends the wait, but Claude does not learn it. claude-focus setup adds it to ~/.claude/settings.json, and running sessions pick it up without a restart. By hand, it looks like this:

"hooks": {
  "UserPromptSubmit": [{"hooks": [{"type": "command",
    "command": "/Users/YOU/.local/bin/claude-focus hook prompt-submit", "timeout": 10}]}]
}

Claude Code gives the hook no origin field, so the hook recognizes a task notification or a message from another session by the start of its text.

Safety rules of the waker:

• It types only into an empty prompt: never over a draft, never into an open question. In iTerm2 it reads the screen and the cursor position; in herdr, which gives no cursor, the screen and its colors (Claude Code's suggestion text is dim, a draft is not). If typing is not safe, the session goes into NEED YOU with a red wake-up note (priority at least 70), and the wake-up is typed later, when the same session is at an empty prompt again and you are not in its pane.
• Only one process runs the waker (the service, or a focus screen when no service runs), so a wake-up is never typed twice.
• A check's output is not put into the wake-up message (it can carry text from outside, such as an e-mail). "wake_check_output": true turns it on.

Free terminals

A pane whose Claude session has ended is free for the next one, and shows under AVAILABLE TERMINALS with its folder, the program and where it is. A pane in which a Claude session runs is never free, and neither is the focus screen's own pane.

• iTerm2: only panes with the green Available profile are free; they show with their tty (see "iTerm2").
• herdr: every pane at a bare shell prompt (zsh, bash, fish, ...) is free, with no setup. It shows as workspace:tab, such as metaos:3, or metaos:3.2 for the second pane of a tab.

Enter on a free terminal, or n for the first one, opens a list of folders for a new session. It holds every folder that Claude Code has run in (Claude Code's own list in ~/.claude.json) and the subfolders of your project folders (project_roots), the most recently used first, with the time of the last session there. Type to search: every word you type must be in the path, and a folder whose own name starts with the first word comes first. When no path has what you typed, the letters are an abbreviation of the folder's name: clfo finds claude-focus.

To start in a new folder, type its name. Below the list, + new folder shows where it goes: into the first of your project folders (project_roots) that exists, or to the path you typed when it starts with ~ or / (clients/acme makes both levels). When no folder matches, it is selected; otherwise ↑ on the first row reaches it. Enter on it types mkdir -p <folder> && cd <folder> && claude. It shows only for a folder that does not exist yet.

• Enter types cd <folder> && claude into the terminal (Ctrl-U first, so anything typed at its prompt goes away) and takes you there; in iTerm2 the pane also gets back your default profile. new_session_command sets the command, for example claude --model opus. It types only into a pane that is still at a bare shell.
• In a folder where Claude Code ran before, Enter first asks how to start, with the number of sessions there, when the last one ran, and how many run now. n (or Enter) starts a new session, c continues the last one (claude --continue), and r resumes an earlier one from Claude Code's own list (claude --resume). ↑↓ and Enter work too. The flag goes after new_session_command. Esc goes back to the folders.
• Tab goes to the terminal without starting anything.
• Esc goes back to the list of sessions.

iTerm2

claude-focus uses the iTerm2 Python API. Turn it on in Settings > General > Magic > Enable Python API; the first time, macOS asks whether claude-focus may control iTerm2.

Finding a session's pane. By the tty of its process, including panes hidden by a maximized pane.

Global hotkeys. With "hotkeys": true, a focus screen registers ⌃⌥N (go to the top session from any pane) and ⌃⌥F (bring the focus screen to the front). hotkey_go and hotkey_focus_window set other keys. The service does not register them: from the service they did not reach iTerm2.

The green profile

In iTerm2, a free terminal is a pane with the green profile Available. If you say yes to free terminals in claude-focus setup, it adds the profile as an iTerm2 dynamic profile (your default profile with a green background, in ~/Library/Application Support/iTerm2/DynamicProfiles/claude-focus.json) and turns on auto_profiles. A profile named Available that you made yourself is used as it is. Then the engine keeps the color true:

• When a Claude session ends and its pane is back at a bare shell (zsh, bash, fish, ...), the pane gets the free profile. A pane that runs another program after the session (vim, a script) is not free.
• When a Claude session starts in a free pane, the pane gets back your default profile (session_profile).

You can also mark a pane free by hand: bind a key to "Change Profile" > Available in iTerm2's key bindings. Config free_profile names another profile.

This is the only part of claude-focus that uses iTerm2 profiles; the colors of the focus screen need no setup. Without the profile, the section stays empty, and a switch to a profile that does not exist changes nothing. The engine switches a profile with iTerm2's SetProfile escape sequence, sent into the pane as program output; nothing shows on the screen.

Crash recovery

When the Mac crashes, every iTerm2 window and every Claude session in it stops, and Claude Code deletes the session files of the dead processes. So claude-focus records the layout itself.

Every 10 s the engine reads each iTerm2 window (frame, display, full screen) and the Claude session in each pane (id, name, folder, the flags of its claude command, its pending wait). When the layout changed, it appends a line to ~/.claude-focus/layouts.jsonl and syncs it to disk.

After the restart, the focus screen says that windows from before are closed: R shows the list, and y opens it. claude-focus restore does the same from a terminal (--dry-run only shows the list). It opens the same windows on the same displays and types cd <folder> && claude <flags> --resume <id> into each pane's login shell, so the shell stays when Claude exits. Then it sets the pending waits again. Other commands that ran in those panes are not run again, and it skips sessions that run now and folders that are gone. A resume keeps the flags of the original command that matter: --model, --permission-mode, --add-dir, --effort, and --dangerously-skip-permissions if you used it.

Planned restart

Before you restart, run claude-focus reboot in a new iTerm2 window (--dry-run only shows the list). It saves the layout, stops each working session with Esc, and waits until it stops. After the restart, the service opens the saved layout by itself, once. A session that was working is told to continue, a session that asked something asks again, and an idle session gets no message.

herdr

herdr is a terminal workspace manager for coding agents: workspaces, tabs and panes in any terminal, kept alive by a server. claude-focus talks to that server over its socket API and needs nothing from the terminal that shows herdr.

Finding a session's pane. herdr knows the foreground processes of each pane, so a session's pane is the one whose foreground runs its process. Two processes of one conversation (a --resume while the old one runs) are told apart this way. herdr's Claude Code integration (herdr integration install claude; setup offers it) also tells herdr the session id in each pane, which finds a session whose process is not in the foreground (Claude Code suspended with Ctrl-Z).

Keys. Setup adds two herdr keys to ~/.config/herdr/config.toml, between # claude-focus setup markers that claude-focus uninstall removes, and reloads herdr's config:

• prefix+a runs claude-focus go: to the session that needs you most. When nothing needs you, a herdr toast says so.
• prefix+f runs claude-focus show: the focus screen, or a new one.

prefix is herdr's prefix key (Ctrl-B unless you changed it). Set herdr_key_go and herdr_key_focus_window for other keys. Setup never takes a key that your config binds already, and when your config is a link (managed by Nix or your dotfiles), it prints the keys for you to add there instead of replacing the link.

The queue in herdr's sidebar. The engine puts each session's place in the queue into herdr's pane metadata, as tokens:

• $cf_state: need you, to-do, wakes 14:00, working or free,
• $cf_priority: the priority in NEED YOU,
• $cf_ask: the one-line request (at most 60 characters).

They show once your herdr config names them in the rows of its agent list, for example:

[ui.sidebar.agents.rows_by_agent]
claude = [["state_icon", "workspace", "tab", "$cf_priority"], ["$cf_ask"]]

The tokens expire 10 minutes after claude-focus stops. "herdr_sidebar": false turns them off.

Focus. "Your keys are in the pane" means herdr's focused pane while the app that shows herdr (the terminal that runs a herdr client) is the front app. herdr's events (a pane opens, closes or gets the focus) make the focus screen and the engine read again at once.

Restarts. herdr's server keeps its panes and resumes the Claude sessions in them after a restart, so claude-focus records no layout for herdr, and restore and reboot only say so.

One server. claude-focus drives one herdr server: herdr_socket in the config when set, else the server of the pane it runs in ($HERDR_SOCKET_PATH), else the default session's (~/.config/herdr/herdr.sock). Sessions in another herdr session or on a remote machine show without a pane.

Configuration

~/.claude-focus/config.json overrides the defaults in claude_focus/store.py. For example:

{"user_name": "Ana", "user_role": "a freelance developer", "companies": {"acme": "Acme"}}

Files

All under ~/.claude-focus/ (mode 700):

• priorities.md: your rules for the scorer, in plain words. Edit it freely.
• config.json: your settings.
• state.json: scores, snoozes, manual priorities, pending waits.
• focus.log: scores, wake-ups, profile switches, errors.
• costs.jsonl: one line per scorer call.
• layouts.jsonl (iTerm2): layout snapshots for a restore (3 days, and always the whole previous iTerm2 run).
• engine.json, engine.lock, service.pid, service.log: which process is the engine.

The jev keys live in ~/.config/claude-focus/credentials (see "Scoring").

Privacy and safety

• For each score, the scorer gets the bottom 45 lines of the session's screen, its last message (up to 3,500 characters), its folder and name, and your priorities.md. The claude scorer sends them to Anthropic through your Claude Code. jev sends them to TypeSafe, or to OpenRouter with an OpenRouter key, and for the request line (ask_model) the screen and the last message also go to Anthropic through your Claude Code. claude-focus sends nothing else anywhere.
• It types into your terminals only for wake-up messages (only into an empty prompt), the command of a new session that you start from the folder list, and in iTerm2 the restore commands, Esc on reboot and the profile escape sequence. In herdr it also sets the sidebar tokens, which stay inside herdr.
• The background service runs your check commands with your shell and your PATH.
• It reads ~/.claude/sessions/, the transcripts in ~/.claude/projects/ and the list of folders in ~/.claude.json, and never writes them.

How it works

One process is the engine: it scores and runs the waker; in iTerm2 it also takes the layout snapshots and switches profiles, and in herdr it sets the sidebar tokens. It holds ~/.claude-focus/engine.lock, so there is never a second one. Normally the engine is the background service, and every focus screen is a view of the shared state (its header says service). Without the service, the first focus screen is the engine.

Every 3 s it reads ~/.claude/sessions/<pid>.json, the data behind claude agents --json: busy, waiting (a question or a permission prompt) or idle. Then it asks the terminal where each session's pane is (see "iTerm2 and herdr"). The terminal sits behind a bridge with the same methods for both: claude_focus/iterm.py and claude_focus/herdr.py, and claude_focus/terminal.py picks one.

If two processes run the same conversation (a --resume while the old window is still open), both rows show DUPLICATE. Close one of them, because both write to one transcript.

Tests

.venv/bin/python -m unittest discover -s tests

The tests use a scratch folder, never your ~/.claude-focus. The herdr tests run against a fake herdr server on a scratch socket.

Releasing

1. Set the new version in claude_focus/__init__.py (__version__), commit, and push main.
2. Push its tag: git tag v0.1.1 && git push origin v0.1.1. The Release workflow (.github/workflows/release.yml) checks that the tag matches the version and publishes the release to PyPI.
3. In nejko/homebrew-tap, point url and sha256 in Formula/claude-focus.rb at the new sdist on PyPI, and push.

License

MIT. See LICENSE.