agent-command-tab 0.1.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.1.0/LICENSE +21 -0
- agent_command_tab-0.1.0/PKG-INFO +85 -0
- agent_command_tab-0.1.0/README.md +62 -0
- agent_command_tab-0.1.0/pyproject.toml +41 -0
- agent_command_tab-0.1.0/setup.cfg +4 -0
- agent_command_tab-0.1.0/src/agent_command_tab/__init__.py +4 -0
- agent_command_tab-0.1.0/src/agent_command_tab/agent_adapters/__init__.py +48 -0
- agent_command_tab-0.1.0/src/agent_command_tab/agent_adapters/base.py +162 -0
- agent_command_tab-0.1.0/src/agent_command_tab/agent_adapters/claude_code.py +120 -0
- agent_command_tab-0.1.0/src/agent_command_tab/agent_adapters/codex.py +102 -0
- agent_command_tab-0.1.0/src/agent_command_tab/agent_adapters/generic.py +22 -0
- agent_command_tab-0.1.0/src/agent_command_tab/agent_process_tree.py +557 -0
- agent_command_tab-0.1.0/src/agent_command_tab/agent_session_pausing.py +254 -0
- agent_command_tab-0.1.0/src/agent_command_tab/app_controller.py +947 -0
- agent_command_tab-0.1.0/src/agent_command_tab/claude_code_transcript_records.py +75 -0
- agent_command_tab-0.1.0/src/agent_command_tab/command_line.py +187 -0
- agent_command_tab-0.1.0/src/agent_command_tab/context_window_usage.py +230 -0
- agent_command_tab-0.1.0/src/agent_command_tab/dashboard_core_api.py +57 -0
- agent_command_tab-0.1.0/src/agent_command_tab/docked_window_frames_store.py +60 -0
- agent_command_tab-0.1.0/src/agent_command_tab/global_shortcut_key_filter.py +167 -0
- agent_command_tab-0.1.0/src/agent_command_tab/hook_event_forwarder.py +116 -0
- agent_command_tab-0.1.0/src/agent_command_tab/hook_event_tracking.py +129 -0
- agent_command_tab-0.1.0/src/agent_command_tab/hook_states_store.py +60 -0
- agent_command_tab-0.1.0/src/agent_command_tab/hooks_installer.py +300 -0
- agent_command_tab-0.1.0/src/agent_command_tab/installed_copy_paths.py +41 -0
- agent_command_tab-0.1.0/src/agent_command_tab/iterm2_actions.py +325 -0
- agent_command_tab-0.1.0/src/agent_command_tab/iterm2_connection_thread.py +2299 -0
- agent_command_tab-0.1.0/src/agent_command_tab/iterm2_snapshot_builder.py +403 -0
- agent_command_tab-0.1.0/src/agent_command_tab/list_sorting.py +117 -0
- agent_command_tab-0.1.0/src/agent_command_tab/messages_between_agent_sessions.py +78 -0
- agent_command_tab-0.1.0/src/agent_command_tab/monitor_assignment.py +109 -0
- agent_command_tab-0.1.0/src/agent_command_tab/pause_records_store.py +61 -0
- agent_command_tab-0.1.0/src/agent_command_tab/screen_readings.py +108 -0
- agent_command_tab-0.1.0/src/agent_command_tab/session_preview_computation.py +228 -0
- agent_command_tab-0.1.0/src/agent_command_tab/session_status_computation.py +235 -0
- agent_command_tab-0.1.0/src/agent_command_tab/settings_store.py +292 -0
- agent_command_tab-0.1.0/src/agent_command_tab/snapshot_data_classes.py +145 -0
- agent_command_tab-0.1.0/src/agent_command_tab/start_with_iterm2.py +138 -0
- agent_command_tab-0.1.0/src/agent_command_tab/tab_order_computation.py +26 -0
- agent_command_tab-0.1.0/src/agent_command_tab/user_interface/__init__.py +1 -0
- agent_command_tab-0.1.0/src/agent_command_tab/user_interface/agent_session_outline_view.py +2120 -0
- agent_command_tab-0.1.0/src/agent_command_tab/user_interface/agent_tool_icons.py +124 -0
- agent_command_tab-0.1.0/src/agent_command_tab/user_interface/app_icon.py +75 -0
- agent_command_tab-0.1.0/src/agent_command_tab/user_interface/control_helpers.py +38 -0
- agent_command_tab-0.1.0/src/agent_command_tab/user_interface/list_window.py +116 -0
- agent_command_tab-0.1.0/src/agent_command_tab/user_interface/menu_bar_status_item.py +193 -0
- agent_command_tab-0.1.0/src/agent_command_tab/user_interface/named_colors.py +58 -0
- agent_command_tab-0.1.0/src/agent_command_tab/user_interface/pointing_hand_button.py +42 -0
- agent_command_tab-0.1.0/src/agent_command_tab/user_interface/popover_container.py +461 -0
- agent_command_tab-0.1.0/src/agent_command_tab/user_interface/row_text_rendering.py +342 -0
- agent_command_tab-0.1.0/src/agent_command_tab/user_interface/screen_layout.py +91 -0
- agent_command_tab-0.1.0/src/agent_command_tab/user_interface/settings_window.py +530 -0
- agent_command_tab-0.1.0/src/agent_command_tab/user_interface/sidebar_panel.py +486 -0
- agent_command_tab-0.1.0/src/agent_command_tab/user_interface/sidebar_placement.py +105 -0
- agent_command_tab-0.1.0/src/agent_command_tab/user_interface/talk_to_each_other_alert.py +130 -0
- agent_command_tab-0.1.0/src/agent_command_tab/window_list_ordering.py +44 -0
- agent_command_tab-0.1.0/src/agent_command_tab.egg-info/PKG-INFO +85 -0
- agent_command_tab-0.1.0/src/agent_command_tab.egg-info/SOURCES.txt +60 -0
- agent_command_tab-0.1.0/src/agent_command_tab.egg-info/dependency_links.txt +1 -0
- agent_command_tab-0.1.0/src/agent_command_tab.egg-info/entry_points.txt +2 -0
- agent_command_tab-0.1.0/src/agent_command_tab.egg-info/requires.txt +2 -0
- agent_command_tab-0.1.0/src/agent_command_tab.egg-info/top_level.txt +1 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 LongfellowLabs LLC
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: agent-command-tab
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: macOS menu bar list, window or screen-edge sidebar of the iTerm2 tabs 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: Development Status :: 3 - Alpha
|
|
11
|
+
Classifier: Environment :: MacOS X :: Cocoa
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Operating System :: MacOS :: MacOS X
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Topic :: Software Development
|
|
16
|
+
Classifier: Topic :: Terminals
|
|
17
|
+
Requires-Python: >=3.10
|
|
18
|
+
Description-Content-Type: text/markdown
|
|
19
|
+
License-File: LICENSE
|
|
20
|
+
Requires-Dist: iterm2<2.31,>=2.30
|
|
21
|
+
Requires-Dist: pyobjc-framework-Cocoa>=10
|
|
22
|
+
Dynamic: license-file
|
|
23
|
+
|
|
24
|
+
<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>
|
|
25
|
+
|
|
26
|
+
# AgentCommandTab
|
|
27
|
+
|
|
28
|
+
A macOS menu bar app that lists the iTerm2 windows and tabs 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. The list shows as a dropdown under the menu bar icon, a sidebar at the edge of the screen, or a regular window.
|
|
29
|
+
|
|
30
|
+
## What it does
|
|
31
|
+
|
|
32
|
+
- **One tree of your agents:** every iTerm2 window 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.
|
|
33
|
+
- **What each agent is doing:** a status dot and word per tab (asking for permission, thinking, running a tool, stuck, running in the background, done, idle, error), how long it has been so, the context size in tokens, and optionally when it started, its memory and CPU use. "Done" stays until you look at the tab. The menu bar icon counts the agents waiting for your answer.
|
|
34
|
+
- **A preview per tab:** what the agent is asking or running, what it said since your last prompt, or that prompt. Open it with the tab's arrow.
|
|
35
|
+
- **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, monitor or all at once. 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.
|
|
36
|
+
- **Sort and filter:** sort by activity, name, start time, memory or CPU use, or keep iTerm2's order; hide the idle tabs with one click.
|
|
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, 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.
|
|
43
|
+
- Python 3.10 or later (for an install with pip or pipx).
|
|
44
|
+
|
|
45
|
+
## Install
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
pipx install agent-command-tab # or: pip install agent-command-tab
|
|
49
|
+
brew install bw2/tap/agent-command-tab # Homebrew adds the bw2/tap repository by itself
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
From a clone of this repository:
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
python3 -m venv .venv && .venv/bin/pip install -e .
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## Use
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
agent-command-tab # the menu bar app; restarts itself if iTerm2's connection drops
|
|
62
|
+
agent-command-tab dump-snapshot # prints the current list as JSON
|
|
63
|
+
agent-command-tab install-hooks # adds the app's hooks to Claude Code's and Codex's settings (remove-hooks takes them out)
|
|
64
|
+
agent-command-tab --version # prints the installed version, for bug reports
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
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.
|
|
68
|
+
|
|
69
|
+
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. Settings > Start with iTerm2 turns that off and removes the script. Only one copy runs at a time; starting another prints that one is already running. Before uninstalling, turn Start with iTerm2 off and run `agent-command-tab remove-hooks`, since pip and Homebrew leave the script and the hooks behind.
|
|
70
|
+
|
|
71
|
+
The app's hooks tell a crashed agent from one that ended normally (its row stays, gray and "exited", for 5 minutes), and count Claude Code's background shells and agents. The list offers to install them (Install Hooks, at its bottom left) while an agent tool in it lacks them. Each settings file is copied to `<file>.agent-command-tab-backup` first. Sessions started afterwards use them, and Codex asks you to approve them first: type `/hooks` in Codex.
|
|
72
|
+
|
|
73
|
+
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.
|
|
74
|
+
|
|
75
|
+
## Development
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
.venv/bin/python -m unittest discover -s tests -p '*_tests.py'
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
[docs/RELEASING.md](https://github.com/bw2/agent-command-tab/blob/main/docs/RELEASING.md) describes how to publish a version.
|
|
82
|
+
|
|
83
|
+
## License
|
|
84
|
+
|
|
85
|
+
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 the Homebrew formula install it alongside as a separate package.
|
|
@@ -0,0 +1,62 @@
|
|
|
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 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. The list shows as a dropdown under the menu bar icon, a sidebar at the edge of the screen, or a regular window.
|
|
6
|
+
|
|
7
|
+
## What it does
|
|
8
|
+
|
|
9
|
+
- **One tree of your agents:** every iTerm2 window 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 for permission, thinking, running a tool, stuck, running in the background, done, idle, error), how long it has been so, the context size in tokens, and optionally when it started, its memory and CPU use. "Done" stays until you look at the tab. 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. Open it with the tab's arrow.
|
|
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, monitor or all at once. 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
|
+
- **Sort and filter:** sort by activity, name, start time, memory or CPU use, or keep iTerm2's order; hide the idle tabs with one click.
|
|
14
|
+
- **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).
|
|
15
|
+
- **A shortcut from any app:** Shift-Command-Tab (or Command-Fn-Tab, chosen in Settings) shows the list, and hides it when pressed again. While macOS's app switcher is open, the keys still go to it.
|
|
16
|
+
|
|
17
|
+
## Requirements
|
|
18
|
+
|
|
19
|
+
- macOS, with iTerm2 3.7 or later and iTerm2's Python API turned on: iTerm2 > Settings > General > Magic > Enable Python API.
|
|
20
|
+
- Python 3.10 or later (for an install with pip or pipx).
|
|
21
|
+
|
|
22
|
+
## Install
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
pipx install agent-command-tab # or: pip install agent-command-tab
|
|
26
|
+
brew install bw2/tap/agent-command-tab # Homebrew adds the bw2/tap repository by itself
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
From a clone of this repository:
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
python3 -m venv .venv && .venv/bin/pip install -e .
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Use
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
agent-command-tab # the menu bar app; restarts itself if iTerm2's connection drops
|
|
39
|
+
agent-command-tab dump-snapshot # prints the current list as JSON
|
|
40
|
+
agent-command-tab install-hooks # adds the app's hooks to Claude Code's and Codex's settings (remove-hooks takes them out)
|
|
41
|
+
agent-command-tab --version # prints the installed version, for bug reports
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
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.
|
|
45
|
+
|
|
46
|
+
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. Settings > Start with iTerm2 turns that off and removes the script. Only one copy runs at a time; starting another prints that one is already running. Before uninstalling, turn Start with iTerm2 off and run `agent-command-tab remove-hooks`, since pip and Homebrew leave the script and the hooks behind.
|
|
47
|
+
|
|
48
|
+
The app's hooks tell a crashed agent from one that ended normally (its row stays, gray and "exited", for 5 minutes), and count Claude Code's background shells and agents. The list offers to install them (Install Hooks, at its bottom left) while an agent tool in it lacks them. Each settings file is copied to `<file>.agent-command-tab-backup` first. Sessions started afterwards use them, and Codex asks you to approve them first: type `/hooks` in Codex.
|
|
49
|
+
|
|
50
|
+
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.
|
|
51
|
+
|
|
52
|
+
## Development
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
.venv/bin/python -m unittest discover -s tests -p '*_tests.py'
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
[docs/RELEASING.md](https://github.com/bw2/agent-command-tab/blob/main/docs/RELEASING.md) describes how to publish a version.
|
|
59
|
+
|
|
60
|
+
## License
|
|
61
|
+
|
|
62
|
+
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 the Homebrew formula install it alongside as a separate package.
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77"] # 77 reads the SPDX license expression below
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "agent-command-tab"
|
|
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"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
license-files = ["LICENSE"]
|
|
12
|
+
authors = [{ name = "Ben Weisburd" }]
|
|
13
|
+
requires-python = ">=3.10"
|
|
14
|
+
dependencies = [
|
|
15
|
+
# Pinned: the core relies on two private names of this package (see tests/iterm2_package_internals_tests.py).
|
|
16
|
+
"iterm2>=2.30,<2.31",
|
|
17
|
+
"pyobjc-framework-Cocoa>=10",
|
|
18
|
+
]
|
|
19
|
+
keywords = ["iterm2", "claude-code", "codex", "ai-agents", "macos", "menu-bar", "dashboard"]
|
|
20
|
+
classifiers = [
|
|
21
|
+
"Development Status :: 3 - Alpha",
|
|
22
|
+
"Environment :: MacOS X :: Cocoa",
|
|
23
|
+
"Intended Audience :: Developers",
|
|
24
|
+
"Operating System :: MacOS :: MacOS X",
|
|
25
|
+
"Programming Language :: Python :: 3",
|
|
26
|
+
"Topic :: Software Development",
|
|
27
|
+
"Topic :: Terminals",
|
|
28
|
+
]
|
|
29
|
+
|
|
30
|
+
[project.urls]
|
|
31
|
+
Homepage = "https://github.com/bw2/agent-command-tab"
|
|
32
|
+
Issues = "https://github.com/bw2/agent-command-tab/issues"
|
|
33
|
+
|
|
34
|
+
[project.scripts]
|
|
35
|
+
agent-command-tab = "agent_command_tab.command_line:main"
|
|
36
|
+
|
|
37
|
+
[tool.setuptools.dynamic]
|
|
38
|
+
version = { attr = "agent_command_tab.__version__" }
|
|
39
|
+
|
|
40
|
+
[tool.setuptools.packages.find]
|
|
41
|
+
where = ["src"]
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
"""Agent tool adapters and the rule that picks one for a tab."""
|
|
2
|
+
|
|
3
|
+
from agent_command_tab.agent_adapters.claude_code import ClaudeCodeAdapter
|
|
4
|
+
from agent_command_tab.agent_adapters.codex import CodexAdapter
|
|
5
|
+
from agent_command_tab.agent_adapters.generic import GenericAdapter
|
|
6
|
+
from agent_command_tab.session_status_computation import map_iterm2_status_value_to_state
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
def build_built_in_agent_tool_adapters():
|
|
10
|
+
"""Returns the adapters with their own rules, in matching order, and the generic adapter."""
|
|
11
|
+
return [ClaudeCodeAdapter(), CodexAdapter()], GenericAdapter()
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def list_slash_commands_of_the_built_in_agent_tools():
|
|
15
|
+
"""Returns every built-in adapter's slash_commands once each, in their order: the tab menu
|
|
16
|
+
lists them all for every tab and enables those its tool takes, so the menu keeps its shape."""
|
|
17
|
+
specific_adapters, generic_adapter = build_built_in_agent_tool_adapters()
|
|
18
|
+
return tuple(dict.fromkeys(command for adapter in [*specific_adapters, generic_adapter] for command in adapter.slash_commands))
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
def list_agent_tool_names_whose_sessions_can_talk_to_each_other():
|
|
22
|
+
"""Returns the names of the built-in tools whose sessions other agent sessions can send
|
|
23
|
+
messages to, the sessions "Talk to Each Other" includes."""
|
|
24
|
+
specific_adapters, generic_adapter = build_built_in_agent_tool_adapters()
|
|
25
|
+
return frozenset(adapter.agent_tool_name for adapter in [*specific_adapters, generic_adapter]
|
|
26
|
+
if adapter.how_other_agent_sessions_send_it_messages)
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def find_agent_tool_adapter_for_tab(command_line, iterm2_status_value, specific_adapters, generic_adapter):
|
|
30
|
+
"""Returns the adapter for a tab's first pane, or None when the tab runs no agent.
|
|
31
|
+
|
|
32
|
+
Args:
|
|
33
|
+
command_line: iTerm2's `commandLine` for the tab's first session.
|
|
34
|
+
iterm2_status_value: The value iTerm2 set in that session's `status` variable after its
|
|
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, tools from settings).
|
|
37
|
+
generic_adapter: Used when no specific adapter matches, the job is not a shell, and the
|
|
38
|
+
status variable holds a recognized value.
|
|
39
|
+
|
|
40
|
+
Returns:
|
|
41
|
+
An AgentToolAdapter or None.
|
|
42
|
+
"""
|
|
43
|
+
for adapter in specific_adapters:
|
|
44
|
+
if adapter.matches_command_line(command_line):
|
|
45
|
+
return adapter
|
|
46
|
+
if generic_adapter.matches_command_line(command_line) and map_iterm2_status_value_to_state(iterm2_status_value):
|
|
47
|
+
return generic_adapter
|
|
48
|
+
return None
|
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
"""What every agent tool adapter provides."""
|
|
2
|
+
|
|
3
|
+
import os
|
|
4
|
+
import shlex
|
|
5
|
+
|
|
6
|
+
SHELL_PROGRAM_NAMES = {"sh", "bash", "zsh", "fish", "dash", "ksh", "tcsh", "csh", "nu", "xonsh", "elvish"}
|
|
7
|
+
# The slash command that ends the conversation and starts a new one: the menu asks first, and
|
|
8
|
+
# the core then forgets the old conversation's readings.
|
|
9
|
+
COMMAND_THAT_STARTS_A_NEW_CONVERSATION = "/clear"
|
|
10
|
+
# The slash commands of Claude Code and Codex alike, in menu order.
|
|
11
|
+
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
|
|
14
|
+
# Code sessions have; or `codex queue --thread <conversation ID>`, which any agent with a shell can run.
|
|
15
|
+
MESSAGES_THROUGH_THE_SEND_MESSAGE_TOOL = "send_message_tool"
|
|
16
|
+
MESSAGES_THROUGH_CODEX_QUEUE = "codex_queue"
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
def split_command_line_into_program_names(command_line):
|
|
20
|
+
"""Returns the base names of the words of a command line, for matching against tool names.
|
|
21
|
+
|
|
22
|
+
A login shell's leading "-" (for example "-bash") is removed. Unbalanced quotes fall back to
|
|
23
|
+
splitting on spaces.
|
|
24
|
+
|
|
25
|
+
Args:
|
|
26
|
+
command_line: iTerm2's `commandLine` variable for a session, or None.
|
|
27
|
+
|
|
28
|
+
Returns:
|
|
29
|
+
A list of base names, possibly empty.
|
|
30
|
+
"""
|
|
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]
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def command_line_runs_a_shell(command_line):
|
|
41
|
+
"""Returns whether the foreground job described by command_line is a plain shell."""
|
|
42
|
+
program_names = split_command_line_into_program_names(command_line)
|
|
43
|
+
return bool(program_names) and program_names[0] in SHELL_PROGRAM_NAMES
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
class AgentToolAdapter:
|
|
47
|
+
"""Describes one agent tool. Subclasses set the class attributes and may override methods.
|
|
48
|
+
|
|
49
|
+
Attributes:
|
|
50
|
+
agent_tool_name: The name shown in the list, for example "Claude Code".
|
|
51
|
+
permission_dialog_screen_patterns: Compiled patterns that all appear while the tool's
|
|
52
|
+
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
|
+
interrupted_turn_screen_pattern: Compiled pattern for the line the tool prints when a
|
|
56
|
+
permission prompt is denied or the turn is interrupted, or None.
|
|
57
|
+
helper_process_names: Names of processes the tool starts for itself during a turn, which
|
|
58
|
+
are not commands the agent waits on (agent_process_tree).
|
|
59
|
+
slash_commands: The commands the tab's right-click menu may type into the tool, in menu
|
|
60
|
+
order ("/compact", "/clear"); empty when the tool has none, or its input box can't be
|
|
61
|
+
read. The menu lists every built-in tool's commands and enables these.
|
|
62
|
+
input_line_marker: The character that starts the tool's input line ("❯"), for
|
|
63
|
+
screen_readings.input_area_is_empty; None when unknown.
|
|
64
|
+
input_area_end_pattern: Compiled pattern of the line just below the input area.
|
|
65
|
+
seconds_before_enter: The pause between a typed command and its Enter, so the tool
|
|
66
|
+
doesn't take the two as one paste.
|
|
67
|
+
working_screen_pattern: Compiled pattern of screen text the tool shows only while a turn
|
|
68
|
+
runs, which tells whether a session whose row has no state (a tool that reports
|
|
69
|
+
none) waits at its prompt; None when unknown.
|
|
70
|
+
queues_slash_commands_typed_during_a_turn: Whether a slash command typed into the tool's
|
|
71
|
+
input box during a turn waits in the tool's own queue and runs when the turn ends,
|
|
72
|
+
rather than being refused (Codex 0.155.1: "'/compact' is disabled while a task is in progress").
|
|
73
|
+
slash_command_refused_during_a_turn_pattern: Compiled pattern of the line the tool prints
|
|
74
|
+
when it refuses a slash command typed during a turn, so the command can be typed again
|
|
75
|
+
later; None when the tool prints none.
|
|
76
|
+
how_other_agent_sessions_send_it_messages: MESSAGES_THROUGH_THE_SEND_MESSAGE_TOOL,
|
|
77
|
+
MESSAGES_THROUGH_CODEX_QUEUE, or None when other sessions have no way to.
|
|
78
|
+
"""
|
|
79
|
+
|
|
80
|
+
agent_tool_name = ""
|
|
81
|
+
permission_dialog_screen_patterns = ()
|
|
82
|
+
progress_noise_patterns = ()
|
|
83
|
+
interrupted_turn_screen_pattern = None
|
|
84
|
+
helper_process_names = frozenset()
|
|
85
|
+
slash_commands = ()
|
|
86
|
+
input_line_marker = None
|
|
87
|
+
input_area_end_pattern = None
|
|
88
|
+
seconds_before_enter = 0.15
|
|
89
|
+
working_screen_pattern = None
|
|
90
|
+
queues_slash_commands_typed_during_a_turn = False
|
|
91
|
+
slash_command_refused_during_a_turn_pattern = None
|
|
92
|
+
how_other_agent_sessions_send_it_messages = None
|
|
93
|
+
|
|
94
|
+
async def find_conversation_id(self, agent_process_id, claude_agent_record):
|
|
95
|
+
"""Returns the ID of the conversation the agent process is in, or None if unknown.
|
|
96
|
+
|
|
97
|
+
Args:
|
|
98
|
+
agent_process_id: The agent's process ID (iTerm2's jobPid).
|
|
99
|
+
claude_agent_record: The process's record from `claude agents --json`, or None.
|
|
100
|
+
"""
|
|
101
|
+
return None
|
|
102
|
+
|
|
103
|
+
async def find_conversation_file(self, agent_process_id, claude_agent_record, claude_config_folders):
|
|
104
|
+
"""Returns the path of the file the tool writes the conversation to, or None if unknown.
|
|
105
|
+
Runs on the core's event loop, so a lookup that reads folders or files does that in a
|
|
106
|
+
worker thread (asyncio.to_thread).
|
|
107
|
+
|
|
108
|
+
Args:
|
|
109
|
+
agent_process_id: The agent's process ID (iTerm2's jobPid).
|
|
110
|
+
claude_agent_record: The process's record from `claude agents --json`, or None.
|
|
111
|
+
claude_config_folders: Folders that may hold Claude Code transcripts.
|
|
112
|
+
"""
|
|
113
|
+
return None
|
|
114
|
+
|
|
115
|
+
def read_context_tokens(self, conversation_file_path):
|
|
116
|
+
"""Returns how many tokens the conversation's context holds, from its file, or None.
|
|
117
|
+
The core calls this, and read_turn_started_at, in a worker thread."""
|
|
118
|
+
return None
|
|
119
|
+
|
|
120
|
+
def read_context_window_tokens(self, conversation_file_path, agent_process_id, claude_agent_record, context_tokens):
|
|
121
|
+
"""Returns the size of the session's context window, for the share of it in use, or None
|
|
122
|
+
if unknown. The core calls this in a worker thread, after read_context_tokens.
|
|
123
|
+
|
|
124
|
+
Args:
|
|
125
|
+
conversation_file_path: The conversation's file.
|
|
126
|
+
agent_process_id: The agent's process ID.
|
|
127
|
+
claude_agent_record: The process's record from `claude agents --json`, or None.
|
|
128
|
+
context_tokens: What read_context_tokens returned.
|
|
129
|
+
"""
|
|
130
|
+
return None
|
|
131
|
+
|
|
132
|
+
def read_turn_started_at(self, conversation_file_path):
|
|
133
|
+
"""Returns when the current turn began, from the conversation file, or None."""
|
|
134
|
+
return None
|
|
135
|
+
|
|
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."""
|
|
139
|
+
return None
|
|
140
|
+
|
|
141
|
+
def build_launch_command_for_a_copy(self, launch_command, conversation_id, claude_agent_record=None):
|
|
142
|
+
"""Returns the command that starts a copy of a session (Duplicate): one that continues a
|
|
143
|
+
copy of the conversation where the tool can fork it, else a fresh session.
|
|
144
|
+
|
|
145
|
+
Args:
|
|
146
|
+
launch_command: The tool's launch command from the settings.
|
|
147
|
+
conversation_id: From find_conversation_id, or None.
|
|
148
|
+
claude_agent_record: The original's record from `claude agents --json`, or None.
|
|
149
|
+
"""
|
|
150
|
+
return launch_command
|
|
151
|
+
|
|
152
|
+
def matches_command_line(self, command_line):
|
|
153
|
+
"""Returns whether a tab whose foreground job has this command line runs this tool.
|
|
154
|
+
|
|
155
|
+
Args:
|
|
156
|
+
command_line: iTerm2's `commandLine` variable, for example "claude --model haiku".
|
|
157
|
+
"""
|
|
158
|
+
raise NotImplementedError
|
|
159
|
+
|
|
160
|
+
def name_agent_tool_for_command_line(self, command_line):
|
|
161
|
+
"""Returns the tool name shown for a tab with this command line (the generic adapter overrides it)."""
|
|
162
|
+
return self.agent_tool_name
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
"""Adapter for Anthropic's Claude Code."""
|
|
2
|
+
|
|
3
|
+
import asyncio
|
|
4
|
+
import glob
|
|
5
|
+
import os
|
|
6
|
+
import re
|
|
7
|
+
import shlex
|
|
8
|
+
|
|
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)
|
|
11
|
+
from agent_command_tab.agent_process_tree import read_process_arguments_and_environment
|
|
12
|
+
from agent_command_tab.context_window_usage import (choose_claude_code_context_window_tokens, find_claude_code_transcript,
|
|
13
|
+
read_claude_code_model_setting,
|
|
14
|
+
read_context_tokens_from_claude_code_transcript,
|
|
15
|
+
read_turn_started_at_from_claude_code_transcript)
|
|
16
|
+
from agent_command_tab.session_preview_computation import read_preview_fields_from_claude_code_transcript
|
|
17
|
+
|
|
18
|
+
ELAPSED_TIME = r"(?:\d+h )?(?:\d+m )?\d+s"
|
|
19
|
+
# One "NAME=value " word in front of a launch command's program, the value maybe quoted
|
|
20
|
+
# ("ANTHROPIC_MODEL=x CLAUDE_CONFIG_DIR=~/.claude_work claude").
|
|
21
|
+
LEADING_ENVIRONMENT_SETTING_PATTERN = re.compile(r"""([A-Za-z_][A-Za-z0-9_]*)=(?:'[^']*'|"(?:[^"\\]|\\.)*"|\\.|[^\s'"\\])*\s+""")
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def list_claude_config_folders():
|
|
25
|
+
"""Returns the Claude Code config folders in use: the default folder (None: a command run
|
|
26
|
+
without CLAUDE_CONFIG_DIR uses it), the dashboard's own CLAUDE_CONFIG_DIR, and every other
|
|
27
|
+
~/.claude* folder with a sessions folder, since a Claude Code started with its own
|
|
28
|
+
CLAUDE_CONFIG_DIR (for example ~/.claude_work) keeps its sessions and settings there. Asked
|
|
29
|
+
by `claude agents --json`, which lists a session only from its own folder, and by the hooks
|
|
30
|
+
installer, since such a session reads only its own folder's settings.json.
|
|
31
|
+
"""
|
|
32
|
+
default_folder = os.path.expanduser("~/.claude")
|
|
33
|
+
other_folders = ([os.environ["CLAUDE_CONFIG_DIR"]] if os.environ.get("CLAUDE_CONFIG_DIR") else []) + sorted(
|
|
34
|
+
folder for folder in glob.glob(os.path.expanduser("~/.claude*")) if os.path.isdir(os.path.join(folder, "sessions")))
|
|
35
|
+
return [None] + [folder for folder in dict.fromkeys(other_folders) if os.path.realpath(folder) != os.path.realpath(default_folder)]
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def remove_config_folder_settings_from_launch_command(launch_command):
|
|
39
|
+
"""Returns the launch command without the CLAUDE_CONFIG_DIR=... words in front of its
|
|
40
|
+
program, keeping its other environment settings."""
|
|
41
|
+
kept_settings = []
|
|
42
|
+
rest = launch_command.lstrip()
|
|
43
|
+
while (match := LEADING_ENVIRONMENT_SETTING_PATTERN.match(rest)):
|
|
44
|
+
if match.group(1) != "CLAUDE_CONFIG_DIR":
|
|
45
|
+
kept_settings.append(match.group(0))
|
|
46
|
+
rest = rest[match.end():]
|
|
47
|
+
return "".join(kept_settings) + rest
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
class ClaudeCodeAdapter(AgentToolAdapter):
|
|
51
|
+
"""Claude Code runs as `claude ...` (iTerm2's jobName is its version number, so the command line is used).
|
|
52
|
+
|
|
53
|
+
Screen patterns are from Claude Code 2.1.302.
|
|
54
|
+
"""
|
|
55
|
+
|
|
56
|
+
agent_tool_name = "Claude Code"
|
|
57
|
+
# Every permission dialog asks "Do you want to ...?" ("proceed?", "make this edit to <file>?",
|
|
58
|
+
# "allow Claude to fetch this content?" in 2.1.303) above an "Esc to cancel" hint.
|
|
59
|
+
permission_dialog_screen_patterns = (re.compile(r"Do you want to .+\?"), re.compile(r"Esc to cancel"))
|
|
60
|
+
interrupted_turn_screen_pattern = re.compile(r"Interrupted · What should Claude do instead\?")
|
|
61
|
+
progress_noise_patterns = (
|
|
62
|
+
re.compile(r"^\s*[✳✶✢✻✽✺·*⏺]\s"), # the spinner glyph, and the tool line's blinking bullet
|
|
63
|
+
re.compile(r"\(" + ELAPSED_TIME + r"(?: · [↓↑] [\d.,]+k? tokens)?\)"), # "(5s · ↓ 97 tokens)", "(4s)"
|
|
64
|
+
re.compile(r" · " + ELAPSED_TIME + r"\b"), # the tool line's " · 4s"
|
|
65
|
+
re.compile(r"\(ctrl\+b to run in background\)"),
|
|
66
|
+
)
|
|
67
|
+
helper_process_names = frozenset({"caffeinate"}) # keeps the Mac awake while a turn runs
|
|
68
|
+
slash_commands = COMPACT_AND_CLEAR_SLASH_COMMANDS
|
|
69
|
+
# The input box: "❯" and a no-break space, then the input, between two rules of "─" (Phase 0).
|
|
70
|
+
input_line_marker = "❯"
|
|
71
|
+
input_area_end_pattern = re.compile(r"^─{10,}\s*$")
|
|
72
|
+
# Checked live with Claude Code 2.1.307 on 2026-10-21: /compact and /clear typed during a turn
|
|
73
|
+
# showed under "Press up to edit queued messages" and ran when the turn ended.
|
|
74
|
+
queues_slash_commands_typed_during_a_turn = True
|
|
75
|
+
how_other_agent_sessions_send_it_messages = MESSAGES_THROUGH_THE_SEND_MESSAGE_TOOL
|
|
76
|
+
|
|
77
|
+
def matches_command_line(self, command_line):
|
|
78
|
+
"""Returns whether the command line's program is `claude` (by base name, so full paths match)."""
|
|
79
|
+
program_names = split_command_line_into_program_names(command_line)
|
|
80
|
+
return bool(program_names) and program_names[0] == "claude"
|
|
81
|
+
|
|
82
|
+
async def find_conversation_id(self, agent_process_id, claude_agent_record):
|
|
83
|
+
"""Returns `sessionId` from the process's `claude agents --json` record."""
|
|
84
|
+
return (claude_agent_record or {}).get("sessionId")
|
|
85
|
+
|
|
86
|
+
async def find_conversation_file(self, agent_process_id, claude_agent_record, claude_config_folders):
|
|
87
|
+
"""Returns the transcript named after the record's `sessionId`: in the record's own config
|
|
88
|
+
folder first (one created after the app started is in no list made then), else in one of
|
|
89
|
+
the config folders."""
|
|
90
|
+
conversation_id = await self.find_conversation_id(agent_process_id, claude_agent_record)
|
|
91
|
+
if not conversation_id:
|
|
92
|
+
return None
|
|
93
|
+
own_config_folder = (claude_agent_record or {}).get("config_folder") or os.path.expanduser("~/.claude")
|
|
94
|
+
return await asyncio.to_thread(find_claude_code_transcript, [own_config_folder, *claude_config_folders], conversation_id)
|
|
95
|
+
|
|
96
|
+
def read_context_tokens(self, conversation_file_path):
|
|
97
|
+
return read_context_tokens_from_claude_code_transcript(conversation_file_path)
|
|
98
|
+
|
|
99
|
+
def read_context_window_tokens(self, conversation_file_path, agent_process_id, claude_agent_record, context_tokens):
|
|
100
|
+
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")),
|
|
102
|
+
context_tokens)
|
|
103
|
+
|
|
104
|
+
def read_turn_started_at(self, conversation_file_path):
|
|
105
|
+
return read_turn_started_at_from_claude_code_transcript(conversation_file_path)
|
|
106
|
+
|
|
107
|
+
def read_preview_fields(self, conversation_file_path):
|
|
108
|
+
return read_preview_fields_from_claude_code_transcript(conversation_file_path)
|
|
109
|
+
|
|
110
|
+
def build_launch_command_for_a_copy(self, launch_command, conversation_id, claude_agent_record=None):
|
|
111
|
+
"""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."""
|
|
115
|
+
if not conversation_id:
|
|
116
|
+
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")
|