handmux 0.22.1 → 0.23.0

package/public/index.html

@@ -48,8 +48,8 @@
       @keyframes bootDot { 0%,100% { opacity: .22; transform: translateY(0); } 40% { opacity: 1; transform: translateY(-3px); } }
       @media (prefers-reduced-motion: reduce) { .boot-glow, .boot-dots i { animation: none; opacity: .8; } }
     </style>
-    <script type="module" crossorigin src="/assets/index-ClOByNCn.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-rjrtUwoJ.css" media="print" onload="this.media='all'"><noscript><link rel="stylesheet" crossorigin href="/assets/index-rjrtUwoJ.css"></noscript>
+    <script type="module" crossorigin src="/assets/index-D1DWcC5u.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-C3N7OkyP.css" media="print" onload="this.media='all'"><noscript><link rel="stylesheet" crossorigin href="/assets/index-C3N7OkyP.css"></noscript>
   </head>
   <body>
     <div id="boot-splash" aria-hidden="true">

package/src/agents/claude.js

@@ -12,6 +12,7 @@ import path from 'node:path';
 import os from 'node:os';
 import { resolveEncodedDirSession, isSessionUuid } from './scanUtils.js';
 import { resolveByExecutable, executableBasename } from './processIdentity.js';
+import { createTranscriptParser, parseTranscript } from '../transcriptParse.js';
 
 // The NATIVE installer names the real binary by version (~/.local/share/claude/versions/2.1.196 —
 // ~/.local/bin/claude is only a symlink to it), and tmux #{pane_current_command} follows that basename
@@ -142,6 +143,7 @@ export const claude = {
   procMatch: /^(\S*\/)?claude(\s|$)/,
   takeoverPrefix: 'cc', // tmux session name prefix for a takeover (cc-<label>-<n>)
   classify: classifyClaude,
+  transcript: { createParser: createTranscriptParser, parse: parseTranscript },
   sessions: {
     isId: isSessionUuid,
     dirOptKey: 'projectsDir', // scanOrphans option that overrides `dir` (back-compat + tests)

package/src/agents/codex.js

@@ -1,15 +1,13 @@
-// The OpenAI Codex CLI agent driver — the second agent, added to prove the driver contract generalizes (see
-// claude.js for the shape). Codex 0.142+ ships a Claude-parity hook system (verified against the real CLI):
-// the SAME lifecycle events (UserPromptSubmit / PermissionRequest / Stop …) delivering the SAME stdin JSON
-// fields (prompt / tool_input / last_assistant_message / stop_hook_active …). So handmux wires Codex through
-// its config.toml hooks (see cli/codexHooks.js) reusing the shared Claude hook scripts, and Codex CLASSIFIES
-// with the very same function as Claude — full working / 需要你 / done parity, not just turn-done.
+// Codex process/session discovery. App Server owns chat, approvals, stopping, inbox state and exact thread
+// identity; plain Codex is identified only as a live process until the user opts into managed mode.
 import path from 'node:path';
 import os from 'node:os';
 import { promises as fsp } from 'node:fs';
 import { readHead, readTail, firstCwd, isSessionUuid } from './scanUtils.js';
-import { classifyClaude } from './claude.js';
 import { resolveByExecutable, executableBasename } from './processIdentity.js';
+import {
+  createCodexTranscriptParser, isCodexSyntheticUserText, parseCodexTranscript,
+} from '../codexTranscriptParse.js';
 
 export const sessionsDir = (home = os.homedir()) => path.join(home, '.codex', 'sessions');
 
@@ -20,10 +18,25 @@ export function rolloutSessionId(name) {
   return m ? m[1] : null;
 }
 
+const UUID_PARTS = '([0-9a-f]{8})\\s*-\\s*([0-9a-f]{4})\\s*-\\s*([0-9a-f]{4})\\s*-\\s*([0-9a-f]{4})\\s*-\\s*([0-9a-f]{12})';
+
+function lastUuidAfter(text, prefix) {
+  const matches = [...String(text || '').matchAll(new RegExp(`${prefix}\\s*${UUID_PARTS}`, 'gi'))];
+  const match = matches.at(-1);
+  return match ? match.slice(1).join('-').toLowerCase() : null;
+}
+
+// A normal Codex exit prints the exact command for the session that just exited. Keep this deliberately
+// stricter than a generic `codex resume` search so conversation text or shell history is not mistaken for
+// the current exit notice.
+export function codexExitSessionId(text) {
+  return lastUuidAfter(text, 'To continue this session, run\\s+codex\\s+resume');
+}
+
 // Last user turn out of a Codex rollout tail, for a recognizable one-line label. Codex records turns as
 // response_item messages: {payload:{type:'message',role:'user',content:[{type:'input_text',text}]}} (and a
-// flatter {type:'message',role:'user',...} in some versions). Skips the synthetic first turn Codex injects
-// (environment_context / user_instructions, which are XML-ish and start with '<'). Best-effort → '' on miss.
+// flatter {type:'message',role:'user',...} in some versions). Skips the synthetic context turns Codex
+// injects (including repository instructions after a resume). Best-effort → '' on miss.
 export function codexUserSnippet(tailText, max = 80) {
   const rows = String(tailText).split('\n');
   for (let i = rows.length - 1; i >= 0; i--) {
@@ -38,8 +51,9 @@ export function codexUserSnippet(tailText, max = 80) {
     let text = '';
     if (typeof c === 'string') text = c;
     else if (Array.isArray(c)) text = c.filter((b) => b && (b.type === 'input_text' || b.type === 'text')).map((b) => b.text).join(' ');
+    if (!text || isCodexSyntheticUserText(text)) continue;
     text = text.replace(/\s+/g, ' ').trim();
-    if (!text || text[0] === '<') continue; // synthetic environment/instructions turn → keep scanning
+    if (!text) continue;
     return text.length > max ? `${text.slice(0, max)}…` : text;
   }
   return '';
@@ -82,6 +96,39 @@ async function recentRollouts(dir, limit = 80) {
   return out.slice(0, limit);
 }
 
+// Resolve one known App Server thread id to its exact rollout. This never falls back by cwd: several
+// Codex panes can share a project, while the UUID suffix is the durable one-to-one session identity.
+const rolloutPathCache = new Map();
+export async function resolveCodexRollout(dir, sessionId) {
+  if (!isSessionUuid(sessionId)) return null;
+  const key = `${dir}\0${sessionId}`;
+  const cached = rolloutPathCache.get(key);
+  if (cached) {
+    try { await fsp.access(cached); return cached; } catch { rolloutPathCache.delete(key); }
+  }
+  const suffix = `-${sessionId}.jsonl`;
+  let found = null;
+  async function descend(current, depth) {
+    if (found) return;
+    let entries;
+    try { entries = await fsp.readdir(current, { withFileTypes: true }); } catch { return; }
+    if (depth < 3) {
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        await descend(path.join(current, entry.name), depth + 1);
+        if (found) return;
+      }
+      return;
+    }
+    const match = entries.find((entry) => entry.isFile()
+      && entry.name.startsWith('rollout-') && entry.name.endsWith(suffix));
+    if (match) found = path.join(current, match.name);
+  }
+  await descend(dir, 0);
+  if (found) rolloutPathCache.set(key, found);
+  return found;
+}
+
 // Resolve a live orphan's cwd to its Codex session: the newest rollout whose recorded cwd matches. Same
 // shape as Claude's resolver ({ sessionId, state, snippet, lastActivity }) so the orphan engine is agnostic.
 export async function resolveCodexSession(dir, cwd, { busyMs = 8000, now = Date.now } = {}) {
@@ -94,7 +141,7 @@ export async function resolveCodexSession(dir, cwd, { busyMs = 8000, now = Date.
     if (!sessionId) continue;
     let snippet = '';
     try { snippet = codexUserSnippet(await readTail(file)); } catch { /* best effort */ }
-    return { sessionId, state: now() - mtime < busyMs ? 'busy' : 'idle', snippet, lastActivity: Math.round(mtime) };
+    return { sessionId, state: now() - mtime < busyMs ? 'busy' : 'idle', snippet, lastActivity: Math.round(mtime), file };
   }
   return {};
 }
@@ -107,8 +154,7 @@ export const codex = {
   procNames: ['codex'],
   procMatch: /^(\S*\/)?codex(\s|$)/,
   takeoverPrefix: 'cx', // tmux session name prefix for a takeover (cx-<label>-<n>)
-  classify: classifyClaude, // Codex hook payloads match Claude's field-for-field — same classifier
-
+  transcript: { createParser: createCodexTranscriptParser, parse: parseCodexTranscript },
   sessions: {
     isId: isSessionUuid,
     dirOptKey: 'sessionsDir', // scanOrphans option that overrides `dir`
@@ -117,5 +163,6 @@ export const codex = {
     // `codex resume <uuid>` continues the session from its rollout file.
     resumeArgs: (id) => ['codex', 'resume', id],
     resumeCmd: (id) => `codex resume ${id}`,
+    managedResumeCmd: (id) => `handmux codex resume ${id}`,
   },
 };

package/src/agents/index.js

@@ -1,7 +1,6 @@
 // The agent registry: the one place that lists which coding agents handmux drives. Adding a third agent is a
-// new driver module (see claude.js / codex.js) plus one line here — the inbox pipeline (claudeEvents.js),
-// the orphan/takeover engine (orphans.js), and the hook installers all consume drivers through this list,
-// so none of them hard-codes an agent name.
+// new driver module (see claude.js / codex.js) plus one line here — the inbox pipeline and orphan/takeover
+// engine consume drivers through this list, so process and session behavior stays centralized.
 import { claude } from './claude.js';
 import { codex } from './codex.js';
 

package/src/claudeEvents.js

@@ -13,9 +13,7 @@ const here = path.dirname(fileURLToPath(import.meta.url));
 // Default lives under server/data (gitignored runtime data); override with CLAUDE_STATE_FILE.
 export const DEFAULT_STATE_FILE = process.env.CLAUDE_STATE_FILE || path.resolve(here, '../data/claude-state.json');
 
-// Classify a Claude hook event → inbox kind. The logic now lives in the Claude driver (agents/claude.js);
-// re-exported here because tests and callers import it by this path. Per-pane classification in getStates
-// dispatches through getAgent(entry.agent) so Codex (and future agents) classify with their own driver.
+// Classify a Claude hook event → inbox kind. Re-exported because tests and callers import this path.
 export const classifyEvent = claude.classify;
 
 // Which display VIEW a kind pushes as — and so what the device notification fires for. permission→需要你,
@@ -28,10 +26,8 @@ const VIEW_LABEL = { needs: '需要你', done: '已完成' };
 
 // The dedup key for a pane's current push view. `needs` is view-only: Claude signals one permission gate via
 // TWO hooks (permreq then permission_prompt) at different ts, and both must collapse to a SINGLE 需要你. But
-// `done` is ts-sensitive: each finished turn is a fresh "已完成 / 该你了". For Claude, two dones are always
-// separated by a 进行中 that re-arms the dedup anyway, so keying done by ts is equivalent; for Codex — whose
-// ONLY event is turn-complete, with no working/prompt event in between — it's what makes turn 2, 3, … push
-// instead of latching on turn 1's done forever.
+// `done` is ts-sensitive: each finished turn is a fresh "已完成 / 该你了". For Claude, two dones are normally
+// separated by a 进行中 that re-arms the dedup; the timestamp also protects unusual missing-start sequences.
 function pushKey(view, ts) { return view === 'done' ? `done:${ts}` : view; }
 
 // A 进行中 (working) is a LATCHED state: set by UserPromptSubmit, normally closed by Stop. But an ESC
@@ -146,6 +142,7 @@ function readStateFile(file) {
 export function createClaudeEvents({
   commands,
   push,
+  codexApp = null,
   file = DEFAULT_STATE_FILE,
   now = () => Date.now(),
   statMtime = defaultStatMtime,
@@ -169,6 +166,7 @@ export function createClaudeEvents({
   function prime() {
     const recorded = readStateFile(file);
     for (const [pane, r] of Object.entries(recorded)) {
+      if (r?.agent === 'codex') continue; // legacy rows are never a Codex state source
       const c = r && typeof r.src === 'string' ? getAgent(r.agent).classify(r.src, r.payload || {}) : null;
       const view = c ? PUSH_VIEW[c.kind] : undefined;
       if (view) lastPushed[pane] = pushKey(view, r.ts); // resting 需要你/已完成 → treat as seen, don't replay
@@ -190,6 +188,37 @@ export function createClaudeEvents({
     try { await push.sendToSession(lp.session, payload, opts); } catch { /* best effort */ }
   }
 
+  async function updatePush(pane, c, ts, lp, { gone = false, suppressPush = false } = {}) {
+    const kind = c ? c.kind : null;
+    const view = PUSH_VIEW[kind];
+    const key = view ? pushKey(view, ts) : undefined;
+    if (kind === 'idle') return;
+    if (gone || !view) {
+      lastPushed[pane] = null;
+    } else if (suppressPush) {
+      lastPushed[pane] = key;
+    } else if (lastPushed[pane] !== key && lp?.session) {
+      lastPushed[pane] = key;
+      await sendPush(pane, view, c, lp);
+    }
+  }
+
+  // Agent identity is part of pane navigation, not inbox state. Resolve it from the pane's live foreground
+  // process so the phone can choose terminal/chat during the initial /panes load instead of waiting for the
+  // slower /states reconciliation pass. Work on copies because executable corroboration normalizes `cmd`.
+  async function identifyPaneAgents(panes = []) {
+    const livePanes = panes.map((pane) => ({
+      ...pane,
+      cmd: typeof pane?.cmd === 'string' ? pane.cmd : (pane?.command || ''),
+    }));
+    try { await resolveVersionedComms(livePanes, run, commVerdicts); } catch { /* exact names still work */ }
+    try { await resolveCodexComms(livePanes, run, commVerdicts); } catch { /* exact names still work */ }
+    return Object.fromEntries(livePanes.flatMap((pane) => {
+      const agent = agentForProc(pane.cmd);
+      return agent ? [[pane.id, agent.id]] : [];
+    }));
+  }
+
   // Read the state file, reconcile every recorded pane against live tmux, and in ONE pass: (1) fire push
   // for 需要你/已完成 transitions (deduped, global — independent of any caller's session filter), and
   // (2) build the pane→state roster the inbox shows. A pane is dropped from the roster when its latest
@@ -201,17 +230,21 @@ export function createClaudeEvents({
     const allow = allowedSessions == null ? null : new Set(allowedSessions);
     const recorded = readStateFile(file);
     let live = null;
+    let managedCodex = {};
     try {
       const panes = await commands.listLivePanes();
-      // Normalize ambiguous commands BEFORE identity/liveness matching: native Claude may report a bare
-      // version and npm-installed Codex reports node. Both require foreground-TTY + real-executable proof.
-      await resolveVersionedComms(panes, run, commVerdicts);
-      await resolveCodexComms(panes, run, commVerdicts);
+      const agents = await identifyPaneAgents(panes);
+      for (const pane of panes) if (agents[pane.id]) pane.cmd = agents[pane.id];
       live = new Map(panes.map((p) => [p.id, p]));
+      managedCodex = codexApp?.inboxStates ? await codexApp.inboxStates(panes) : {};
     } catch { /* tmux down */ }
 
     const out = {};
     for (const [pane, rec] of Object.entries(recorded)) {
+      // Older Handmux versions wrote Codex events into this Claude Hook state file. Codex is now strictly
+      // App Server-backed, so even an unmanaged pane must ignore those stale rows instead of reviving an
+      // approximate status or notification.
+      if (rec?.agent === 'codex') continue;
       const agent = getAgent(rec && rec.agent);
       let c = rec && typeof rec.src === 'string' ? agent.classify(rec.src, rec.payload || {}) : null;
       // A 需要你 the user already resolved leaves no closing hook (see PERM_RESOLVED_GUARD_MS). statMtime
@@ -247,17 +280,7 @@ export function createClaudeEvents({
       // 60s "still waiting" idle neither pushes nor disturbs the dedup (the pane is still in the same
       // resting state). working / end / gone / unclassifiable re-arm the dedup for the next entry.
       if (live) {
-        const kind = c ? c.kind : null;
-        const view = PUSH_VIEW[kind]; // 'needs' | 'done' | undefined
-        const key = view ? pushKey(view, rec.ts) : undefined;
-        if (kind === 'idle') {
-          /* trailing idle reminder — no push, keep the dedup as the preceding done left it */
-        } else if (gone || !view) {
-          lastPushed[pane] = null; // 进行中 / 结束 / gone → re-arm for the next 需要你 / 已完成
-        } else if (lastPushed[pane] !== key && lp.session) {
-          lastPushed[pane] = key;
-          await sendPush(pane, view, c, lp);
-        }
+        await updatePush(pane, c, rec.ts, lp, { gone });
       }
 
       // (2) roster — drop ended / dead / claude-exited panes; resolve location from the live tmux row.
@@ -271,6 +294,22 @@ export function createClaudeEvents({
       out[pane] = { ...loc, kind: c.kind, msg: c.msg || '', ts: rec.ts || 0, agent: agent.id };
     }
 
+    // App Server is the sole Codex state source. A neutral state still leaves process presence below to
+    // identify the pane as Codex without guessing its activity.
+    if (live) {
+      for (const [pane, state] of Object.entries(managedCodex)) {
+        const lp = live.get(pane);
+        if (!lp) continue;
+        const c = state.kind ? { kind: state.kind, msg: state.msg || '' } : null;
+        await updatePush(pane, c, state.ts || 0, lp, { suppressPush: state.suppressPush });
+        if (allow && !allow.has(lp.session)) continue;
+        out[pane] = {
+          session: lp.session, window: lp.window, windowName: lp.windowName,
+          kind: c?.kind || null, msg: c?.msg || '', ...(c ? { ts: state.ts || 0 } : {}), agent: 'codex',
+        };
+      }
+    }
+
     // (3) process presence — a pane whose FOREGROUND program IS a coding agent reads as "agent here" even
     // with no active turn on record: a fresh session that hasn't prompted yet, or one right after `/clear`
     // (whose SessionEnd dropped its roster entry above though the agent is still running). This is what the
@@ -334,23 +373,27 @@ export function createClaudeEvents({
   // isn't a Claude pane / the recorded payload carries no session info, so callers can fall back cleanly.
   function paneSession(pane) {
     const rec = readStateFile(file)[pane];
+    if (rec?.agent === 'codex') return null;
     const p = rec && rec.payload;
     if (!p || typeof p !== 'object') return null;
     const transcriptPath = typeof p.transcript_path === 'string' ? p.transcript_path : null;
     const sessionId = typeof p.session_id === 'string' ? p.session_id : null;
     const cwd = typeof p.cwd === 'string' ? p.cwd : null;
     if (!transcriptPath && !sessionId) return null;
-    return { sessionId, transcriptPath, cwd };
+    return {
+      sessionId, transcriptPath, cwd,
+      agent: typeof rec.agent === 'string' ? rec.agent : undefined,
+    };
   }
 
-  // Agent identity is needed independently of session metadata: a Codex pane may not have a Claude-style
-  // transcript path, but the current Claude-only chat lens must still fail closed instead of cwd-falling
-  // back to an unrelated Claude jsonl. Untagged legacy hook rows are Claude.
+  // Agent identity is needed independently of session metadata so the chat lens chooses the matching
+  // backend (Claude transcript or Codex App Server). Untagged legacy hook rows are Claude.
   function paneAgent(pane) {
     const rec = readStateFile(file)[pane];
     if (!rec || typeof rec !== 'object') return null;
+    if (rec.agent === 'codex') return null;
     return typeof rec.agent === 'string' && rec.agent ? rec.agent : 'claude';
   }
 
-  return { getStates, start, stop, paneSession, paneAgent };
+  return { getStates, identifyPaneAgents, start, stop, paneSession, paneAgent };
 }

package/src/cli/codexManaged.js

@@ -0,0 +1,77 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawn as spawnChild } from 'node:child_process';
+
+const PANE_RE = /^%\d+$/;
+
+export function codexAppSocketPath(pane, home = os.homedir()) {
+  if (!PANE_RE.test(pane || '')) throw new Error('managed Codex requires a tmux pane');
+  return path.join(home, '.handmux', 'codex-app', `${pane.slice(1)}.sock`);
+}
+
+function waitForSocket(socketPath, child, {
+  exists = fs.existsSync,
+  wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  timeoutMs = 5_000,
+  now = Date.now,
+} = {}) {
+  return new Promise((resolve, reject) => {
+    let exited = false;
+    let exitCode = null;
+    child.once('exit', (code) => { exited = true; exitCode = code; });
+    child.once('error', reject);
+    (async () => {
+      const started = now();
+      while (!exists(socketPath)) {
+        if (exited) throw new Error(`Codex App Server exited before startup (${exitCode ?? 'unknown'})`);
+        if (now() - started >= timeoutMs) throw new Error('Codex App Server startup timed out');
+        await wait(25);
+      }
+      resolve();
+    })().catch(reject);
+  });
+}
+
+function finish(child) {
+  return new Promise((resolve, reject) => {
+    child.once('error', reject);
+    child.once('exit', (code, signal) => resolve({ code, signal }));
+  });
+}
+
+// One App Server belongs to one tmux pane. The TUI and Handmux connect to that pane-owned Unix socket,
+// so thread identity, messages, approvals, settings, interrupts and inbox state share one runtime.
+export async function runManagedCodex(args = [], {
+  home = os.homedir(),
+  env = process.env,
+  spawn = spawnChild,
+  mkdir = (dir) => fs.mkdirSync(dir, { recursive: true, mode: 0o700 }),
+  unlink = (file) => { try { fs.unlinkSync(file); } catch (error) { if (error?.code !== 'ENOENT') throw error; } },
+  waitOptions,
+} = {}) {
+  const pane = env.TMUX_PANE;
+  const socketPath = codexAppSocketPath(pane, home);
+  mkdir(path.dirname(socketPath));
+  unlink(socketPath);
+
+  const managedEnv = { ...env, HANDMUX_CODEX_MANAGED: '1' };
+  const appServer = spawn('codex', ['app-server', '--listen', `unix://${socketPath}`], {
+    env: managedEnv,
+    stdio: ['ignore', 'ignore', 'ignore'],
+  });
+  let tui = null;
+  try {
+    await waitForSocket(socketPath, appServer, waitOptions);
+    tui = spawn('codex', ['--remote', `unix://${socketPath}`, ...args], {
+      env: managedEnv,
+      stdio: 'inherit',
+    });
+    const result = await finish(tui);
+    return Number.isInteger(result.code) ? result.code : 1;
+  } finally {
+    if (tui && tui.exitCode == null && tui.signalCode == null) tui.kill('SIGTERM');
+    if (appServer.exitCode == null && appServer.signalCode == null) appServer.kill('SIGTERM');
+    unlink(socketPath);
+  }
+}

package/src/cli/hookScaffold.js

@@ -1,13 +1,9 @@
-// Shared IO scaffolding for the coding-agent hook installers (claudeHooks.js, codexHooks.js) and the
-// statusLine capturer. The FORMAT each installer merges into differs (settings.json vs config.toml's marked
-// region vs the single statusLine slot) and stays in its own module — but the plumbing underneath is
-// identical: deploy the shared scripts, write the env, remove them on uninstall, and write atomically.
+// Shared IO scaffolding for the Claude Code hook installer and statusLine capturer.
 import fs from 'node:fs';
 import path from 'node:path';
 
-// Scripts every agent hook installer deploys. The notify/write pair is shared because Codex mirrors
-// Claude's hook contract; the small Codex usage reader is inert unless handmux-write receives agent=codex.
-export const HOOK_SCRIPTS = ['handmux-notify.sh', 'handmux-write.cjs', 'handmux-codex-usage.cjs'];
+export const HOOK_SCRIPTS = ['handmux-notify.sh', 'handmux-write.cjs'];
+const LEGACY_HOOK_SCRIPTS = ['handmux-codex-usage.cjs'];
 
 // Atomic write (tmp + rename) so a crash can't leave a half-written config file. Text in, text out — callers
 // pass raw TOML for config.toml, or use writeJsonAtomic for pretty-printed settings.json.
@@ -18,18 +14,20 @@ export function writeFileAtomic(file, text) {
 }
 export const writeJsonAtomic = (file, obj) => writeFileAtomic(file, JSON.stringify(obj, null, 2));
 
-// Deploy the shared notify/write scripts into `hooksDir` and point their env at the shared state file. Same
-// bytes for every agent — only the registration target (settings.json vs config.toml) differs per installer.
+// Deploy the Claude notify/write scripts into `hooksDir` and point their env at the shared state file.
 export function deployHookScripts(hooksDir, srcDir, stateFile) {
   fs.mkdirSync(hooksDir, { recursive: true });
   for (const f of HOOK_SCRIPTS) fs.copyFileSync(path.join(srcDir, f), path.join(hooksDir, f));
+  for (const f of LEGACY_HOOK_SCRIPTS) {
+    try { fs.unlinkSync(path.join(hooksDir, f)); } catch { /* absent */ }
+  }
   fs.chmodSync(path.join(hooksDir, 'handmux-notify.sh'), 0o755);
   fs.writeFileSync(path.join(hooksDir, 'handmux-notify.env'), `HANDMUX_STATE=${stateFile}\n`, { mode: 0o600 });
 }
 
 // Remove the deployed scripts + env (uninstall). Best-effort: a missing file is fine.
 export function removeHookScripts(hooksDir) {
-  for (const f of [...HOOK_SCRIPTS, 'handmux-notify.env']) {
+  for (const f of [...HOOK_SCRIPTS, ...LEGACY_HOOK_SCRIPTS, 'handmux-notify.env']) {
     try { fs.unlinkSync(path.join(hooksDir, f)); } catch { /* already gone */ }
   }
 }

package/src/cli/i18n/en.js

@@ -126,15 +126,11 @@ export default {
   'access.hint': '  handmux status | stop',
 
   // hooks
-  'hooks.confirmEnable': 'Enable coding-agent notifications (inbox)?',
-  'hooks.installedShort': '✓ Agent hooks installed.',
+  'hooks.confirmEnable': 'Enable Claude Code states and notifications (inbox)?',
   'hooks.noClaude': 'Claude Code not detected (~/.claude missing) — nothing to install.',
-  'hooks.noAgents': 'No coding agent detected (no ~/.claude, and codex not on PATH) — nothing to install.',
-  'hooks.installed': '✓ Claude hooks installed → ~/.claude/settings.json',
   'hooks.installedClaude': '✓ Claude Code hooks installed → ~/.claude/settings.json',
-  'hooks.installedCodex': '✓ Codex hooks installed → ~/.codex/config.toml',
-  'hooks.installedHint': '  Restart or open a new agent session to load them; the inbox lights up as panes report.',
-  'hooks.removed': '✓ Agent hooks removed.',
+  'hooks.installedHint': '  Restart or open a new Claude Code session to load them; the inbox lights up as panes report.',
+  'hooks.removed': '✓ Claude Code hooks removed.',
   'hooks.usage': 'usage: handmux hooks install|uninstall',
 
   // Claude statusLine usage capturer (powers the phone Usage page's 5h/weekly bars)
@@ -341,6 +337,7 @@ export default {
   handmux stop | restart | status
   handmux logs [--follow] [--lines N]
   handmux push <title> <body>   notify your phone from a script (--session X · --device K · --tag T · --url U)
+  handmux codex [args...]       launch a Codex TUI synchronized with chat view
   handmux restore [--dry-run] [--checkpoint <id>] [--session <name>]
   handmux restore --list
   handmux update           upgrade to the latest published version (npm i -g handmux@latest)
@@ -350,7 +347,7 @@ The model: 'start' runs · 'setup' configures (writes ~/.handmux/config.json) ·
 
 more:
   handmux config                          show the effective config + where each value came from
-  handmux hooks install|uninstall         enable/disable agent notifications (inbox)
+  handmux hooks install|uninstall         enable/disable Claude Code notifications (inbox)
   handmux service install|uninstall       start at login (launchd/systemd)
   handmux help flags                      one-run flags + env vars (scripting / headless / Docker)
   --config PATH · --lang en|zh · --version, -v

package/src/cli/i18n/zh.js

@@ -125,15 +125,11 @@ export default {
   'access.hint': '  handmux status | stop',
 
   // hooks
-  'hooks.confirmEnable': '启用编程 agent 通知(收件箱)?',
-  'hooks.installedShort': '✓ agent hooks 已安装。',
+  'hooks.confirmEnable': '启用 Claude Code 状态与通知(收件箱)?',
   'hooks.noClaude': '未检测到 Claude Code(缺少 ~/.claude)—— 无需安装。',
-  'hooks.noAgents': '未检测到编程 agent(无 ~/.claude,且 PATH 上没有 codex)—— 无需安装。',
-  'hooks.installed': '✓ Claude hooks 已安装 → ~/.claude/settings.json',
   'hooks.installedClaude': '✓ Claude Code hooks 已安装 → ~/.claude/settings.json',
-  'hooks.installedCodex': '✓ Codex hooks 已安装 → ~/.codex/config.toml',
-  'hooks.installedHint': '  重启或新开一个 agent 会话以加载;窗格上报后收件箱就会亮起。',
-  'hooks.removed': '✓ agent hooks 已移除。',
+  'hooks.installedHint': '  重启或新开一个 Claude Code 会话以加载;窗格上报后收件箱就会亮起。',
+  'hooks.removed': '✓ Claude Code hooks 已移除。',
   'hooks.usage': '用法:handmux hooks install|uninstall',
 
   // Claude statusLine 用量捕获(点亮手机用量页的 5h/周额度条)
@@ -340,6 +336,7 @@ export default {
   handmux stop | restart | status
   handmux logs [--follow] [--lines N]
   handmux push <标题> <正文>    从脚本推一条通知到手机（--session 会话 · --device 设备key · --tag · --url）
+  handmux codex [参数...]      启动与对话视图同步的 Codex TUI
   handmux restore [--dry-run] [--checkpoint <id>] [--session <name>]
   handmux restore --list
   handmux update           升级到最新发布版本(npm i -g handmux@latest)
@@ -349,7 +346,7 @@ export default {
 
 更多:
   handmux config                          显示生效的配置 + 每一项来自哪里
-  handmux hooks install|uninstall         启用/停用 agent 通知(收件箱)
+  handmux hooks install|uninstall         启用/停用 Claude Code 通知(收件箱)
   handmux service install|uninstall       开机自启(launchd/systemd)
   handmux help flags                      一次性 flag + 环境变量(脚本 / 无头 / Docker)
   --config PATH · --lang en|zh · --version, -v

package/src/cli/legacyCodexHooks.js

@@ -0,0 +1,49 @@
+// Cleanup for Handmux versions that used to install Codex lifecycle hooks. Current Codex integration is
+// App Server-only; this module can only remove Handmux's exact marked region and files, never install or
+// synchronize hooks and never touch user-owned Codex configuration outside the marker.
+import fs from 'node:fs';
+import path from 'node:path';
+import { homedir } from 'node:os';
+import { writeFileAtomic } from './hookScaffold.js';
+
+const BEGIN = '# >>> handmux codex-hooks >>>';
+const END = '# <<< handmux codex-hooks <<<';
+const LEGACY_FILES = [
+  'handmux-notify.sh',
+  'handmux-write.cjs',
+  'handmux-codex-usage.cjs',
+  'handmux-notify.env',
+];
+
+export function stripLegacyCodexHooks(toml) {
+  const text = toml || '';
+  const start = text.indexOf(BEGIN);
+  if (start < 0) return text;
+  const end = text.indexOf(END, start);
+  if (end < 0) return text;
+  return (text.slice(0, start) + text.slice(end + END.length)).replace(/\n{3,}/g, '\n\n');
+}
+
+export function removeLegacyCodexHooks(home = homedir()) {
+  const codexDir = path.join(home, '.codex');
+  const configuredPath = path.join(codexDir, 'config.toml');
+  let changed = false;
+  try {
+    const configFile = fs.lstatSync(configuredPath).isSymbolicLink()
+      ? fs.realpathSync(configuredPath) : configuredPath;
+    const mode = fs.statSync(configFile).mode & 0o777;
+    const before = fs.readFileSync(configFile, 'utf8');
+    const after = stripLegacyCodexHooks(before);
+    if (after !== before) {
+      writeFileAtomic(configFile, after);
+      fs.chmodSync(configFile, mode);
+      changed = true;
+    }
+  } catch { /* no readable config */ }
+
+  const hooksDir = path.join(codexDir, 'hooks');
+  for (const name of LEGACY_FILES) {
+    try { fs.unlinkSync(path.join(hooksDir, name)); changed = true; } catch { /* absent or user-inaccessible */ }
+  }
+  return { changed };
+}