agent-command-tab 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. agent_command_tab/__init__.py +4 -0
  2. agent_command_tab/agent_adapters/__init__.py +48 -0
  3. agent_command_tab/agent_adapters/base.py +162 -0
  4. agent_command_tab/agent_adapters/claude_code.py +120 -0
  5. agent_command_tab/agent_adapters/codex.py +102 -0
  6. agent_command_tab/agent_adapters/generic.py +22 -0
  7. agent_command_tab/agent_process_tree.py +557 -0
  8. agent_command_tab/agent_session_pausing.py +254 -0
  9. agent_command_tab/app_controller.py +947 -0
  10. agent_command_tab/claude_code_transcript_records.py +75 -0
  11. agent_command_tab/command_line.py +187 -0
  12. agent_command_tab/context_window_usage.py +230 -0
  13. agent_command_tab/dashboard_core_api.py +57 -0
  14. agent_command_tab/docked_window_frames_store.py +60 -0
  15. agent_command_tab/global_shortcut_key_filter.py +167 -0
  16. agent_command_tab/hook_event_forwarder.py +116 -0
  17. agent_command_tab/hook_event_tracking.py +129 -0
  18. agent_command_tab/hook_states_store.py +60 -0
  19. agent_command_tab/hooks_installer.py +300 -0
  20. agent_command_tab/installed_copy_paths.py +41 -0
  21. agent_command_tab/iterm2_actions.py +325 -0
  22. agent_command_tab/iterm2_connection_thread.py +2299 -0
  23. agent_command_tab/iterm2_snapshot_builder.py +403 -0
  24. agent_command_tab/list_sorting.py +117 -0
  25. agent_command_tab/messages_between_agent_sessions.py +78 -0
  26. agent_command_tab/monitor_assignment.py +109 -0
  27. agent_command_tab/pause_records_store.py +61 -0
  28. agent_command_tab/screen_readings.py +108 -0
  29. agent_command_tab/session_preview_computation.py +228 -0
  30. agent_command_tab/session_status_computation.py +235 -0
  31. agent_command_tab/settings_store.py +292 -0
  32. agent_command_tab/snapshot_data_classes.py +145 -0
  33. agent_command_tab/start_with_iterm2.py +138 -0
  34. agent_command_tab/tab_order_computation.py +26 -0
  35. agent_command_tab/user_interface/__init__.py +1 -0
  36. agent_command_tab/user_interface/agent_session_outline_view.py +2120 -0
  37. agent_command_tab/user_interface/agent_tool_icons.py +124 -0
  38. agent_command_tab/user_interface/app_icon.py +75 -0
  39. agent_command_tab/user_interface/control_helpers.py +38 -0
  40. agent_command_tab/user_interface/list_window.py +116 -0
  41. agent_command_tab/user_interface/menu_bar_status_item.py +193 -0
  42. agent_command_tab/user_interface/named_colors.py +58 -0
  43. agent_command_tab/user_interface/pointing_hand_button.py +42 -0
  44. agent_command_tab/user_interface/popover_container.py +461 -0
  45. agent_command_tab/user_interface/row_text_rendering.py +342 -0
  46. agent_command_tab/user_interface/screen_layout.py +91 -0
  47. agent_command_tab/user_interface/settings_window.py +530 -0
  48. agent_command_tab/user_interface/sidebar_panel.py +486 -0
  49. agent_command_tab/user_interface/sidebar_placement.py +105 -0
  50. agent_command_tab/user_interface/talk_to_each_other_alert.py +130 -0
  51. agent_command_tab/window_list_ordering.py +44 -0
  52. agent_command_tab-0.1.0.dist-info/METADATA +85 -0
  53. agent_command_tab-0.1.0.dist-info/RECORD +57 -0
  54. agent_command_tab-0.1.0.dist-info/WHEEL +5 -0
  55. agent_command_tab-0.1.0.dist-info/entry_points.txt +2 -0
  56. agent_command_tab-0.1.0.dist-info/licenses/LICENSE +21 -0
  57. agent_command_tab-0.1.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,4 @@
1
+ """AgentCommandTab: a macOS menu bar list of the iTerm2 tabs where AI coding agents run."""
2
+
3
+ # The one place the version is set: pyproject.toml reads it from here, and so does `agent-command-tab --version`.
4
+ __version__ = "0.1.0"
@@ -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")
@@ -0,0 +1,102 @@
1
+ """Adapter for OpenAI's Codex CLI."""
2
+
3
+ import asyncio
4
+ import os
5
+ import re
6
+ import shlex
7
+ import time
8
+
9
+ from agent_command_tab.agent_adapters.base import (COMPACT_AND_CLEAR_SLASH_COMMANDS, MESSAGES_THROUGH_CODEX_QUEUE,
10
+ AgentToolAdapter, split_command_line_into_program_names)
11
+ from agent_command_tab.agent_process_tree import (read_process_arguments_and_environment, read_process_current_folder,
12
+ read_process_info)
13
+ from agent_command_tab.context_window_usage import (find_codex_conversation_files,
14
+ read_context_tokens_from_codex_conversation_file,
15
+ read_context_window_tokens_from_codex_conversation_file,
16
+ read_turn_started_at_from_codex_conversation_file)
17
+ from agent_command_tab.session_preview_computation import read_preview_fields_from_codex_conversation_file
18
+
19
+ # <sessions folder>/2026/10/18/rollout-2026-10-18T15-04-05-<conversation ID>.jsonl
20
+ CONVERSATION_FILE_PATTERN = re.compile(
21
+ r"rollout-[^/]*?([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$")
22
+ # The timer Codex shows above its input box only while a turn runs: "Working (5s • esc to
23
+ # interrupt)", "Waiting for background terminal (16s • esc to interrupt)" (0.155.1 and 0.163).
24
+ TURN_TIMER_PATTERN = re.compile(r"\((?:\d+h )?(?:\d+m )?\d+s • esc to interrupt\)")
25
+
26
+
27
+ class CodexAdapter(AgentToolAdapter):
28
+ """Codex runs as `codex ...` (0.163) or through its Node.js wrapper, `node .../codex ...` (0.154).
29
+
30
+ Codex 0.163 reports "waiting" itself exactly while its approval menu shows, so it needs no
31
+ permission dialog check.
32
+ """
33
+
34
+ agent_tool_name = "Codex"
35
+ progress_noise_patterns = (TURN_TIMER_PATTERN,)
36
+ working_screen_pattern = TURN_TIMER_PATTERN
37
+ helper_process_names = frozenset({"codex-code-mode-host"}) # stays running for the whole session
38
+ slash_commands = COMPACT_AND_CLEAR_SLASH_COMMANDS
39
+ # The input box: "›", then the input, above the line with the model and the folder
40
+ # (" GPT-6-Astra low fast · /private/tmp/…", Phase 0).
41
+ input_line_marker = "›"
42
+ input_area_end_pattern = re.compile(r"^ \S[^·]* · [~/…]")
43
+ seconds_before_enter = 0.3 # Codex takes keys within 8 ms of each other as a paste, and Enter for 120 ms after it as a newline
44
+ # Codex 0.155.1 hides its turn timer while answer text streams, so a turn can look over on
45
+ # screen; a /compact typed then is refused with this line and dropped from the box.
46
+ slash_command_refused_during_a_turn_pattern = re.compile(r"'/\w+' is disabled while a task is in progress")
47
+ # `codex queue` reached a busy Codex 0.155.1 session in 0.2 s, which ran the message right after its turn (2026-10-21).
48
+ how_other_agent_sessions_send_it_messages = MESSAGES_THROUGH_CODEX_QUEUE
49
+
50
+ def matches_command_line(self, command_line):
51
+ """Returns whether the command line runs `codex`, directly or as `node <path>/codex`."""
52
+ program_names = split_command_line_into_program_names(command_line)
53
+ if not program_names:
54
+ return False
55
+ if program_names[0] == "codex":
56
+ return True
57
+ return program_names[0] == "node" and len(program_names) > 1 and program_names[1] in ("codex", "codex.js")
58
+
59
+ async def find_conversation_id(self, agent_process_id, claude_agent_record):
60
+ """Returns the conversation ID from the conversation file's name, only when exactly one
61
+ file fits, so a Duplicate doesn't fork an older conversation of this process (after /new).
62
+ One file fitting can still be another Codex session's in the same folder (a later one,
63
+ while this one has no file yet); callers check that with
64
+ DashboardCore.codex_conversation_may_be_another_sessions."""
65
+ conversation_files = await asyncio.to_thread(self.find_conversation_files, agent_process_id)
66
+ return CONVERSATION_FILE_PATTERN.search(conversation_files[0]).group(1) if len(conversation_files) == 1 else None
67
+
68
+ async def find_conversation_file(self, agent_process_id, claude_agent_record, claude_config_folders):
69
+ """Returns the most recently written file that fits (see find_conversation_files)."""
70
+ conversation_files = await asyncio.to_thread(self.find_conversation_files, agent_process_id)
71
+ return conversation_files[0] if conversation_files else None
72
+
73
+ def find_conversation_files(self, agent_process_id):
74
+ """Returns the files that may be the Codex process's conversation, matched by its folder and
75
+ start time in Codex's sessions folder, newest first (context_window_usage.find_codex_conversation_files;
76
+ Codex 0.163 doesn't keep the file open, so lsof can't find it). A process started with
77
+ `codex resume` (or `node .../codex resume`) may be writing an earlier conversation's file."""
78
+ agent_process = read_process_info(agent_process_id) if agent_process_id else None
79
+ if agent_process is None:
80
+ return []
81
+ codex_home = os.environ.get("CODEX_HOME") or os.path.expanduser("~/.codex")
82
+ return find_codex_conversation_files(
83
+ os.path.join(codex_home, "sessions"), agent_process.started_at, read_process_current_folder(agent_process_id),
84
+ time.time(), agent_resumed_a_conversation="resume" in read_process_arguments_and_environment(agent_process_id)[0][1:])
85
+
86
+ def read_context_tokens(self, conversation_file_path):
87
+ return read_context_tokens_from_codex_conversation_file(conversation_file_path)
88
+
89
+ def read_context_window_tokens(self, conversation_file_path, agent_process_id, claude_agent_record, context_tokens):
90
+ return read_context_window_tokens_from_codex_conversation_file(conversation_file_path)
91
+
92
+ def read_turn_started_at(self, conversation_file_path):
93
+ return read_turn_started_at_from_codex_conversation_file(conversation_file_path)
94
+
95
+ def read_preview_fields(self, conversation_file_path):
96
+ return read_preview_fields_from_codex_conversation_file(conversation_file_path)
97
+
98
+ def build_launch_command_for_a_copy(self, launch_command, conversation_id, claude_agent_record=None):
99
+ """Continues a copy of the conversation (`codex fork <id>`)."""
100
+ if not conversation_id:
101
+ return launch_command
102
+ return f"{launch_command} fork {shlex.quote(conversation_id)}"
@@ -0,0 +1,22 @@
1
+ """Adapter for agent tools that have no adapter of their own."""
2
+
3
+ from agent_command_tab.agent_adapters.base import (AgentToolAdapter, command_line_runs_a_shell,
4
+ split_command_line_into_program_names)
5
+
6
+
7
+ class GenericAdapter(AgentToolAdapter):
8
+ """A tab counts as an agent session of an unknown tool when its foreground job is not a shell
9
+ and its iTerm2 `status` variable holds a recognized value. The tool is named after the
10
+ command line's first word. A command line alone never qualifies, because nothing would tell
11
+ such a tool apart from any other program."""
12
+
13
+ agent_tool_name = "Agent"
14
+
15
+ def matches_command_line(self, command_line):
16
+ """Returns whether the foreground job is something other than a shell (the status is checked separately)."""
17
+ return bool(command_line) and not command_line_runs_a_shell(command_line)
18
+
19
+ def name_agent_tool_for_command_line(self, command_line):
20
+ """Returns the name shown for an unknown tool: the base name of the command line's first word."""
21
+ program_names = split_command_line_into_program_names(command_line)
22
+ return program_names[0] if program_names else self.agent_tool_name