wezdeck AGENTS.md

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.

Task Routing

• Setup, local prerequisites, or machine-local config: Read docs/setup.md.
• Sync, reload, verification, or day-to-day maintenance: Read docs/daily-workflow.md.
• 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: ~/.grok/bin/grok → wrapper, grok.real = ELF; required because zshrc prepends ~/.grok/bin), 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.
• 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 host-helper release, updating release-manifest.json, forcing the release-install branch, or side-loading the release zip: Read docs/host-helper-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, or smoke tests (operator surface — env knobs, file paths, troubleshooting); also guest-OOM hardening in all three of its shapes — the whole distro vanishing / restarting on a fixed interval, the reclaim livelock that pins every core, kills nothing, and leaves no OOM record, and the high-order (order:7 / vmbus_alloc_ring) allocation failure that kills the vsock channel and makes Windows reboot the whole VM while swap still looks healthy (wsl-oom-guard.sh, the wezterm-oom-protect / wezterm-oom-record units, the M·… / S·… memory badge, the fragmentation axis with its compact-then-SIGTERM relief, and install-earlyoom.sh); also host disk space (host volume full, ext4.vhdx growing but never shrinking, why --set-sparse is a trap, fstrim → wsl --shutdown → Optimize-VHD / compact vdisk, build-artifact inventory, OEM preinstalls, and the wsl-disk-guard.sh sampler + D·… headroom badge); also the standing-memory baseline for agent-side processes (per-session MCP cost, the chrome-devtools-mcp unbounded-heap leak and its uxc containment, uxc-session-reaper.sh, and why the Claude Code and OpenClaw sides are deliberately asymmetric); also the IDE-side TypeScript language server (tsgo / typescript.experimental.useTsgo) — why maxTsServerMemory does nothing to it, how js/ts.server.goMemLimit set below the live heap trades ~4 Gi of memory for a permanent ~1.5-core GC burn, the RSS-flat / faults-near-zero signature that identifies it, why only Developer: Reload Window applies a change to that key, and why the uncapped tsgo that Claude Code spawns on its own must be left uncapped: Read docs/diagnostics.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 development environment failures involving Windows, WSL, DNS, VPN/proxy software, shells, or agent CLIs; also the first-triage path when the whole WSL distro disappears at once (distro restart vs VM reboot): 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.
• 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 ${WEZTERM_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.