agent-command-tab 0.2.0__tar.gz → 0.4.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. agent_command_tab-0.4.0/PKG-INFO +122 -0
  2. agent_command_tab-0.4.0/README.md +100 -0
  3. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/pyproject.toml +1 -2
  4. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/__init__.py +1 -1
  5. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/agent_adapters/__init__.py +7 -0
  6. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/agent_adapters/base.py +83 -16
  7. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/agent_adapters/claude_code.py +29 -38
  8. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/agent_adapters/codex.py +69 -17
  9. agent_command_tab-0.4.0/src/agent_command_tab/agent_input_box_typing.py +139 -0
  10. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/agent_process_tree.py +217 -76
  11. agent_command_tab-0.4.0/src/agent_command_tab/agent_session_pausing.py +218 -0
  12. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/app_controller.py +304 -141
  13. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/claude_code_transcript_records.py +4 -11
  14. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/command_line.py +112 -18
  15. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/context_window_usage.py +60 -19
  16. agent_command_tab-0.2.0/src/agent_command_tab/iterm2_connection_thread.py → agent_command_tab-0.4.0/src/agent_command_tab/dashboard_core.py +1212 -743
  17. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/dashboard_core_api.py +4 -4
  18. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/docked_window_frames_store.py +9 -12
  19. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/global_shortcut_key_filter.py +2 -3
  20. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/hook_event_forwarder.py +29 -16
  21. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/hook_event_tracking.py +77 -10
  22. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/hook_states_store.py +15 -13
  23. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/hooks_installer.py +87 -46
  24. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/installed_copy_paths.py +3 -5
  25. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/list_sorting.py +11 -20
  26. agent_command_tab-0.4.0/src/agent_command_tab/login_shell_environment.py +86 -0
  27. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/messages_between_agent_sessions.py +12 -7
  28. agent_command_tab-0.4.0/src/agent_command_tab/open_tool_call_reading.py +94 -0
  29. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/pause_records_store.py +12 -17
  30. agent_command_tab-0.4.0/src/agent_command_tab/saved_agent_sessions_store.py +193 -0
  31. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/screen_readings.py +2 -30
  32. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/session_status_computation.py +45 -78
  33. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/settings_store.py +134 -78
  34. agent_command_tab-0.2.0/src/agent_command_tab/iterm2_snapshot_builder.py → agent_command_tab-0.4.0/src/agent_command_tab/snapshot_builder.py +111 -92
  35. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/snapshot_data_classes.py +33 -27
  36. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/start_with_iterm2.py +53 -30
  37. agent_command_tab-0.4.0/src/agent_command_tab/terminal_backends/__init__.py +1 -0
  38. agent_command_tab-0.4.0/src/agent_command_tab/terminal_backends/base.py +216 -0
  39. agent_command_tab-0.4.0/src/agent_command_tab/terminal_backends/iterm2_terminal_backend.py +645 -0
  40. agent_command_tab-0.4.0/src/agent_command_tab/terminal_backends/tmux_terminal_backend.py +581 -0
  41. agent_command_tab-0.4.0/src/agent_command_tab/unix_socket_listeners.py +18 -0
  42. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/user_interface/agent_session_outline_view.py +446 -477
  43. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/user_interface/agent_tool_icons.py +3 -3
  44. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/user_interface/app_icon.py +1 -1
  45. agent_command_tab-0.4.0/src/agent_command_tab/user_interface/control_helpers.py +62 -0
  46. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/user_interface/list_window.py +2 -2
  47. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/user_interface/menu_bar_status_item.py +20 -13
  48. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/user_interface/named_colors.py +10 -13
  49. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/user_interface/pointing_hand_button.py +2 -2
  50. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/user_interface/popover_container.py +167 -120
  51. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/user_interface/process_info_alert.py +5 -10
  52. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/user_interface/row_text_rendering.py +47 -68
  53. agent_command_tab-0.4.0/src/agent_command_tab/user_interface/saved_sessions_window.py +345 -0
  54. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/user_interface/screen_layout.py +20 -3
  55. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/user_interface/settings_window.py +127 -64
  56. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/user_interface/sidebar_panel.py +7 -8
  57. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/user_interface/talk_to_each_other_alert.py +6 -13
  58. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/window_list_ordering.py +2 -5
  59. agent_command_tab-0.4.0/src/agent_command_tab.egg-info/PKG-INFO +122 -0
  60. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab.egg-info/SOURCES.txt +12 -4
  61. agent_command_tab-0.2.0/PKG-INFO +0 -85
  62. agent_command_tab-0.2.0/README.md +0 -62
  63. agent_command_tab-0.2.0/src/agent_command_tab/agent_session_pausing.py +0 -269
  64. agent_command_tab-0.2.0/src/agent_command_tab/iterm2_actions.py +0 -331
  65. agent_command_tab-0.2.0/src/agent_command_tab/session_preview_computation.py +0 -228
  66. agent_command_tab-0.2.0/src/agent_command_tab/user_interface/control_helpers.py +0 -38
  67. agent_command_tab-0.2.0/src/agent_command_tab.egg-info/PKG-INFO +0 -85
  68. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/LICENSE +0 -0
  69. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/setup.cfg +0 -0
  70. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/agent_adapters/generic.py +0 -0
  71. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/monitor_assignment.py +0 -0
  72. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/user_interface/__init__.py +0 -0
  73. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab/user_interface/sidebar_placement.py +0 -0
  74. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab.egg-info/dependency_links.txt +0 -0
  75. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab.egg-info/entry_points.txt +0 -0
  76. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab.egg-info/requires.txt +0 -0
  77. {agent_command_tab-0.2.0 → agent_command_tab-0.4.0}/src/agent_command_tab.egg-info/top_level.txt +0 -0
@@ -0,0 +1,122 @@
1
+ Metadata-Version: 2.4
2
+ Name: agent-command-tab
3
+ Version: 0.4.0
4
+ Summary: macOS menu bar list, window or screen-edge sidebar of the iTerm2 tabs and tmux windows where AI coding agents run
5
+ Author: Ben Weisburd
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/bw2/agent-command-tab
8
+ Project-URL: Issues, https://github.com/bw2/agent-command-tab/issues
9
+ Keywords: iterm2,claude-code,codex,ai-agents,macos,menu-bar,dashboard
10
+ Classifier: Environment :: MacOS X :: Cocoa
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: Operating System :: MacOS :: MacOS X
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Topic :: Software Development
15
+ Classifier: Topic :: Terminals
16
+ Requires-Python: >=3.10
17
+ Description-Content-Type: text/markdown
18
+ License-File: LICENSE
19
+ Requires-Dist: iterm2<2.31,>=2.30
20
+ Requires-Dist: pyobjc-framework-Cocoa>=10
21
+ Dynamic: license-file
22
+
23
+ <a href="https://github.com/bw2/agent-command-tab/actions/workflows/test.yml"><img src="https://github.com/bw2/agent-command-tab/actions/workflows/test.yml/badge.svg" align="right" alt="unit tests"></a>
24
+
25
+ # AgentCommandTab
26
+
27
+ A macOS menu bar app that lists the iTerm2 windows and tabs, and the tmux sessions and windows, where AI coding agents run (Claude Code, OpenAI Codex CLI, and others), shows what each agent is doing, and lets you rename, focus, reorder and move those tabs without interrupting the agents.
28
+
29
+ ## What it does
30
+
31
+ - **One tree of your agents:** every iTerm2 window and tmux session with at least one agent tab, with its tabs below it, grouped by monitor when you have several. Tabs without an agent are left out.
32
+ - **What each agent is doing:** a status dot and word per tab (asking a question or for permission, thinking, running a tool, running in the background, done, new, idle, paused, error), the context size in tokens and its share of the context window, and optionally when it started, how long it has run, its memory and CPU use. "Done" stays until you look at the tab, and a Claude Code session is "new" until you send it its first message. The menu bar icon counts the agents waiting for your answer.
33
+ - **Process rows:** a tab whose agent started processes has an arrow that opens a row for each of them (right-click one for Info or Kill). The button at the top right collapses or expands all windows.
34
+ - **Control:** double-click to bring a window or tab to the front; press and hold to peek at a tab; rename in place; drag tabs between windows and windows between monitors; start a new agent window or tab; duplicate a tab; type `/compact` or `/clear` into an agent waiting at its prompt; end an agent's process; pause agents (with every process they started) before going offline and resume them later, per tab, window or monitor from the right-click menu, or for the selected rows with the button at the bottom right. Select several rows (Command-click, Shift-click) to act on all their agents at once (a busy agent gets `/compact` or `/clear` when its turn ends), or to ask them to talk to each other: each gets your note and how to message the others.
35
+ - **Saved sessions:** save Claude Code and Codex sessions before a reboot, or to come back to them later: right-click a tab row for "Save session", or a window or monitor row, or one of several selected rows, for "Save 3 sessions" (with the number it can save). "Restore sessions…", right below it (grayed out until something is saved) and in the menu bar icon's right-click menu once something is saved, opens the Saved sessions window: the saved sessions under the windows they were saved from, to restore, rename (double-click a name, or select its row and press Return, Command-R or Command-Shift-R) or delete. A restored session continues its conversation (`--resume` for Claude Code, `resume` for Codex, after the launch command in Settings) in its own tab when that tab waits at a shell prompt (iTerm2 brings its tabs back after a reboot; a tmux pane counts while its tmux session runs), else in a new tab beside the others of its window, else in a new window. A name you gave a tab or window goes back to it. A restored session leaves the list once its agent runs in its tab; one that couldn't be restored, or whose agent didn't start within 15 seconds, stays, and an alert says why.
36
+ - **Keyboard:** Return shows the selected tab or window, Delete ends its agent (asking first), R, Command-R or Command-Shift-R renames it, the Right and Left arrows open and close a tab's process rows, Command-E or Command-Shift-E collapses or expands all windows, typing a name's first letters selects its row, Command-comma opens Settings, and Esc closes the list.
37
+ - **Sort and filter:** sort by status, name, share of the context window, start time, memory or CPU use, or keep the tab order; hide the idle tabs with one click or Command-I (new ones stay).
38
+ - **Your choice of view:** a dropdown under the menu bar icon, a sidebar that hides at the screen's edge or stays visible (optionally keeping iTerm2 windows out of its way), or a regular window (optionally always on top).
39
+ - **A shortcut from any app:** Shift-Command-Tab (or Command-Fn-Tab, chosen in Settings) shows the list with the first agent waiting for your answer selected (or, while none is, the tab in front), and hides it when pressed again. While macOS's app switcher is open, the keys still go to it.
40
+
41
+ ## Requirements
42
+
43
+ - macOS, with iTerm2 3.7 or later and iTerm2's Python API turned on (iTerm2 > Settings > General > Magic > Enable Python API), or tmux 3.2 or later, or both.
44
+ - Python 3.10 or later (for an install with pip or pipx).
45
+
46
+ ## tmux
47
+
48
+ Agents running inside tmux, in any terminal app, are listed next to iTerm2's. Each tmux session is a window row, labeled "tmux:", and each of its tmux windows a tab row, judged by its first pane (as an iTerm2 tab is). The app reads the default tmux server (the one a plain `tmux` command uses) once a second.
49
+
50
+ Almost everything works as in iTerm2: the states, process rows, /compact and /clear, Talk to Each Other, rename, new tabs and windows, Duplicate, moving a tab within a session or into another session, and Close. Some differences:
51
+
52
+ - tmux doesn't report agent states, so the app takes Claude Code's own report of each session, and for Codex the turn timer on its screen (a Codex approval request doesn't show as asking). Agent tools other than Claude Code and Codex aren't recognized in tmux.
53
+ - A tmux session has no window of its own, so it is listed with the menu-bar monitor and can't be moved to another monitor, and a tab can't move between iTerm2 and tmux.
54
+ - Showing a tab selects it in tmux and switches an attached client to its session, then brings that client's terminal to the front (its iTerm2 tab, or any other terminal app). With no client attached, the app says how to attach one.
55
+ - The app can't tell which tab of a terminal app other than iTerm2 is in front, so a "done" tab whose tmux client runs there stays "done" until you show it from the list.
56
+ - Agents in tmux can't be paused: tmux restarts a stopped pane's shell at once, which would then take the terminal from the agent.
57
+ - Typing into an agent (/compact, /clear, Talk to Each Other) is refused in a tmux window with `synchronize-panes` on, since the keys would reach its other panes too, and while its pane is in copy mode, which would take the keys.
58
+
59
+ ## Install
60
+
61
+ The `python3` that comes with macOS is too old (3.9), so install with pipx, which [Homebrew](https://brew.sh) installs along with a recent Python:
62
+
63
+ ```bash
64
+ brew install pipx
65
+ pipx ensurepath # puts pipx's programs on your PATH; open a new terminal tab afterwards
66
+ pipx install agent-command-tab
67
+ ```
68
+
69
+ Then, once:
70
+
71
+ 1. Turn on iTerm2's Python API: iTerm2 > Settings > General > Magic > Enable Python API.
72
+ 2. Start the app from an iTerm2 tab: `agent-command-tab`. iTerm2 asks whether to let it use the Python API: allow it. From then on, iTerm2 starts the app whenever iTerm2 starts.
73
+ 3. Click the "C" in the menu bar. If the list's bottom bar says the hooks aren't installed, click Install Hooks; for Codex, then type `/hooks` in Codex and approve them. Agent sessions started afterwards report to the app.
74
+ 4. Optionally, for the Shift-Command-Tab shortcut, give iTerm2 the Accessibility permission (System Settings > Privacy & Security > Accessibility).
75
+
76
+ If a Homebrew upgrade removes the Python version that pipx made the app's environment with, the app no longer starts, and a copy still running says in its bottom bar that the hooks can't run. `pipx reinstall agent-command-tab` fixes both.
77
+
78
+ From a clone of this repository:
79
+
80
+ ```bash
81
+ python3 -m venv .venv && .venv/bin/pip install -e .
82
+ ```
83
+
84
+ ## Use
85
+
86
+ ```bash
87
+ agent-command-tab # the menu bar app; restarts itself if iTerm2's connection drops
88
+ agent-command-tab dump-snapshot # prints the current list as JSON
89
+ agent-command-tab install-hooks # adds the app's hooks to Claude Code's and Codex's settings (remove-hooks takes them out)
90
+ agent-command-tab --version # prints the installed version, for bug reports
91
+ ```
92
+
93
+ Click the "C" in the menu bar to see the list, right-click it for Settings. The first time, iTerm2 asks whether to allow the app to use its Python API.
94
+
95
+ From its first start on, iTerm2 starts the app whenever iTerm2 starts: the app adds `AgentCommandTab.scpt` to iTerm2's AutoLaunch folder (`~/Library/Application Support/iTerm2/Scripts/AutoLaunch`), which starts the copy that added it, however you installed it. A script added by another copy is kept while that copy is still installed; once it is uninstalled, the copy you run next adds its own. Started that way, it has iTerm2's permissions, as when you start it from an iTerm2 tab, and writes its output to `~/Library/Logs/agent-command-tab.log`. Turning off Settings > Launch AgentCommandTab whenever iTerm2 is started removes the script. Only one copy runs at a time; starting another prints that one is already running.
96
+
97
+ The app's hooks tell a crashed agent from one that ended normally (its row stays, gray and "exited", for 5 minutes), count Claude Code's background shells and agents, and tell when a Claude Code turn ends while one of those still runs. The list offers to install them (Install Hooks, at its bottom left) while an agent tool in it lacks them. The first time the app changes a settings file, it copies it to `<file>.agent-command-tab-backup`. Sessions started afterwards use them, and Codex asks you to approve them first: type `/hooks` in Codex.
98
+
99
+ The shortcut needs the Accessibility permission (System Settings > Privacy & Security > Accessibility), because it has to see the keys before macOS's app switcher does. macOS gives it to the app that starts AgentCommandTab, so started from iTerm2, turn it on for iTerm2. Until it is on, Settings show a button that opens that page.
100
+
101
+ ## Uninstall
102
+
103
+ pip and pipx remove only the app's own files, so first take out what it added elsewhere:
104
+
105
+ ```bash
106
+ agent-command-tab clean-up-before-uninstalling # stops the app, takes out its hooks and its iTerm2 AutoLaunch script
107
+ pipx uninstall agent-command-tab
108
+ ```
109
+
110
+ Its settings stay in `~/Library/Application Support/agent-command-tab`, and its log in `~/Library/Logs/agent-command-tab.log`.
111
+
112
+ ## Development
113
+
114
+ ```bash
115
+ .venv/bin/python -m unittest discover -s tests -p '*_tests.py'
116
+ ```
117
+
118
+ [dev/RELEASING.md](https://github.com/bw2/agent-command-tab/blob/main/dev/RELEASING.md) describes how to publish a version.
119
+
120
+ ## License
121
+
122
+ MIT; see [LICENSE](https://github.com/bw2/agent-command-tab/blob/main/LICENSE). The app uses iTerm2's `iterm2` Python package, which is licensed GPL-2.0-or-later. pip and pipx install it alongside as a separate package.
@@ -0,0 +1,100 @@
1
+ <a href="https://github.com/bw2/agent-command-tab/actions/workflows/test.yml"><img src="https://github.com/bw2/agent-command-tab/actions/workflows/test.yml/badge.svg" align="right" alt="unit tests"></a>
2
+
3
+ # AgentCommandTab
4
+
5
+ A macOS menu bar app that lists the iTerm2 windows and tabs, and the tmux sessions and windows, where AI coding agents run (Claude Code, OpenAI Codex CLI, and others), shows what each agent is doing, and lets you rename, focus, reorder and move those tabs without interrupting the agents.
6
+
7
+ ## What it does
8
+
9
+ - **One tree of your agents:** every iTerm2 window and tmux session with at least one agent tab, with its tabs below it, grouped by monitor when you have several. Tabs without an agent are left out.
10
+ - **What each agent is doing:** a status dot and word per tab (asking a question or for permission, thinking, running a tool, running in the background, done, new, idle, paused, error), the context size in tokens and its share of the context window, and optionally when it started, how long it has run, its memory and CPU use. "Done" stays until you look at the tab, and a Claude Code session is "new" until you send it its first message. The menu bar icon counts the agents waiting for your answer.
11
+ - **Process rows:** a tab whose agent started processes has an arrow that opens a row for each of them (right-click one for Info or Kill). The button at the top right collapses or expands all windows.
12
+ - **Control:** double-click to bring a window or tab to the front; press and hold to peek at a tab; rename in place; drag tabs between windows and windows between monitors; start a new agent window or tab; duplicate a tab; type `/compact` or `/clear` into an agent waiting at its prompt; end an agent's process; pause agents (with every process they started) before going offline and resume them later, per tab, window or monitor from the right-click menu, or for the selected rows with the button at the bottom right. Select several rows (Command-click, Shift-click) to act on all their agents at once (a busy agent gets `/compact` or `/clear` when its turn ends), or to ask them to talk to each other: each gets your note and how to message the others.
13
+ - **Saved sessions:** save Claude Code and Codex sessions before a reboot, or to come back to them later: right-click a tab row for "Save session", or a window or monitor row, or one of several selected rows, for "Save 3 sessions" (with the number it can save). "Restore sessions…", right below it (grayed out until something is saved) and in the menu bar icon's right-click menu once something is saved, opens the Saved sessions window: the saved sessions under the windows they were saved from, to restore, rename (double-click a name, or select its row and press Return, Command-R or Command-Shift-R) or delete. A restored session continues its conversation (`--resume` for Claude Code, `resume` for Codex, after the launch command in Settings) in its own tab when that tab waits at a shell prompt (iTerm2 brings its tabs back after a reboot; a tmux pane counts while its tmux session runs), else in a new tab beside the others of its window, else in a new window. A name you gave a tab or window goes back to it. A restored session leaves the list once its agent runs in its tab; one that couldn't be restored, or whose agent didn't start within 15 seconds, stays, and an alert says why.
14
+ - **Keyboard:** Return shows the selected tab or window, Delete ends its agent (asking first), R, Command-R or Command-Shift-R renames it, the Right and Left arrows open and close a tab's process rows, Command-E or Command-Shift-E collapses or expands all windows, typing a name's first letters selects its row, Command-comma opens Settings, and Esc closes the list.
15
+ - **Sort and filter:** sort by status, name, share of the context window, start time, memory or CPU use, or keep the tab order; hide the idle tabs with one click or Command-I (new ones stay).
16
+ - **Your choice of view:** a dropdown under the menu bar icon, a sidebar that hides at the screen's edge or stays visible (optionally keeping iTerm2 windows out of its way), or a regular window (optionally always on top).
17
+ - **A shortcut from any app:** Shift-Command-Tab (or Command-Fn-Tab, chosen in Settings) shows the list with the first agent waiting for your answer selected (or, while none is, the tab in front), and hides it when pressed again. While macOS's app switcher is open, the keys still go to it.
18
+
19
+ ## Requirements
20
+
21
+ - macOS, with iTerm2 3.7 or later and iTerm2's Python API turned on (iTerm2 > Settings > General > Magic > Enable Python API), or tmux 3.2 or later, or both.
22
+ - Python 3.10 or later (for an install with pip or pipx).
23
+
24
+ ## tmux
25
+
26
+ Agents running inside tmux, in any terminal app, are listed next to iTerm2's. Each tmux session is a window row, labeled "tmux:", and each of its tmux windows a tab row, judged by its first pane (as an iTerm2 tab is). The app reads the default tmux server (the one a plain `tmux` command uses) once a second.
27
+
28
+ Almost everything works as in iTerm2: the states, process rows, /compact and /clear, Talk to Each Other, rename, new tabs and windows, Duplicate, moving a tab within a session or into another session, and Close. Some differences:
29
+
30
+ - tmux doesn't report agent states, so the app takes Claude Code's own report of each session, and for Codex the turn timer on its screen (a Codex approval request doesn't show as asking). Agent tools other than Claude Code and Codex aren't recognized in tmux.
31
+ - A tmux session has no window of its own, so it is listed with the menu-bar monitor and can't be moved to another monitor, and a tab can't move between iTerm2 and tmux.
32
+ - Showing a tab selects it in tmux and switches an attached client to its session, then brings that client's terminal to the front (its iTerm2 tab, or any other terminal app). With no client attached, the app says how to attach one.
33
+ - The app can't tell which tab of a terminal app other than iTerm2 is in front, so a "done" tab whose tmux client runs there stays "done" until you show it from the list.
34
+ - Agents in tmux can't be paused: tmux restarts a stopped pane's shell at once, which would then take the terminal from the agent.
35
+ - Typing into an agent (/compact, /clear, Talk to Each Other) is refused in a tmux window with `synchronize-panes` on, since the keys would reach its other panes too, and while its pane is in copy mode, which would take the keys.
36
+
37
+ ## Install
38
+
39
+ The `python3` that comes with macOS is too old (3.9), so install with pipx, which [Homebrew](https://brew.sh) installs along with a recent Python:
40
+
41
+ ```bash
42
+ brew install pipx
43
+ pipx ensurepath # puts pipx's programs on your PATH; open a new terminal tab afterwards
44
+ pipx install agent-command-tab
45
+ ```
46
+
47
+ Then, once:
48
+
49
+ 1. Turn on iTerm2's Python API: iTerm2 > Settings > General > Magic > Enable Python API.
50
+ 2. Start the app from an iTerm2 tab: `agent-command-tab`. iTerm2 asks whether to let it use the Python API: allow it. From then on, iTerm2 starts the app whenever iTerm2 starts.
51
+ 3. Click the "C" in the menu bar. If the list's bottom bar says the hooks aren't installed, click Install Hooks; for Codex, then type `/hooks` in Codex and approve them. Agent sessions started afterwards report to the app.
52
+ 4. Optionally, for the Shift-Command-Tab shortcut, give iTerm2 the Accessibility permission (System Settings > Privacy & Security > Accessibility).
53
+
54
+ If a Homebrew upgrade removes the Python version that pipx made the app's environment with, the app no longer starts, and a copy still running says in its bottom bar that the hooks can't run. `pipx reinstall agent-command-tab` fixes both.
55
+
56
+ From a clone of this repository:
57
+
58
+ ```bash
59
+ python3 -m venv .venv && .venv/bin/pip install -e .
60
+ ```
61
+
62
+ ## Use
63
+
64
+ ```bash
65
+ agent-command-tab # the menu bar app; restarts itself if iTerm2's connection drops
66
+ agent-command-tab dump-snapshot # prints the current list as JSON
67
+ agent-command-tab install-hooks # adds the app's hooks to Claude Code's and Codex's settings (remove-hooks takes them out)
68
+ agent-command-tab --version # prints the installed version, for bug reports
69
+ ```
70
+
71
+ Click the "C" in the menu bar to see the list, right-click it for Settings. The first time, iTerm2 asks whether to allow the app to use its Python API.
72
+
73
+ From its first start on, iTerm2 starts the app whenever iTerm2 starts: the app adds `AgentCommandTab.scpt` to iTerm2's AutoLaunch folder (`~/Library/Application Support/iTerm2/Scripts/AutoLaunch`), which starts the copy that added it, however you installed it. A script added by another copy is kept while that copy is still installed; once it is uninstalled, the copy you run next adds its own. Started that way, it has iTerm2's permissions, as when you start it from an iTerm2 tab, and writes its output to `~/Library/Logs/agent-command-tab.log`. Turning off Settings > Launch AgentCommandTab whenever iTerm2 is started removes the script. Only one copy runs at a time; starting another prints that one is already running.
74
+
75
+ The app's hooks tell a crashed agent from one that ended normally (its row stays, gray and "exited", for 5 minutes), count Claude Code's background shells and agents, and tell when a Claude Code turn ends while one of those still runs. The list offers to install them (Install Hooks, at its bottom left) while an agent tool in it lacks them. The first time the app changes a settings file, it copies it to `<file>.agent-command-tab-backup`. Sessions started afterwards use them, and Codex asks you to approve them first: type `/hooks` in Codex.
76
+
77
+ The shortcut needs the Accessibility permission (System Settings > Privacy & Security > Accessibility), because it has to see the keys before macOS's app switcher does. macOS gives it to the app that starts AgentCommandTab, so started from iTerm2, turn it on for iTerm2. Until it is on, Settings show a button that opens that page.
78
+
79
+ ## Uninstall
80
+
81
+ pip and pipx remove only the app's own files, so first take out what it added elsewhere:
82
+
83
+ ```bash
84
+ agent-command-tab clean-up-before-uninstalling # stops the app, takes out its hooks and its iTerm2 AutoLaunch script
85
+ pipx uninstall agent-command-tab
86
+ ```
87
+
88
+ Its settings stay in `~/Library/Application Support/agent-command-tab`, and its log in `~/Library/Logs/agent-command-tab.log`.
89
+
90
+ ## Development
91
+
92
+ ```bash
93
+ .venv/bin/python -m unittest discover -s tests -p '*_tests.py'
94
+ ```
95
+
96
+ [dev/RELEASING.md](https://github.com/bw2/agent-command-tab/blob/main/dev/RELEASING.md) describes how to publish a version.
97
+
98
+ ## License
99
+
100
+ MIT; see [LICENSE](https://github.com/bw2/agent-command-tab/blob/main/LICENSE). The app uses iTerm2's `iterm2` Python package, which is licensed GPL-2.0-or-later. pip and pipx install it alongside as a separate package.
@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
5
5
  [project]
6
6
  name = "agent-command-tab"
7
7
  dynamic = ["version"] # agent_command_tab.__version__
8
- description = "macOS menu bar list, window or screen-edge sidebar of the iTerm2 tabs where AI coding agents run"
8
+ description = "macOS menu bar list, window or screen-edge sidebar of the iTerm2 tabs and tmux windows where AI coding agents run"
9
9
  readme = "README.md"
10
10
  license = "MIT"
11
11
  license-files = ["LICENSE"]
@@ -18,7 +18,6 @@ dependencies = [
18
18
  ]
19
19
  keywords = ["iterm2", "claude-code", "codex", "ai-agents", "macos", "menu-bar", "dashboard"]
20
20
  classifiers = [
21
- "Development Status :: 3 - Alpha",
22
21
  "Environment :: MacOS X :: Cocoa",
23
22
  "Intended Audience :: Developers",
24
23
  "Operating System :: MacOS :: MacOS X",
@@ -1,4 +1,4 @@
1
1
  """AgentCommandTab: a macOS menu bar list of the iTerm2 tabs where AI coding agents run."""
2
2
 
3
3
  # The one place the version is set: pyproject.toml reads it from here, and so does `agent-command-tab --version`.
4
- __version__ = "0.2.0"
4
+ __version__ = "0.4.0"
@@ -26,6 +26,13 @@ def list_agent_tool_names_whose_sessions_can_talk_to_each_other():
26
26
  if adapter.how_other_agent_sessions_send_it_messages)
27
27
 
28
28
 
29
+ def list_agent_tool_names_whose_conversations_can_be_resumed():
30
+ """Returns the names of the built-in tools whose sessions Save session can save (can_resume_conversations)."""
31
+ specific_adapters, generic_adapter = build_built_in_agent_tool_adapters()
32
+ return frozenset(adapter.agent_tool_name for adapter in [*specific_adapters, generic_adapter]
33
+ if adapter.can_resume_conversations)
34
+
35
+
29
36
  def find_agent_tool_adapter_for_tab(command_line, iterm2_status_value, specific_adapters, generic_adapter):
30
37
  """Returns the adapter for a tab's first pane, or None when the tab runs no agent.
31
38
 
@@ -1,6 +1,7 @@
1
1
  """What every agent tool adapter provides."""
2
2
 
3
3
  import os
4
+ import re
4
5
  import shlex
5
6
 
6
7
  SHELL_PROGRAM_NAMES = {"sh", "bash", "zsh", "fish", "dash", "ksh", "tcsh", "csh", "nu", "xonsh", "elvish"}
@@ -9,11 +10,38 @@ SHELL_PROGRAM_NAMES = {"sh", "bash", "zsh", "fish", "dash", "ksh", "tcsh", "csh"
9
10
  COMMAND_THAT_STARTS_A_NEW_CONVERSATION = "/clear"
10
11
  # The slash commands of Claude Code and Codex alike, in menu order.
11
12
  COMPACT_AND_CLEAR_SLASH_COMMANDS = ("/compact", COMMAND_THAT_STARTS_A_NEW_CONVERSATION)
12
- # How other agent sessions send a tool's sessions messages ("Talk to Each Other"; user request,
13
- # 2026-10-21): Claude Code's SendMessage tool, addressed by the session's name, which only Claude
13
+ # How other agent sessions send a tool's sessions messages ("Talk to Each Other"): Claude Code's SendMessage
14
+ # tool, addressed by the session's name, which only Claude
14
15
  # Code sessions have; or `codex queue --thread <conversation ID>`, which any agent with a shell can run.
15
16
  MESSAGES_THROUGH_THE_SEND_MESSAGE_TOOL = "send_message_tool"
16
17
  MESSAGES_THROUGH_CODEX_QUEUE = "codex_queue"
18
+ # One "NAME=value " word in front of a launch command's program, the value maybe quoted
19
+ # ("ANTHROPIC_MODEL=x CLAUDE_CONFIG_DIR=~/.claude_work claude").
20
+ LEADING_ENVIRONMENT_SETTING_PATTERN = re.compile(r"""([A-Za-z_][A-Za-z0-9_]*)=(?:'[^']*'|"(?:[^"\\]|\\.)*"|\\.|[^\s'"\\])*\s+""")
21
+
22
+
23
+ def remove_environment_settings_from_launch_command(launch_command, variable_name):
24
+ """Returns the launch command without the <variable_name>=... words in front of its program
25
+ (CLAUDE_CONFIG_DIR, CODEX_HOME), keeping its other environment settings, so a setting put in
26
+ front of it isn't overridden by the launch command's own."""
27
+ kept_settings = []
28
+ rest = launch_command.lstrip()
29
+ while (match := LEADING_ENVIRONMENT_SETTING_PATTERN.match(rest)):
30
+ if match.group(1) != variable_name:
31
+ kept_settings.append(match.group(0))
32
+ rest = rest[match.end():]
33
+ return "".join(kept_settings) + rest
34
+
35
+
36
+ def split_command_line_into_words(command_line):
37
+ """Returns the words of a command line (iTerm2's `commandLine` variable for a session, or
38
+ None), possibly none. Unbalanced quotes fall back to splitting on spaces."""
39
+ if not command_line:
40
+ return []
41
+ try:
42
+ return shlex.split(command_line)
43
+ except ValueError:
44
+ return command_line.split()
17
45
 
18
46
 
19
47
  def split_command_line_into_program_names(command_line):
@@ -28,13 +56,7 @@ def split_command_line_into_program_names(command_line):
28
56
  Returns:
29
57
  A list of base names, possibly empty.
30
58
  """
31
- if not command_line:
32
- return []
33
- try:
34
- words = shlex.split(command_line)
35
- except ValueError:
36
- words = command_line.split()
37
- return [os.path.basename(word).lstrip("-") for word in words]
59
+ return [os.path.basename(word).lstrip("-") for word in split_command_line_into_words(command_line)]
38
60
 
39
61
 
40
62
  def command_line_runs_a_shell(command_line):
@@ -43,6 +65,17 @@ def command_line_runs_a_shell(command_line):
43
65
  return bool(program_names) and program_names[0] in SHELL_PROGRAM_NAMES
44
66
 
45
67
 
68
+ def command_line_is_a_shell_with_no_script_or_command(command_line):
69
+ """Returns whether the foreground job described by command_line is a shell started with
70
+ nothing to run (`-zsh`, `/bin/bash`, `zsh -l`, `bash --login`), so it waits at its prompt for
71
+ what is typed into it. Unlike command_line_runs_a_shell, not `bash job.sh` or `zsh -c '...'`; a
72
+ script with a `#!/bin/bash` line runs as `/bin/bash ./job.sh`. To be safe, any option other
73
+ than login and interactive (-l, -i, --login, --interactive) counts as running something."""
74
+ return command_line_runs_a_shell(command_line) and all(
75
+ word in ("--login", "--interactive") or re.fullmatch(r"-[il]+", word)
76
+ for word in split_command_line_into_words(command_line)[1:])
77
+
78
+
46
79
  class AgentToolAdapter:
47
80
  """Describes one agent tool. Subclasses set the class attributes and may override methods.
48
81
 
@@ -50,8 +83,6 @@ class AgentToolAdapter:
50
83
  agent_tool_name: The name shown in the list, for example "Claude Code".
51
84
  permission_dialog_screen_patterns: Compiled patterns that all appear while the tool's
52
85
  permission dialog is showing; empty when the tool's own status already covers it.
53
- progress_noise_patterns: Compiled patterns for screen text that changes every second
54
- without real progress (screen_readings.compute_screen_fingerprint).
55
86
  interrupted_turn_screen_pattern: Compiled pattern for the line the tool prints when a
56
87
  permission prompt is denied or the turn is interrupted, or None.
57
88
  helper_process_names: Names of processes the tool starts for itself during a turn, which
@@ -75,11 +106,12 @@ class AgentToolAdapter:
75
106
  later; None when the tool prints none.
76
107
  how_other_agent_sessions_send_it_messages: MESSAGES_THROUGH_THE_SEND_MESSAGE_TOOL,
77
108
  MESSAGES_THROUGH_CODEX_QUEUE, or None when other sessions have no way to.
109
+ can_resume_conversations: Whether a saved session of the tool can be resumed later
110
+ (build_launch_command_to_resume; Save session).
78
111
  """
79
112
 
80
113
  agent_tool_name = ""
81
114
  permission_dialog_screen_patterns = ()
82
- progress_noise_patterns = ()
83
115
  interrupted_turn_screen_pattern = None
84
116
  helper_process_names = frozenset()
85
117
  slash_commands = ()
@@ -90,6 +122,7 @@ class AgentToolAdapter:
90
122
  queues_slash_commands_typed_during_a_turn = False
91
123
  slash_command_refused_during_a_turn_pattern = None
92
124
  how_other_agent_sessions_send_it_messages = None
125
+ can_resume_conversations = False
93
126
 
94
127
  async def find_conversation_id(self, agent_process_id, claude_agent_record):
95
128
  """Returns the ID of the conversation the agent process is in, or None if unknown.
@@ -100,6 +133,11 @@ class AgentToolAdapter:
100
133
  """
101
134
  return None
102
135
 
136
+ async def find_conversation_ids_it_may_be_in(self, agent_process_id):
137
+ """Returns the IDs of the conversations the agent process may be in when find_conversation_id
138
+ can't tell which one it is in: none, unless the tool overrides it."""
139
+ return []
140
+
103
141
  async def find_conversation_file(self, agent_process_id, claude_agent_record, claude_config_folders):
104
142
  """Returns the path of the file the tool writes the conversation to, or None if unknown.
105
143
  Runs on the core's event loop, so a lookup that reads folders or files does that in a
@@ -133,12 +171,23 @@ class AgentToolAdapter:
133
171
  """Returns when the current turn began, from the conversation file, or None."""
134
172
  return None
135
173
 
136
- def read_preview_fields(self, conversation_file_path):
137
- """Returns the conversation's last prompt, what the agent said since and its open tool
138
- call (session_preview_computation), or None. Called in a worker thread."""
174
+ def read_turn_is_under_way(self, conversation_file_path):
175
+ """Returns whether the conversation file shows a turn under way, or None when it can't
176
+ tell. Called in a worker thread."""
139
177
  return None
140
178
 
141
- def build_launch_command_for_a_copy(self, launch_command, conversation_id, claude_agent_record=None):
179
+ def read_turns_run_outside_the_tab(self, conversation_file_path):
180
+ """Returns whether the conversation's turns and commands run in a process outside the
181
+ tab (Codex's shared background server), which a pause of the tab's processes can't stop.
182
+ Called in a worker thread."""
183
+ return False
184
+
185
+ def read_open_tool_call(self, conversation_file_path):
186
+ """Returns the tool call the agent waits on, from the end of the conversation file
187
+ (open_tool_call_reading), or None. Called in a worker thread."""
188
+ return None
189
+
190
+ def build_launch_command_for_a_copy(self, launch_command, conversation_id, claude_agent_record=None, codex_home_folder=None):
142
191
  """Returns the command that starts a copy of a session (Duplicate): one that continues a
143
192
  copy of the conversation where the tool can fork it, else a fresh session.
144
193
 
@@ -146,9 +195,27 @@ class AgentToolAdapter:
146
195
  launch_command: The tool's launch command from the settings.
147
196
  conversation_id: From find_conversation_id, or None.
148
197
  claude_agent_record: The original's record from `claude agents --json`, or None.
198
+ codex_home_folder: For Codex, the original's CODEX_HOME, or None when not known.
149
199
  """
150
200
  return launch_command
151
201
 
202
+ def build_launch_command_to_resume(self, launch_command, conversation_id, claude_config_folder=None, codex_home_folder=None):
203
+ """Returns the command that resumes a saved conversation (can_resume_conversations only).
204
+ Each tool uses its own folder argument.
205
+
206
+ Args:
207
+ launch_command: The tool's launch command from the settings.
208
+ conversation_id: The saved conversation's ID.
209
+ claude_config_folder: The Claude Code config folder it ran with, or None for the default.
210
+ codex_home_folder: The CODEX_HOME a Codex conversation ran with, or None when not known
211
+ (the launch command's own then applies).
212
+ """
213
+ raise NotImplementedError
214
+
215
+ def find_codex_home_folder_of_process(self, agent_process_id):
216
+ """Returns the CODEX_HOME of a Codex process (codex.CodexAdapter's); None for other tools."""
217
+ return None
218
+
152
219
  def matches_command_line(self, command_line):
153
220
  """Returns whether a tab whose foreground job has this command line runs this tool.
154
221
 
@@ -7,19 +7,17 @@ import re
7
7
  import shlex
8
8
 
9
9
  from agent_command_tab.agent_adapters.base import (COMPACT_AND_CLEAR_SLASH_COMMANDS, MESSAGES_THROUGH_THE_SEND_MESSAGE_TOOL,
10
- AgentToolAdapter, split_command_line_into_program_names)
10
+ AgentToolAdapter, remove_environment_settings_from_launch_command,
11
+ split_command_line_into_program_names)
11
12
  from agent_command_tab.agent_process_tree import read_process_arguments_and_environment
12
13
  from agent_command_tab.context_window_usage import (choose_claude_code_context_window_tokens, find_claude_code_transcript,
13
14
  read_claude_code_model_setting,
14
15
  read_context_tokens_from_claude_code_transcript,
15
16
  read_model_from_claude_code_transcript,
16
17
  read_turn_started_at_from_claude_code_transcript)
17
- from agent_command_tab.session_preview_computation import read_preview_fields_from_claude_code_transcript
18
+ from agent_command_tab.open_tool_call_reading import read_open_tool_call_from_claude_code_transcript
18
19
 
19
- ELAPSED_TIME = r"(?:\d+h )?(?:\d+m )?\d+s"
20
- # One "NAME=value " word in front of a launch command's program, the value maybe quoted
21
- # ("ANTHROPIC_MODEL=x CLAUDE_CONFIG_DIR=~/.claude_work claude").
22
- LEADING_ENVIRONMENT_SETTING_PATTERN = re.compile(r"""([A-Za-z_][A-Za-z0-9_]*)=(?:'[^']*'|"(?:[^"\\]|\\.)*"|\\.|[^\s'"\\])*\s+""")
20
+ DEFAULT_CLAUDE_CONFIG_FOLDER = os.path.expanduser("~/.claude") # the one a Claude Code without CLAUDE_CONFIG_DIR uses
23
21
 
24
22
 
25
23
  def list_claude_config_folders():
@@ -30,22 +28,15 @@ def list_claude_config_folders():
30
28
  by `claude agents --json`, which lists a session only from its own folder, and by the hooks
31
29
  installer, since such a session reads only its own folder's settings.json.
32
30
  """
33
- default_folder = os.path.expanduser("~/.claude")
34
31
  other_folders = ([os.environ["CLAUDE_CONFIG_DIR"]] if os.environ.get("CLAUDE_CONFIG_DIR") else []) + sorted(
35
32
  folder for folder in glob.glob(os.path.expanduser("~/.claude*")) if os.path.isdir(os.path.join(folder, "sessions")))
36
- return [None] + [folder for folder in dict.fromkeys(other_folders) if os.path.realpath(folder) != os.path.realpath(default_folder)]
33
+ return [None] + [folder for folder in dict.fromkeys(other_folders)
34
+ if os.path.realpath(folder) != os.path.realpath(DEFAULT_CLAUDE_CONFIG_FOLDER)]
37
35
 
38
36
 
39
- def remove_config_folder_settings_from_launch_command(launch_command):
40
- """Returns the launch command without the CLAUDE_CONFIG_DIR=... words in front of its
41
- program, keeping its other environment settings."""
42
- kept_settings = []
43
- rest = launch_command.lstrip()
44
- while (match := LEADING_ENVIRONMENT_SETTING_PATTERN.match(rest)):
45
- if match.group(1) != "CLAUDE_CONFIG_DIR":
46
- kept_settings.append(match.group(0))
47
- rest = rest[match.end():]
48
- return "".join(kept_settings) + rest
37
+ def list_claude_config_folder_paths():
38
+ """Returns list_claude_config_folders's folders, the default one by its path."""
39
+ return [folder or DEFAULT_CLAUDE_CONFIG_FOLDER for folder in list_claude_config_folders()]
49
40
 
50
41
 
51
42
  class ClaudeCodeAdapter(AgentToolAdapter):
@@ -59,21 +50,16 @@ class ClaudeCodeAdapter(AgentToolAdapter):
59
50
  # "allow Claude to fetch this content?" in 2.1.303) above an "Esc to cancel" hint.
60
51
  permission_dialog_screen_patterns = (re.compile(r"Do you want to .+\?"), re.compile(r"Esc to cancel"))
61
52
  interrupted_turn_screen_pattern = re.compile(r"Interrupted · What should Claude do instead\?")
62
- progress_noise_patterns = (
63
- re.compile(r"^\s*[✳✶✢✻✽✺·*⏺]\s"), # the spinner glyph, and the tool line's blinking bullet
64
- re.compile(r"\(" + ELAPSED_TIME + r"(?: · [↓↑] [\d.,]+k? tokens)?\)"), # "(5s · ↓ 97 tokens)", "(4s)"
65
- re.compile(r" · " + ELAPSED_TIME + r"\b"), # the tool line's " · 4s"
66
- re.compile(r"\(ctrl\+b to run in background\)"),
67
- )
68
53
  helper_process_names = frozenset({"caffeinate"}) # keeps the Mac awake while a turn runs
69
54
  slash_commands = COMPACT_AND_CLEAR_SLASH_COMMANDS
70
- # The input box: "❯" and a no-break space, then the input, between two rules of "─" (Phase 0).
55
+ # The input box: "❯" and a no-break space, then the input, between two rules of "─".
71
56
  input_line_marker = "❯"
72
57
  input_area_end_pattern = re.compile(r"^─{10,}\s*$")
73
- # Checked live with Claude Code 2.1.307 on 2026-10-21: /compact and /clear typed during a turn
58
+ # Checked live with Claude Code 2.1.307: /compact and /clear typed during a turn
74
59
  # showed under "Press up to edit queued messages" and ran when the turn ended.
75
60
  queues_slash_commands_typed_during_a_turn = True
76
61
  how_other_agent_sessions_send_it_messages = MESSAGES_THROUGH_THE_SEND_MESSAGE_TOOL
62
+ can_resume_conversations = True
77
63
 
78
64
  def matches_command_line(self, command_line):
79
65
  """Returns whether the command line's program is `claude` (by base name, so full paths match)."""
@@ -90,7 +76,7 @@ class ClaudeCodeAdapter(AgentToolAdapter):
90
76
  conversation_id = await self.find_conversation_id(agent_process_id, claude_agent_record)
91
77
  if not conversation_id:
92
78
  return None
93
- own_config_folder = (claude_agent_record or {}).get("config_folder") or os.path.expanduser("~/.claude")
79
+ own_config_folder = (claude_agent_record or {}).get("config_folder") or DEFAULT_CLAUDE_CONFIG_FOLDER
94
80
  return await asyncio.to_thread(find_claude_code_transcript, [own_config_folder, *claude_config_folders], conversation_id)
95
81
 
96
82
  def read_context_tokens(self, conversation_file_path):
@@ -98,23 +84,28 @@ class ClaudeCodeAdapter(AgentToolAdapter):
98
84
 
99
85
  def read_context_window_tokens(self, conversation_file_path, agent_process_id, claude_agent_record, context_tokens):
100
86
  return choose_claude_code_context_window_tokens(read_claude_code_model_setting(
101
- *read_process_arguments_and_environment(agent_process_id), (claude_agent_record or {}).get("config_folder")),
87
+ *read_process_arguments_and_environment(agent_process_id),
88
+ (claude_agent_record or {}).get("config_folder") or DEFAULT_CLAUDE_CONFIG_FOLDER),
102
89
  read_model_from_claude_code_transcript(conversation_file_path), context_tokens)
103
90
 
104
91
  def read_turn_started_at(self, conversation_file_path):
105
92
  return read_turn_started_at_from_claude_code_transcript(conversation_file_path)
106
93
 
107
- def read_preview_fields(self, conversation_file_path):
108
- return read_preview_fields_from_claude_code_transcript(conversation_file_path)
94
+ def read_open_tool_call(self, conversation_file_path):
95
+ return read_open_tool_call_from_claude_code_transcript(conversation_file_path)
109
96
 
110
- def build_launch_command_for_a_copy(self, launch_command, conversation_id, claude_agent_record=None):
97
+ def build_launch_command_for_a_copy(self, launch_command, conversation_id, claude_agent_record=None, codex_home_folder=None):
111
98
  """Continues a copy of the conversation under a new session ID (`--resume <id> --fork-session`),
112
- in the original's config folder (Claude Code finds the conversation only there): a
113
- CLAUDE_CONFIG_DIR set in front of the launch command gives way to the original's folder,
114
- or to none for an original in the default folder."""
99
+ in the original's config folder (build_launch_command_to_resume)."""
115
100
  if not conversation_id:
116
101
  return launch_command
117
- config_folder = (claude_agent_record or {}).get("config_folder")
118
- environment_prefix = f"CLAUDE_CONFIG_DIR={shlex.quote(config_folder)} " if config_folder else ""
119
- return (f"{environment_prefix}{remove_config_folder_settings_from_launch_command(launch_command)}"
120
- f" --resume {shlex.quote(conversation_id)} --fork-session")
102
+ return self.build_launch_command_to_resume(launch_command, conversation_id,
103
+ (claude_agent_record or {}).get("config_folder")) + " --fork-session"
104
+
105
+ def build_launch_command_to_resume(self, launch_command, conversation_id, claude_config_folder=None, codex_home_folder=None):
106
+ """`<launch command> --resume <id>`, in the conversation's config folder (Claude Code finds
107
+ the conversation only there): a CLAUDE_CONFIG_DIR set in front of the launch command gives
108
+ way to that folder, or to none for a conversation in the default folder."""
109
+ environment_prefix = f"CLAUDE_CONFIG_DIR={shlex.quote(claude_config_folder)} " if claude_config_folder else ""
110
+ return (f"{environment_prefix}{remove_environment_settings_from_launch_command(launch_command, 'CLAUDE_CONFIG_DIR')}"
111
+ f" --resume {shlex.quote(conversation_id)}")