agent-command-tab 0.1.0__tar.gz → 0.3.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.
- agent_command_tab-0.3.0/PKG-INFO +120 -0
- agent_command_tab-0.3.0/README.md +98 -0
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/pyproject.toml +1 -2
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/__init__.py +1 -1
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/agent_adapters/__init__.py +1 -1
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/agent_adapters/claude_code.py +3 -3
- agent_command_tab-0.3.0/src/agent_command_tab/agent_input_box_typing.py +96 -0
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/agent_process_tree.py +135 -4
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/agent_session_pausing.py +68 -57
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/app_controller.py +232 -69
- agent_command_tab-0.3.0/src/agent_command_tab/command_line.py +324 -0
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/context_window_usage.py +77 -23
- agent_command_tab-0.1.0/src/agent_command_tab/iterm2_connection_thread.py → agent_command_tab-0.3.0/src/agent_command_tab/dashboard_core.py +806 -578
- agent_command_tab-0.3.0/src/agent_command_tab/dashboard_core_api.py +41 -0
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/hook_event_forwarder.py +14 -10
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/hook_event_tracking.py +87 -5
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/hook_states_store.py +10 -2
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/hooks_installer.py +45 -8
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/list_sorting.py +5 -10
- agent_command_tab-0.3.0/src/agent_command_tab/login_shell_environment.py +86 -0
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/messages_between_agent_sessions.py +4 -3
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/session_status_computation.py +45 -10
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/settings_store.py +60 -50
- agent_command_tab-0.1.0/src/agent_command_tab/iterm2_snapshot_builder.py → agent_command_tab-0.3.0/src/agent_command_tab/snapshot_builder.py +52 -23
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/snapshot_data_classes.py +35 -8
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/start_with_iterm2.py +5 -3
- agent_command_tab-0.3.0/src/agent_command_tab/terminal_backends/__init__.py +1 -0
- agent_command_tab-0.3.0/src/agent_command_tab/terminal_backends/base.py +207 -0
- agent_command_tab-0.3.0/src/agent_command_tab/terminal_backends/iterm2_terminal_backend.py +686 -0
- agent_command_tab-0.3.0/src/agent_command_tab/terminal_backends/tmux_terminal_backend.py +595 -0
- agent_command_tab-0.3.0/src/agent_command_tab/unix_socket_listeners.py +18 -0
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/user_interface/agent_session_outline_view.py +779 -124
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/user_interface/named_colors.py +13 -3
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/user_interface/popover_container.py +144 -79
- agent_command_tab-0.3.0/src/agent_command_tab/user_interface/process_info_alert.py +121 -0
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/user_interface/row_text_rendering.py +16 -15
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/user_interface/settings_window.py +146 -22
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/user_interface/sidebar_panel.py +15 -8
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/user_interface/sidebar_placement.py +2 -1
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/window_list_ordering.py +14 -7
- agent_command_tab-0.3.0/src/agent_command_tab.egg-info/PKG-INFO +120 -0
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab.egg-info/SOURCES.txt +10 -4
- agent_command_tab-0.1.0/PKG-INFO +0 -85
- agent_command_tab-0.1.0/README.md +0 -62
- agent_command_tab-0.1.0/src/agent_command_tab/command_line.py +0 -187
- agent_command_tab-0.1.0/src/agent_command_tab/dashboard_core_api.py +0 -57
- agent_command_tab-0.1.0/src/agent_command_tab/iterm2_actions.py +0 -325
- agent_command_tab-0.1.0/src/agent_command_tab/tab_order_computation.py +0 -26
- agent_command_tab-0.1.0/src/agent_command_tab.egg-info/PKG-INFO +0 -85
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/LICENSE +0 -0
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/setup.cfg +0 -0
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/agent_adapters/base.py +0 -0
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/agent_adapters/codex.py +0 -0
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/agent_adapters/generic.py +0 -0
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/claude_code_transcript_records.py +0 -0
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/docked_window_frames_store.py +0 -0
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/global_shortcut_key_filter.py +0 -0
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/installed_copy_paths.py +0 -0
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/monitor_assignment.py +0 -0
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/pause_records_store.py +0 -0
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/screen_readings.py +0 -0
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/session_preview_computation.py +0 -0
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/user_interface/__init__.py +0 -0
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/user_interface/agent_tool_icons.py +0 -0
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/user_interface/app_icon.py +0 -0
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/user_interface/control_helpers.py +0 -0
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/user_interface/list_window.py +0 -0
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/user_interface/menu_bar_status_item.py +0 -0
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/user_interface/pointing_hand_button.py +0 -0
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/user_interface/screen_layout.py +0 -0
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/user_interface/talk_to_each_other_alert.py +0 -0
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab.egg-info/dependency_links.txt +0 -0
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab.egg-info/entry_points.txt +0 -0
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab.egg-info/requires.txt +0 -0
- {agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab.egg-info/top_level.txt +0 -0
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: agent-command-tab
|
|
3
|
+
Version: 0.3.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, stuck, 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
|
+
- **A preview per tab:** what the agent is asking or running, what it said since your last prompt, or that prompt. The tab's arrow opens it, along with a row for each process the agent started (right-click one for Info or Kill).
|
|
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
|
+
- **Keyboard:** Return shows the selected tab or window, Delete ends its agent (asking first), R renames it, the Right and Left arrows open and close a tab's preview, typing a name's first letters selects its row, Command-comma opens Settings, and Esc closes the list.
|
|
36
|
+
- **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).
|
|
37
|
+
- **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).
|
|
38
|
+
- **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.
|
|
39
|
+
|
|
40
|
+
## Requirements
|
|
41
|
+
|
|
42
|
+
- 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.
|
|
43
|
+
- Python 3.10 or later (for an install with pip or pipx).
|
|
44
|
+
|
|
45
|
+
## tmux
|
|
46
|
+
|
|
47
|
+
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.
|
|
48
|
+
|
|
49
|
+
Almost everything works as in iTerm2: the states, previews, process rows, /compact and /clear, Talk to Each Other, pause and resume, rename, new tabs and windows, Duplicate, moving a tab within a session or into another session, and Close. Some differences:
|
|
50
|
+
|
|
51
|
+
- 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.
|
|
52
|
+
- 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.
|
|
53
|
+
- 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.
|
|
54
|
+
- 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.
|
|
55
|
+
- Typing into an agent (/compact, /clear, Talk to Each Other, pause and resume) 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.
|
|
56
|
+
|
|
57
|
+
## Install
|
|
58
|
+
|
|
59
|
+
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:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
brew install pipx
|
|
63
|
+
pipx ensurepath # puts pipx's programs on your PATH; open a new terminal tab afterwards
|
|
64
|
+
pipx install agent-command-tab
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Then, once:
|
|
68
|
+
|
|
69
|
+
1. Turn on iTerm2's Python API: iTerm2 > Settings > General > Magic > Enable Python API.
|
|
70
|
+
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.
|
|
71
|
+
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.
|
|
72
|
+
4. Optionally, for the Shift-Command-Tab shortcut, give iTerm2 the Accessibility permission (System Settings > Privacy & Security > Accessibility).
|
|
73
|
+
|
|
74
|
+
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.
|
|
75
|
+
|
|
76
|
+
From a clone of this repository:
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
python3 -m venv .venv && .venv/bin/pip install -e .
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
## Use
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
agent-command-tab # the menu bar app; restarts itself if iTerm2's connection drops
|
|
86
|
+
agent-command-tab dump-snapshot # prints the current list as JSON
|
|
87
|
+
agent-command-tab install-hooks # adds the app's hooks to Claude Code's and Codex's settings (remove-hooks takes them out)
|
|
88
|
+
agent-command-tab --version # prints the installed version, for bug reports
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
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.
|
|
92
|
+
|
|
93
|
+
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 you ran, however you installed it. 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.
|
|
94
|
+
|
|
95
|
+
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.
|
|
96
|
+
|
|
97
|
+
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.
|
|
98
|
+
|
|
99
|
+
## Uninstall
|
|
100
|
+
|
|
101
|
+
pip and pipx remove only the app's own files, so first take out what it added elsewhere:
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
agent-command-tab clean-up-before-uninstalling # stops the app, takes out its hooks and its iTerm2 AutoLaunch script
|
|
105
|
+
pipx uninstall agent-command-tab
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
Its settings stay in `~/Library/Application Support/agent-command-tab`, and its log in `~/Library/Logs/agent-command-tab.log`.
|
|
109
|
+
|
|
110
|
+
## Development
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
.venv/bin/python -m unittest discover -s tests -p '*_tests.py'
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
[docs/RELEASING.md](https://github.com/bw2/agent-command-tab/blob/main/docs/RELEASING.md) describes how to publish a version.
|
|
117
|
+
|
|
118
|
+
## License
|
|
119
|
+
|
|
120
|
+
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,98 @@
|
|
|
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, stuck, 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
|
+
- **A preview per tab:** what the agent is asking or running, what it said since your last prompt, or that prompt. The tab's arrow opens it, along with a row for each process the agent started (right-click one for Info or Kill).
|
|
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
|
+
- **Keyboard:** Return shows the selected tab or window, Delete ends its agent (asking first), R renames it, the Right and Left arrows open and close a tab's preview, typing a name's first letters selects its row, Command-comma opens Settings, and Esc closes the list.
|
|
14
|
+
- **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).
|
|
15
|
+
- **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).
|
|
16
|
+
- **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.
|
|
17
|
+
|
|
18
|
+
## Requirements
|
|
19
|
+
|
|
20
|
+
- 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.
|
|
21
|
+
- Python 3.10 or later (for an install with pip or pipx).
|
|
22
|
+
|
|
23
|
+
## tmux
|
|
24
|
+
|
|
25
|
+
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.
|
|
26
|
+
|
|
27
|
+
Almost everything works as in iTerm2: the states, previews, process rows, /compact and /clear, Talk to Each Other, pause and resume, rename, new tabs and windows, Duplicate, moving a tab within a session or into another session, and Close. Some differences:
|
|
28
|
+
|
|
29
|
+
- 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.
|
|
30
|
+
- 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.
|
|
31
|
+
- 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.
|
|
32
|
+
- 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.
|
|
33
|
+
- Typing into an agent (/compact, /clear, Talk to Each Other, pause and resume) 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.
|
|
34
|
+
|
|
35
|
+
## Install
|
|
36
|
+
|
|
37
|
+
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:
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
brew install pipx
|
|
41
|
+
pipx ensurepath # puts pipx's programs on your PATH; open a new terminal tab afterwards
|
|
42
|
+
pipx install agent-command-tab
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Then, once:
|
|
46
|
+
|
|
47
|
+
1. Turn on iTerm2's Python API: iTerm2 > Settings > General > Magic > Enable Python API.
|
|
48
|
+
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.
|
|
49
|
+
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.
|
|
50
|
+
4. Optionally, for the Shift-Command-Tab shortcut, give iTerm2 the Accessibility permission (System Settings > Privacy & Security > Accessibility).
|
|
51
|
+
|
|
52
|
+
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.
|
|
53
|
+
|
|
54
|
+
From a clone of this repository:
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
python3 -m venv .venv && .venv/bin/pip install -e .
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## Use
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
agent-command-tab # the menu bar app; restarts itself if iTerm2's connection drops
|
|
64
|
+
agent-command-tab dump-snapshot # prints the current list as JSON
|
|
65
|
+
agent-command-tab install-hooks # adds the app's hooks to Claude Code's and Codex's settings (remove-hooks takes them out)
|
|
66
|
+
agent-command-tab --version # prints the installed version, for bug reports
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
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.
|
|
70
|
+
|
|
71
|
+
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 you ran, however you installed it. 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.
|
|
72
|
+
|
|
73
|
+
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.
|
|
74
|
+
|
|
75
|
+
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.
|
|
76
|
+
|
|
77
|
+
## Uninstall
|
|
78
|
+
|
|
79
|
+
pip and pipx remove only the app's own files, so first take out what it added elsewhere:
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
agent-command-tab clean-up-before-uninstalling # stops the app, takes out its hooks and its iTerm2 AutoLaunch script
|
|
83
|
+
pipx uninstall agent-command-tab
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Its settings stay in `~/Library/Application Support/agent-command-tab`, and its log in `~/Library/Logs/agent-command-tab.log`.
|
|
87
|
+
|
|
88
|
+
## Development
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
.venv/bin/python -m unittest discover -s tests -p '*_tests.py'
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
[docs/RELEASING.md](https://github.com/bw2/agent-command-tab/blob/main/docs/RELEASING.md) describes how to publish a version.
|
|
95
|
+
|
|
96
|
+
## License
|
|
97
|
+
|
|
98
|
+
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",
|
{agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/agent_adapters/__init__.py
RENAMED
|
@@ -33,7 +33,7 @@ def find_agent_tool_adapter_for_tab(command_line, iterm2_status_value, specific_
|
|
|
33
33
|
command_line: iTerm2's `commandLine` for the tab's first session.
|
|
34
34
|
iterm2_status_value: The value iTerm2 set in that session's `status` variable after its
|
|
35
35
|
foreground job started, or None (find_status_set_in_iterm2_since_the_job_started).
|
|
36
|
-
specific_adapters: Adapters tried in order (Claude Code, Codex
|
|
36
|
+
specific_adapters: Adapters tried in order (Claude Code, then Codex).
|
|
37
37
|
generic_adapter: Used when no specific adapter matches, the job is not a shell, and the
|
|
38
38
|
status variable holds a recognized value.
|
|
39
39
|
|
|
@@ -12,6 +12,7 @@ from agent_command_tab.agent_process_tree import read_process_arguments_and_envi
|
|
|
12
12
|
from agent_command_tab.context_window_usage import (choose_claude_code_context_window_tokens, find_claude_code_transcript,
|
|
13
13
|
read_claude_code_model_setting,
|
|
14
14
|
read_context_tokens_from_claude_code_transcript,
|
|
15
|
+
read_model_from_claude_code_transcript,
|
|
15
16
|
read_turn_started_at_from_claude_code_transcript)
|
|
16
17
|
from agent_command_tab.session_preview_computation import read_preview_fields_from_claude_code_transcript
|
|
17
18
|
|
|
@@ -85,8 +86,7 @@ class ClaudeCodeAdapter(AgentToolAdapter):
|
|
|
85
86
|
|
|
86
87
|
async def find_conversation_file(self, agent_process_id, claude_agent_record, claude_config_folders):
|
|
87
88
|
"""Returns the transcript named after the record's `sessionId`: in the record's own config
|
|
88
|
-
folder first
|
|
89
|
-
the config folders."""
|
|
89
|
+
folder first, else in one of the config folders."""
|
|
90
90
|
conversation_id = await self.find_conversation_id(agent_process_id, claude_agent_record)
|
|
91
91
|
if not conversation_id:
|
|
92
92
|
return None
|
|
@@ -99,7 +99,7 @@ class ClaudeCodeAdapter(AgentToolAdapter):
|
|
|
99
99
|
def read_context_window_tokens(self, conversation_file_path, agent_process_id, claude_agent_record, context_tokens):
|
|
100
100
|
return choose_claude_code_context_window_tokens(read_claude_code_model_setting(
|
|
101
101
|
*read_process_arguments_and_environment(agent_process_id), (claude_agent_record or {}).get("config_folder")),
|
|
102
|
-
context_tokens)
|
|
102
|
+
read_model_from_claude_code_transcript(conversation_file_path), context_tokens)
|
|
103
103
|
|
|
104
104
|
def read_turn_started_at(self, conversation_file_path):
|
|
105
105
|
return read_turn_started_at_from_claude_code_transcript(conversation_file_path)
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
"""Typing a slash command into an agent's input box and pasting a message there, in any terminal
|
|
2
|
+
(a terminal_backends.base.TerminalSession): only into an empty box, checked on screen before and
|
|
3
|
+
after, since text typed into a draft would join it."""
|
|
4
|
+
|
|
5
|
+
import asyncio
|
|
6
|
+
|
|
7
|
+
from agent_command_tab.dashboard_core_api import ActionResult
|
|
8
|
+
from agent_command_tab.screen_readings import count_lines_matching, input_area_is_empty, read_typed_input_area_text
|
|
9
|
+
from agent_command_tab.terminal_backends.base import TerminalRequestFailed
|
|
10
|
+
|
|
11
|
+
SECONDS_BEFORE_CHECKING_THAT_A_COMMAND_WAS_SUBMITTED = 0.5 # the box empties within a redraw of the Enter
|
|
12
|
+
SECONDS_BETWEEN_A_PASTE_AND_ITS_ENTER = 0.5 # the pause of the live check (2026-10-21)
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
async def type_slash_command(terminal_session, command, adapter, agent_is_in_the_middle_of_a_turn=False):
|
|
16
|
+
"""Types a slash command into the agent's empty input box, then Enter after the adapter's
|
|
17
|
+
pause. Types nothing when the box
|
|
18
|
+
holds unsent text or can't be found on screen, since the command would join the draft.
|
|
19
|
+
Reports a failure, without retrying, when the command is still in the box a moment after Enter.
|
|
20
|
+
|
|
21
|
+
Args:
|
|
22
|
+
terminal_session: The tab's TerminalSession.
|
|
23
|
+
command: One of the adapter's slash_commands, for example "/compact".
|
|
24
|
+
adapter: The session's agent tool adapter (its input line marker, input area end and pause).
|
|
25
|
+
agent_is_in_the_middle_of_a_turn: Whether the agent is busy (Claude Code queues a command
|
|
26
|
+
typed then). Enter then goes only while the command is still in the box, since the
|
|
27
|
+
agent may open a permission prompt meanwhile, which would take the Enter as its answer;
|
|
28
|
+
otherwise a failure is reported. Not checked for an agent at its prompt, which opens
|
|
29
|
+
no prompt on its own: in a live check on 2026-10-22, Codex's input box couldn't be found
|
|
30
|
+
on screen right after the command was typed (its slash-command menu was open).
|
|
31
|
+
|
|
32
|
+
Returns:
|
|
33
|
+
None when nothing was typed because the box holds unsent text or can't be found on screen,
|
|
34
|
+
or when the agent refused the command because a turn is under way (Codex, whose turn can
|
|
35
|
+
look over on screen while answer text streams); the caller may try again later. Otherwise
|
|
36
|
+
an ActionResult.
|
|
37
|
+
"""
|
|
38
|
+
if command not in adapter.slash_commands:
|
|
39
|
+
return ActionResult(False, f"{command} can't be sent to {adapter.agent_tool_name or 'this agent'}")
|
|
40
|
+
screen_lines_before_typing = await terminal_session.read_screen_lines_with_faint_flags()
|
|
41
|
+
if not input_area_is_empty(screen_lines_before_typing, adapter.input_line_marker, adapter.input_area_end_pattern):
|
|
42
|
+
return None
|
|
43
|
+
await terminal_session.send_text(command)
|
|
44
|
+
await asyncio.sleep(adapter.seconds_before_enter)
|
|
45
|
+
if agent_is_in_the_middle_of_a_turn:
|
|
46
|
+
typed_text = read_typed_input_area_text(await terminal_session.read_screen_lines_with_faint_flags(),
|
|
47
|
+
adapter.input_line_marker, adapter.input_area_end_pattern)
|
|
48
|
+
if typed_text is None or command not in typed_text:
|
|
49
|
+
return ActionResult(False, f"{command} wasn't submitted: the tab's input box changed before Enter")
|
|
50
|
+
await terminal_session.send_text("\r")
|
|
51
|
+
await asyncio.sleep(SECONDS_BEFORE_CHECKING_THAT_A_COMMAND_WAS_SUBMITTED)
|
|
52
|
+
try:
|
|
53
|
+
screen_lines_after_enter = await terminal_session.read_screen_lines_with_faint_flags()
|
|
54
|
+
except TerminalRequestFailed:
|
|
55
|
+
return ActionResult(True) # the tab closed meanwhile
|
|
56
|
+
refusal_pattern = adapter.slash_command_refused_during_a_turn_pattern
|
|
57
|
+
if count_lines_matching([text for text, _ in screen_lines_after_enter], refusal_pattern) > count_lines_matching(
|
|
58
|
+
[text for text, _ in screen_lines_before_typing], refusal_pattern):
|
|
59
|
+
return None
|
|
60
|
+
typed_text = read_typed_input_area_text(screen_lines_after_enter, adapter.input_line_marker, adapter.input_area_end_pattern)
|
|
61
|
+
# A box that is off screen (the tool redrawing) can't be checked; the command was sent.
|
|
62
|
+
if typed_text is not None and command in typed_text:
|
|
63
|
+
return ActionResult(False, f"{command} may not have been submitted: it is still in the tab's input box")
|
|
64
|
+
return ActionResult(True)
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
async def paste_message_into_empty_input_box(terminal_session, message, adapter):
|
|
68
|
+
"""Pastes a message of one or more lines into the agent's empty input box as one bracketed
|
|
69
|
+
paste, then presses Enter ("Talk to Each Other"; checked live with Claude Code 2.1.306 on
|
|
70
|
+
2026-10-21: a three-line message was submitted as one prompt). Reports a failure, without
|
|
71
|
+
retrying, when the box isn't empty a moment after Enter.
|
|
72
|
+
|
|
73
|
+
Args:
|
|
74
|
+
terminal_session: The tab's TerminalSession.
|
|
75
|
+
message: The text to submit.
|
|
76
|
+
adapter: The session's agent tool adapter (its input line marker and input area end).
|
|
77
|
+
|
|
78
|
+
Returns:
|
|
79
|
+
None when nothing was pasted because the box holds unsent text or can't be found on
|
|
80
|
+
screen (the caller may try again later), otherwise an ActionResult.
|
|
81
|
+
"""
|
|
82
|
+
if not input_area_is_empty(await terminal_session.read_screen_lines_with_faint_flags(), adapter.input_line_marker,
|
|
83
|
+
adapter.input_area_end_pattern):
|
|
84
|
+
return None
|
|
85
|
+
await terminal_session.paste_text(message)
|
|
86
|
+
await asyncio.sleep(SECONDS_BETWEEN_A_PASTE_AND_ITS_ENTER)
|
|
87
|
+
await terminal_session.send_text("\r")
|
|
88
|
+
await asyncio.sleep(SECONDS_BEFORE_CHECKING_THAT_A_COMMAND_WAS_SUBMITTED)
|
|
89
|
+
try:
|
|
90
|
+
typed_text = read_typed_input_area_text(await terminal_session.read_screen_lines_with_faint_flags(),
|
|
91
|
+
adapter.input_line_marker, adapter.input_area_end_pattern)
|
|
92
|
+
except TerminalRequestFailed:
|
|
93
|
+
return ActionResult(True) # the tab closed meanwhile
|
|
94
|
+
if typed_text: # None: the box is off screen (the tool redrawing), so it can't be checked
|
|
95
|
+
return ActionResult(False, "the message may not have been submitted: the tab's input box isn't empty after Enter")
|
|
96
|
+
return ActionResult(True)
|
{agent_command_tab-0.1.0 → agent_command_tab-0.3.0}/src/agent_command_tab/agent_process_tree.py
RENAMED
|
@@ -23,7 +23,20 @@ PROC_PIDT_SHORTBSDINFO = 13 # proc_pidinfo flavor that returns struct proc_bsds
|
|
|
23
23
|
STOPPED_PROCESS_STATUS = 4 # SSTOP in <sys/proc.h>, proc_bsdinfo's pbi_status of a stopped process
|
|
24
24
|
PROC_PIDVNODEPATHINFO = 9 # proc_pidinfo flavor that returns struct proc_vnodepathinfo
|
|
25
25
|
VNODE_INFO_SIZE = 152 # sizeof(struct vnode_info); the current folder's path follows it
|
|
26
|
+
PROC_PIDLISTFDS = 1 # proc_pidinfo flavor that returns a struct proc_fdinfo for each open file descriptor
|
|
27
|
+
PROC_FD_INFO_SIZE = 8 # sizeof(struct proc_fdinfo): the descriptor and its type, two 32-bit integers
|
|
28
|
+
PROX_FDTYPE_VNODE = 1 # proc_fdinfo's type of a file or device (not a pipe or a socket)
|
|
29
|
+
PROC_PIDFDVNODEPATHINFO = 2 # proc_pidfdinfo flavor that returns struct vnode_fdinfowithpath
|
|
30
|
+
# sizeof(struct proc_fileinfo), which starts a vnode_fdinfowithpath (its first field, fi_openflags,
|
|
31
|
+
# holds FWRITE when the descriptor was opened for writing); a vnode_info and the path follow.
|
|
32
|
+
PROC_FILE_INFO_SIZE = 24
|
|
33
|
+
FWRITE = 0x0002
|
|
34
|
+
STANDARD_OUTPUT_FILE_DESCRIPTOR = 1
|
|
26
35
|
MAXIMUM_PATH_LENGTH = 1024
|
|
36
|
+
# The file a Claude Code shell writes its output to, named after its task: the ID its hooks list
|
|
37
|
+
# a background shell by (its tool result names the file too, "Output is being written to: ...").
|
|
38
|
+
CLAUDE_CODE_TASK_OUTPUT_FILE = re.compile(r"/tasks/([A-Za-z0-9]+)\.output\Z")
|
|
39
|
+
DEVICES_FOLDER = "/dev/" # a process writing to a terminal or /dev/null writes to a device here, not to a file
|
|
27
40
|
MAXIMUM_CHILD_PROCESSES = 1024
|
|
28
41
|
# Shells and wrappers that agents run commands in: the command's name is the first process
|
|
29
42
|
# below them (python3 rather than the zsh that Claude Code runs it in).
|
|
@@ -45,6 +58,9 @@ CLAUDE_CODE_SHELL_TOOL_COMMAND = re.compile(r"""&& eval '((?:[^']|'"'"')*)'(?: <
|
|
|
45
58
|
# which a process row calls just "scratchpad" (user request, 2026-10-28), so the end of the command shows.
|
|
46
59
|
CLAUDE_CODE_SCRATCHPAD_PATH = re.compile(r"(?:/private)?/tmp/claude-\d+/[^/\s'\"]+/[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}/scratchpad")
|
|
47
60
|
LAUNCHD_PROCESS_ID = 1 # adopts a process whose parent ended
|
|
61
|
+
# Text editors that run in a terminal, which an agent may open in its own process group (Claude
|
|
62
|
+
# Code's Ctrl+G does), besides the one its VISUAL or EDITOR setting names.
|
|
63
|
+
TERMINAL_TEXT_EDITOR_NAMES = frozenset({"vi", "vim", "nvim", "nano", "pico", "emacs", "micro", "hx", "kak", "mg", "joe"})
|
|
48
64
|
|
|
49
65
|
RUSAGE_INFO_V2 = 2 # proc_pid_rusage flavor that returns struct rusage_info_v2
|
|
50
66
|
|
|
@@ -157,6 +173,36 @@ def read_process_current_folder(process_id):
|
|
|
157
173
|
return buffer.raw[VNODE_INFO_SIZE:VNODE_INFO_SIZE + MAXIMUM_PATH_LENGTH].split(b"\0", 1)[0].decode(errors="replace")
|
|
158
174
|
|
|
159
175
|
|
|
176
|
+
def list_the_files_a_process_writes_to(process_id):
|
|
177
|
+
"""Returns {file descriptor: path} for the files and devices a process has open for writing
|
|
178
|
+
(a terminal or /dev/null gives its device's path; pipes and sockets aren't listed), or {} for
|
|
179
|
+
a process that can't be read."""
|
|
180
|
+
needed_size = LIBPROC.proc_pidinfo(process_id, PROC_PIDLISTFDS, ctypes.c_uint64(0), None, 0)
|
|
181
|
+
if needed_size <= 0:
|
|
182
|
+
return {}
|
|
183
|
+
file_descriptor_infos = (ctypes.c_int32 * (2 * (needed_size // PROC_FD_INFO_SIZE)))() # (descriptor, type) pairs
|
|
184
|
+
listed_size = LIBPROC.proc_pidinfo(process_id, PROC_PIDLISTFDS, ctypes.c_uint64(0), file_descriptor_infos,
|
|
185
|
+
ctypes.sizeof(file_descriptor_infos))
|
|
186
|
+
path_info = ctypes.create_string_buffer(PROC_FILE_INFO_SIZE + VNODE_INFO_SIZE + MAXIMUM_PATH_LENGTH)
|
|
187
|
+
paths_by_file_descriptor = {}
|
|
188
|
+
for index in range(max(listed_size, 0) // PROC_FD_INFO_SIZE):
|
|
189
|
+
file_descriptor, file_descriptor_type = file_descriptor_infos[2 * index], file_descriptor_infos[2 * index + 1]
|
|
190
|
+
if (file_descriptor_type == PROX_FDTYPE_VNODE
|
|
191
|
+
and LIBPROC.proc_pidfdinfo(process_id, file_descriptor, PROC_PIDFDVNODEPATHINFO, path_info,
|
|
192
|
+
len(path_info)) == len(path_info)
|
|
193
|
+
and ctypes.c_uint32.from_buffer_copy(path_info.raw[:4]).value & FWRITE):
|
|
194
|
+
paths_by_file_descriptor[file_descriptor] = (
|
|
195
|
+
path_info.raw[PROC_FILE_INFO_SIZE + VNODE_INFO_SIZE:].split(b"\0", 1)[0].decode(errors="replace"))
|
|
196
|
+
return paths_by_file_descriptor
|
|
197
|
+
|
|
198
|
+
|
|
199
|
+
def find_the_claude_code_task_of_an_output_file(output_file_path):
|
|
200
|
+
"""Returns the ID of the Claude Code task an output file is named after
|
|
201
|
+
(CLAUDE_CODE_TASK_OUTPUT_FILE), as the file a shell Claude Code's shell tool runs writes to is, or None."""
|
|
202
|
+
match = CLAUDE_CODE_TASK_OUTPUT_FILE.search(output_file_path)
|
|
203
|
+
return match.group(1) if match else None
|
|
204
|
+
|
|
205
|
+
|
|
160
206
|
def process_is_alive(process_id):
|
|
161
207
|
"""Returns whether a process with this ID exists (one owned by another user counts as alive)."""
|
|
162
208
|
try:
|
|
@@ -245,6 +291,41 @@ def list_other_stopped_jobs_of_the_agents_shell(agent_process_id):
|
|
|
245
291
|
return other_stopped_job_process_ids
|
|
246
292
|
|
|
247
293
|
|
|
294
|
+
def find_foreground_job_process_id(process_id):
|
|
295
|
+
"""Returns the ID of the job in front on the process's terminal (the leader of the terminal's
|
|
296
|
+
foreground process group, as iTerm2's jobPid names it), or process_id itself when the
|
|
297
|
+
process has no terminal or the leader is gone; None when the process is gone. For a tmux
|
|
298
|
+
pane's shell, the program the pane runs in front (user request, 2026-11-01)."""
|
|
299
|
+
bsd_info = read_process_bsd_info(process_id)
|
|
300
|
+
if bsd_info is None:
|
|
301
|
+
return None
|
|
302
|
+
if bsd_info.e_tpgid == 0 or read_process_bsd_info(bsd_info.e_tpgid) is None:
|
|
303
|
+
return process_id
|
|
304
|
+
return bsd_info.e_tpgid
|
|
305
|
+
|
|
306
|
+
|
|
307
|
+
def find_text_editor_opened_by_the_job(job_process_id):
|
|
308
|
+
"""Returns the ID of a text editor below the job in the job's own process group, or None.
|
|
309
|
+
Claude Code's Ctrl+G opens one so: the editor gets the keys, while the terminal's foreground
|
|
310
|
+
group, and so find_foreground_job_process_id, still names the agent (iTerm2's jobPid names
|
|
311
|
+
the editor). Other programs in the group, such as a caffeinate the agent started, don't count."""
|
|
312
|
+
processes_in_the_jobs_group = []
|
|
313
|
+
# Three levels: the agent may run below a wrapper the job started, and the editor in a shell.
|
|
314
|
+
for descendant in list_descendant_processes(job_process_id, maximum_depth=3):
|
|
315
|
+
bsd_info = read_process_bsd_info(descendant.process_id)
|
|
316
|
+
if bsd_info is not None and bsd_info.pbi_pgid == job_process_id:
|
|
317
|
+
processes_in_the_jobs_group.append(descendant)
|
|
318
|
+
if not processes_in_the_jobs_group:
|
|
319
|
+
return None
|
|
320
|
+
editor_names = set(TERMINAL_TEXT_EDITOR_NAMES)
|
|
321
|
+
environment = read_process_arguments_and_environment(job_process_id)[1]
|
|
322
|
+
for setting_name in ("VISUAL", "EDITOR"):
|
|
323
|
+
words = environment.get(setting_name, "").split()
|
|
324
|
+
if words:
|
|
325
|
+
editor_names.add(os.path.basename(words[0]))
|
|
326
|
+
return next((process.process_id for process in processes_in_the_jobs_group if process.name in editor_names), None)
|
|
327
|
+
|
|
328
|
+
|
|
248
329
|
def process_has_its_terminal(process_id):
|
|
249
330
|
"""Returns whether the process's group is its terminal's foreground group, the one that gets
|
|
250
331
|
the keys, as the kernel has it right now (iTerm2's jobPid variable follows only after a while)."""
|
|
@@ -437,9 +518,18 @@ def choose_detached_processes_of_the_conversation(detached_processes, conversati
|
|
|
437
518
|
def read_child_processes(agent_process_id, turn_is_under_way, turn_started_at, reads_resource_usage, now,
|
|
438
519
|
detached_processes_of_the_conversation=()):
|
|
439
520
|
"""Returns [{"child": ProcessInfo, "command_text", "command_started_at", "is_background_shell",
|
|
440
|
-
"is_detached", "
|
|
441
|
-
|
|
442
|
-
|
|
521
|
+
"is_detached", "claude_code_task_id": the ID of the Claude Code task whose output file it writes
|
|
522
|
+
to (find_the_claude_code_task_of_an_output_file), or None,
|
|
523
|
+
"is_a_shell_writing_to_a_file_of_no_claude_code_task": whether it is a shell or wrapper with a
|
|
524
|
+
process running in it, writing to no Claude Code task's file, whose standard output goes to a
|
|
525
|
+
file (not to a pipe, a socket or a device, as Claude Code's Monitor tool's shells write to sockets),
|
|
526
|
+
"is_a_claude_code_monitor_shell": whether it is a shell Claude Code's shell tool runs
|
|
527
|
+
(find_the_command_a_claude_code_shell_runs) whose standard output goes to no file: Claude
|
|
528
|
+
Code's Monitor tool runs its command so, writing to a socket, while every command of its
|
|
529
|
+
Bash tool writes to its task's output file (checked with Claude Code 2.1.316 on 2026-11-03),
|
|
530
|
+
"resource_usage": (memory in bytes, CPU seconds) of the child and the processes below it, or
|
|
531
|
+
None}] for each process the agent started (list_child_processes_of_the_agent), then for each
|
|
532
|
+
detached one (choose_detached_processes_of_the_conversation), which runs in the background.
|
|
443
533
|
A Claude Code shell is named by its command and dated by its own start; another child by the
|
|
444
534
|
command shown and that command's start (a shell Codex keeps between turns is older).
|
|
445
535
|
|
|
@@ -454,6 +544,12 @@ def read_child_processes(agent_process_id, turn_is_under_way, turn_started_at, r
|
|
|
454
544
|
for child, shown_process in list_child_processes_of_the_agent(agent_process_id, list_descendant_processes(agent_process_id), now):
|
|
455
545
|
claude_code_shell_command = find_the_command_a_claude_code_shell_runs(read_process_arguments_and_environment(child.process_id)[0])
|
|
456
546
|
command_started_at = child.started_at if claude_code_shell_command else shown_process.started_at
|
|
547
|
+
# Any file it writes to, not only its standard output: a shell that runs a loop or a { }
|
|
548
|
+
# block with its output sent elsewhere (`done > /dev/null`) keeps its own on another descriptor meanwhile.
|
|
549
|
+
paths_written_to_by_file_descriptor = list_the_files_a_process_writes_to(child.process_id)
|
|
550
|
+
claude_code_task_id = next(filter(None, (find_the_claude_code_task_of_an_output_file(path)
|
|
551
|
+
for _, path in sorted(paths_written_to_by_file_descriptor.items()))), None)
|
|
552
|
+
output_file_path = paths_written_to_by_file_descriptor.get(STANDARD_OUTPUT_FILE_DESCRIPTOR, "")
|
|
457
553
|
child_processes.append({
|
|
458
554
|
"child": child,
|
|
459
555
|
"command_text": (shorten_scratchpad_paths(" ".join(claude_code_shell_command.split())) if claude_code_shell_command
|
|
@@ -463,15 +559,50 @@ def read_child_processes(agent_process_id, turn_is_under_way, turn_started_at, r
|
|
|
463
559
|
"is_background_shell": child_process_is_a_background_shell(child, shown_process, command_started_at,
|
|
464
560
|
turn_is_under_way, turn_started_at),
|
|
465
561
|
"is_detached": False,
|
|
562
|
+
"claude_code_task_id": claude_code_task_id,
|
|
563
|
+
"is_a_shell_writing_to_a_file_of_no_claude_code_task": (
|
|
564
|
+
child.name in SHELL_AND_WRAPPER_PROCESS_NAMES and shown_process is not child and claude_code_task_id is None
|
|
565
|
+
and output_file_path != "" and not output_file_path.startswith(DEVICES_FOLDER)),
|
|
566
|
+
"is_a_claude_code_monitor_shell": claude_code_shell_command is not None and claude_code_task_id is None and output_file_path == "",
|
|
466
567
|
"resource_usage": read_process_tree_resource_usage(child.process_id) if reads_resource_usage else None})
|
|
467
568
|
for process, arguments in detached_processes_of_the_conversation:
|
|
468
569
|
child_processes.append({
|
|
469
570
|
"child": process, "command_text": build_command_text(arguments, process.name), "command_started_at": process.started_at,
|
|
470
|
-
"is_background_shell": True, "is_detached": True,
|
|
571
|
+
"is_background_shell": True, "is_detached": True, "claude_code_task_id": None,
|
|
572
|
+
"is_a_shell_writing_to_a_file_of_no_claude_code_task": False, "is_a_claude_code_monitor_shell": False,
|
|
471
573
|
"resource_usage": read_process_tree_resource_usage(process.process_id) if reads_resource_usage else None})
|
|
472
574
|
return sorted(child_processes, key=lambda child_process: child_process["child"].started_at) # oldest first, detached ones too
|
|
473
575
|
|
|
474
576
|
|
|
577
|
+
def read_process_details(process_id):
|
|
578
|
+
"""Returns what a sub row's Info shows about its process (user request, 2026-10-29), or None
|
|
579
|
+
if it is gone: {"process_id", "command_line": its arguments as ps shows them, "agent_command":
|
|
580
|
+
the command in it as the agent wrote it, for a Claude Code shell, else None, "working_folder"
|
|
581
|
+
("" if unknown), "started_at", "subprocesses": [{"process_id", "command_text"
|
|
582
|
+
(build_command_text's)}] of the processes below it, oldest first (user request, 2026-10-29),
|
|
583
|
+
and "memory_bytes" and "cpu_seconds" (read_process_tree_resource_usage's), its and theirs
|
|
584
|
+
together}. The command line keeps its line breaks, as a command with a heredoc has them."""
|
|
585
|
+
process = read_process_info(process_id)
|
|
586
|
+
resource_usage = read_process_tree_resource_usage(process_id)
|
|
587
|
+
if process is None or resource_usage is None:
|
|
588
|
+
return None
|
|
589
|
+
arguments = read_process_arguments_and_environment(process_id)[0]
|
|
590
|
+
processes_below = sorted(list_descendant_processes(process_id, maximum_depth=None), key=lambda process_below: process_below.started_at)
|
|
591
|
+
return {
|
|
592
|
+
"process_id": process_id,
|
|
593
|
+
"command_line": " ".join(arguments) or process.name,
|
|
594
|
+
"agent_command": find_the_command_a_claude_code_shell_runs(arguments),
|
|
595
|
+
"working_folder": read_process_current_folder(process_id),
|
|
596
|
+
"started_at": process.started_at,
|
|
597
|
+
"subprocesses": [
|
|
598
|
+
{"process_id": process_below.process_id,
|
|
599
|
+
"command_text": build_command_text(read_process_arguments_and_environment(process_below.process_id)[0], process_below.name)}
|
|
600
|
+
for process_below in processes_below],
|
|
601
|
+
"memory_bytes": resource_usage[0],
|
|
602
|
+
"cpu_seconds": resource_usage[1],
|
|
603
|
+
}
|
|
604
|
+
|
|
605
|
+
|
|
475
606
|
def choose_helper_process_ids(descendant_processes):
|
|
476
607
|
"""Returns the IDs of the processes running below an agent between its turns (MCP servers, for
|
|
477
608
|
example), which choose_command_the_agent_is_waiting_on never takes for a command, nor anything
|