wezdeck: Instructions file for Codex

AGENTS

This file is the project-level agent entry point. User-level reusable agent profiles hosted under agent-profiles/ are separate and do not override this file unless a user explicitly points an external tool at them.

Loading Rule

Read AGENTS.md first, then open only the matching file under docs/. Read additional docs only when the current doc points to them or the task crosses that boundary.

Design stance

Control plane, not a hotkey dump. Every new/changed interaction must be (1) keyboard-first, (2) headless-verify for agents (CDP without stealing focus), (3) observable — leave reviewable signals (badge / category log·latency / timeline·habit). Blind features are incomplete. Summary: README.md#design-stance. Operator: docs/diagnostics.md. Emit: docs/logging-conventions.md.

Task Routing

• Setup, local prerequisites, or machine-local config: Read docs/setup.md.
• Human-only script handoff (wd-run / x), propose→peek→CAS run, handoff audit / retention, or “do not paste multi-line scripts for the human to run”: Read docs/agent-run.md. Agent self-exec is out of scope.
• Sync, reload, verification, or day-to-day maintenance: Read docs/daily-workflow.md.
• Repository-owned config/skill/script renames, compatibility layers, migration warnings, or deciding whether to keep an old interface: Read docs/compatibility-policy.md.
• External capability source ownership, user-level links, agent profiles, shell injection, WEZDECK_REPO, upstream agent skills, or path resolution: Read docs/skill-sources.md.
• Repo hygiene (doc/code size budgets, broken relative links, pre-commit gate, run.sh audit): Read docs/daily-workflow.md#repo-hygiene; run skills/repo-hygiene/.
• Resetting a primary checkout or long-lived dev-* workstation / 「重置开发分支」 / recycle onto origin/HEAD / closing a round then starting the next task: Load platform skill skills/worktree-recycle/SKILL.md (linked as worktree-recycle); do not hand-roll git reset or ask the human to run CLI. Fast path: fetch + dirty check + hard-reset + remote sync; delivery gate and project init are off by default. Docs: docs/workspaces.md. Standing policy: after a worktree round is delivered onto mainline, always recycle the dev-* tree so the next round starts from origin/HEAD; keep primary master / WEZDECK_REPO as the machine source of truth (Maintenance loop).
• Workspace definitions or workspace behavior: Read docs/workspaces.md.
• Keybindings: Read docs/keybindings.md.
• tmux UI, tab titles, status rendering, copy-mode, or visible terminal behavior: Read docs/tmux-ui.md.
• Terminal Vim inside tmux: scroll that feels like page-skips, windows full of @ rows, 'termsync' / DEC 2026 under tmux DA2, or Shift+drag jumping into copy-mode while editing: Read docs/tmux-ui.md#vim-in-tmux (install / vimrc: docs/setup.md#vim-92-optional).
• Grok Build fullscreen TUI: whole-transcript flash on Alt+o / pane focus, FocusGained terminal.clear(), cream #eeeeee vs pane bg_base, the PATH focus-filter (grok-with-focus-filter.sh --install / --check / launch --ensure; ~/.grok/bin/grok → wrapper, grok.real = ELF; zshrc prepends ~/.grok/bin), interactive grok after grok update (updater clobbers ~/.grok/bin/grok; heal = shell-env grok() absolute wrap + launch ensure reseats PATH and re-applies GrokDay cream/Reset theme patch, then exit/--resume live panes — do not redesign focus-events), why managed agent-launcher.sh grok can look fine while a bare-PATH grok flashes (launcher uses wrapper absolute path), why macOS WezTerm+tmux can look fine with the same heal (sub-frame client burst, not OS-exempt), why WSL→Windows still flashes even on a tiny pane, scripts/dev/repro-grok-focus-flash.sh, mouse-wheel feel under tmux (scroll_lines / scroll_mode=wheel / scroll_speed in ~/.grok/config.toml), or Grok follow ▼ click dead while a stock-tmux macOS box works (MouseDown1Pane must send-keys -M when alternate_on / mouse_any_flag): Read docs/tmux-ui.md#grok-build-in-tmux.
• Claude Code fullscreen TUI (tui: fullscreen in ~/.claude/settings.json), mouse-wheel feel under WezTerm→tmux (CLAUDE_CODE_SCROLL_SPEED, /scroll-speed, wheelScrollAccelerationEnabled), or why background / agent-view attach stays fullscreen even after /tui default: Read docs/tmux-ui.md#claude-code-in-tmux.
• Window appearance presets (opaque / frosted), transparency / frosted-glass, win32_system_backdrop, window_background_opacity, the WEZTERM_APPEARANCE_PRESET selector, render-tmux-appearance.sh, or the tab-bar / pane / status background colors that make the frosted look cohere: Read docs/appearance-presets.md.
• Choosing or revisiting the inner multiplexer (tmux vs herdr), or planning feature work that a tmux upgrade could absorb — the tmux 3.8 borrow list (OSC 133 pane events, floating / modal panes, set-hook -B monitors, theme reporting, #{A/count:frames}), the measured herdr 0.8.0 numbers (per-session server memory, session-level focus, sidebar limits, no #(shell) equivalent, no ad-hoc popup CLI), and why the 2026-08-18 evaluation ended with tmux staying: Read docs/multiplexer-comparison.md.
• Agent-attention pipeline: Claude hook install / upgrade, attention.json schema and transitions, tab badges + right-status counters, focus-based auto-ack, the Alt+j / Alt+k / Alt+l / Alt+Shift+l / Alt+/ keyboard entry points, or Codex integration: Read docs/agent-attention.md.
• Timed reminders (cron-driven tmux popups), the reminder.sh / tmux-popup-active.sh wrappers, or the wezterm-x/local/crontab install workflow: Read docs/reminders.md.
• Phone / Android remote work (OpenClaw only; Happy + Tailscale phone shell retired 2026-07), tmux window-size limits, Termux IME notes: Read docs/mobile-access.md.
• Headless Chrome debug instance, auto-start behavior, Alt+b / Alt+Shift+b, chrome://inspect workflow, or the right-status CDP·… badge: Read docs/browser-debug.md.
• Cutting a Windows wezdeck-runtime release, updating release-manifest.json, forcing the release-install branch, or side-loading the release zip: Read docs/wezdeck-runtime-release.md.
• Cutting a Go picker (native/picker/) release, updating its multi-asset release-manifest.json, or the install-side fetcher (WEZTERM_PICKER_INSTALL_SOURCE=auto|local|release) that lets end users without Go consume the prebuilt tarball: Read docs/picker-release.md.
• Diagnostics, logs, smoke tests, latency / hotkey counters, or operator troubleshooting (env knobs, file paths): Read docs/diagnostics.md.
• Personal development-habit weekly report（开发习惯周报 / habit weekly）: Load repo-local skill skills/habit-weekly/SKILL.md (habit-weekly; not linked to ~/.agents/skills); collector is scripts/dev/habit-report.sh. Not coco-weekly-report (business delivery).
• Guest OOM hardening (distro restart loop, reclaim livelock, high-order allocation / VM reboot; wsl-oom-guard.sh, M·… / earlyoom; standing memory consumers including MCP/uxc and IDE tsgo / goMemLimit; guest free calm while Windows VmmemWSL still large / scripts/dev/wsl-host-mem.sh): Read docs/guest-oom.md (Guest vs host memory meters).
• Host disk space (host volume full, ext4.vhdx never shrinking, sparse-VHD trap, trim→shutdown→Optimize-VHD / compact, OEM preinstalls, D·… badge): Read docs/host-disk.md.
• Unverified claims, deferred decisions, or "what still needs following up" on any of the above — dated, each with how to close it: Read docs/diagnostics.md#open-questions. Record new ones there rather than only in a commit body, which is not reviewable day to day.
• Cross-host failures (Windows, WSL, DNS, VPN/proxy, shells, agent CLIs); WezTerm silent exit / distro vanish; Failed to translate 'C:\…' / fake /mnt/c / unread image-path paste: Read docs/development-environment-troubleshooting.md.
• Adding or modifying a logger callsite, choosing a category, deciding log level / required fields, or moving a log file across the WSL boundary (author surface): Read docs/logging-conventions.md.
• Performance work on the Alt+/ popup, the cross-FS routing rule for state files, the bench harnesses, or the sync-runtime hot path (skip-if-current gates, rsync-vs-cp tradeoff, mtime-based change detection): Read docs/performance.md.
• IME candidate-window stability, DEC mode 2026 (synchronized output), why tmux 3.7+ is required, or agent-CLI render flicker investigation: Read docs/ime-flicker-and-sync-output.md.
• Sending a signal from a hook / picker / external helper into the WezTerm Lua process, picking between OSC and file transports, adding a new event, or migrating producers/consumers when upstream tmux or wezterm fix popup OSC pass-through: Read docs/event-bus.md.
• Per-workspace tmux-session focus statistics, the tab-stats-bump.sh hook chain, the on-disk <workspace>.json schema, weight decay / normalization formula, or planning the top-N tab bar slots / overflow tab / warm preheat layer: Read docs/tab-visibility.md.
• Ownership boundaries, runtime architecture, or entry points: Read docs/architecture.md.
• Agent 执行通道调度（人工 TUI / 跨仓工单 Ticket-headless / OpenClaw ACP·Main / 审查 headless）、host-agent-invoke 读写分档、「统一什么 / 刻意不合什么」、 或跨仓 票仓协议 vs 多目录挂载（战术）: Read docs/agent-scheduling.md（含 #ticket-vs-multi-dir-mount； 平台知识；不放 openclaw/docs/）。
• Env loading, secret placement, the ~/.config/shell-env.d/ convention, runtime-env-lib.sh::runtime_env_load_managed, or deciding whether a value belongs in wezterm-x/local/shared.env vs ~/.config/shell-env.d/: Read docs/setup.md#env-loading-model.
• Agent-CLI launch chain, agent-launcher.sh, the ${WEZDECK_REPO} placeholder used in config/worktree-task.env, or any path that spawns claude / codex: Read docs/architecture.md#startup-invariants.
• Adversarial code review skill (find→refute→repro), cross-agent backend selection, the shared lib/provider.sh layer, per-stage reasoning effort, the no-session-resume rationale, or offline mock testing: Read docs/adversarial-review.md.
• Multi-persona brainstorm skill (diverge→challenge→converge), persona/provider selection, per-stage effort, the no-resume design, or the offline mock harness: Read docs/brainstorm.md.
• Host-CLI invoke layers (one-way dependency):
  • Single-shot: adversarial-review/lib/provider.sh → run_agent / agent_text → plugin __invoke (no temp dir).
  • Multi-shot / parallel: agent-fanout/lib/fanout-lib.sh (fanout_call / fanout_run / fanout_run_jobs) + CLI run.sh. Fanout sources provider; provider never loads fanout. Do not hand-roll claude & wait or call __invoke from feature code. Offline smoke: scripts/dev/agent-fanout/test.sh. Notes: docs/adversarial-review.md / docs/brainstorm.md.
• Design proposal / RFC / ADR / 方案评审 (no runtime diff — not a dedicated skill): structured 设计评审 checklist and intent routing live in the user-level profile agent-profiles/v1/en/validation.md (Design proposal review); also summarized under docs/adversarial-review.md (out of scope) and docs/brainstorm.md (when alternatives are still needed).
• Host↔Claw session interop (Session Adapter Kit / session-bridge: list/read host tmux + claw sessions, gated poke / host-send-keys under lease, panic freeze, bot-send / say-as-me identities, attention merge, tmux side-load safety): Read openclaw/docs/session-bridge.md.
• Personal OpenClaw control plane (Feishu gateway templates, main-agent protocol, link/smoke scripts — not the WezTerm/tmux execution hot path): Read openclaw/README.md and openclaw/workspace/AGENTS.md.