# Known Limitations

[Back to README](../README.md)

| Limitation | Details |
|---|---|
| **Codex CLI: no terminal focus** | Codex official hooks and JSONL fallback do not carry a usable terminal PID. Clicking Clawd still won't jump to the Codex terminal. Claude Code and Copilot CLI work fine. |
| **Codex CLI: partial hook coverage** | Official hooks cover live state and `PermissionRequest` observation/intercept mode, but not every runtime signal. Clawd keeps JSONL polling active for hook-disabled sessions and fallback-only events such as web search, compaction, and aborted turns, so those state/metadata events can still have polling latency. Approval prompts are not inferred from JSONL; they require official `PermissionRequest` hooks. |
| **Copilot CLI: no Telegram remote approval (yet)** | Copilot permission bubbles work locally, but v1 wiring intentionally excludes Telegram remote approval. The `edit` tool's full diff is the worst-case payload and needs a safe summary formatter before it can be sent over the bridge. The local bubble path is unaffected. |
| **Gemini CLI: no permission bubble** | Gemini handles tool approval inside the terminal. Clawd observes Gemini hook events, but does not show permission bubbles unless Gemini adds a compatible blocking approval contract later. |
| **Antigravity CLI: no permission bubble (state-only)** | Clawd does **not** pop any permission bubble for agy. Every Allow / Deny / Always-allow choice happens in agy's own 5-option terminal menu (Yes / Yes Persist / No / Always Deny / Always Deny Persist). For a permanent rule, choose the menu item labeled "Persist to settings.json" in agy's menu — the rule lands in `~/.gemini/antigravity-cli/settings.json` where you can also clear it. Dogfooding showed that adding a Clawd bubble on top produced 8-10 confirmations per single user task, so Clawd intentionally lets agy own permission flow end-to-end. Pet still reflects working / idle / attention state via PreInvocation / PostToolUse / Stop hooks. |
| **Cursor Agent: no permission bubble** | Cursor handles permissions via stdout JSON in the hook, not HTTP blocking — Clawd can't intercept the approval flow. |
| **Cursor Agent: startup recovery** | No process detection on startup (matching the editor PID would false-trigger on any Cursor instance). Clawd stays idle until the first hook event fires. |
| **Hermes Agent: install required before use** | Hermes is listed in Settings but starts Not installed on fresh installs. Clawd does not write Hermes plugin files until you explicitly install the integration and a real Hermes install is detected. Install Hermes, then use **Settings -> Agents -> Install** or run `npm run install:hermes-plugin`. |
| **Hermes Agent: partial permission bubble support** | Hermes plugin events cover state, sessions, SessionEnd, tool activity, terminal focus, clarify elicitation bubbles, and plugin-originated permission bubbles. Clawd does not fully replace Hermes' native approval menu yet: `once` / `session` / `always` persistence still belongs to Hermes until upstream exposes a blocking approval-resolution hook. Subagent lifecycle also still needs paired upstream start/stop events. |
| **Hardware Buddy: external Clawstick runtime required** | Clawd v0.8.1 keeps the hardware runtime in the separate [Clawstick repository](https://github.com/rullerzhou-afk/clawstick). Install or checkout Clawstick separately, place it next to Clawd as `../clawstick`, or set `CLAWD_HARDWARE_BUDDY_ROOT`. If the runtime is missing, Clawd stays usable and Hardware Buddy reports `Install Clawstick` in Settings. |
| **Kiro CLI: no session tracking** | Kiro CLI stdin JSON has no session_id — all Kiro sessions are merged into a single tracked session. |
| **Kiro CLI: no SessionEnd** | Kiro CLI has no session end event, so Clawd can't detect when a Kiro session ends. |
| **Kiro CLI: no subagent detection** | Kiro CLI has no subagent events, so juggling/conducting animations won't trigger. |
| **Kiro CLI: terminal permission prompts stay in terminal** | Kiro state hooks are verified on macOS and Windows, but when Kiro shows native terminal permission prompts such as `t / y / n`, those still need to be handled in the terminal. Clawd does not currently replace that flow. |
| **Kimi Code CLI (Kimi-CLI): hook-only runtime path** | Kimi in Clawd is hook-only (`~/.kimi/config.toml`). If a future Kimi release breaks hook delivery, recover by reverting to the historical log-poll implementation from commit `e57679a` (the current `agents/kimi-log-monitor.js` is a compatibility stub). |
| **Kimi Code CLI (Kimi-CLI): `[[hooks]]` blocks referencing `kimi-hook.js` are owned by Clawd** | Clawd auto-syncs Kimi hooks on every startup (and from `npm run install:kimi-hooks`). Any `[[hooks]]` block whose `command` references `kimi-hook.js` is treated as Clawd-owned: all such blocks are removed and rewritten as the canonical 13 events (including any `CLAWD_KIMI_PERMISSION_MODE=…` prefix, which is carried over from a prior install when no env var is passed). Non-hook sections in `config.toml` (e.g. `[server]`, `[mcp]`, `[[tools]]`) and any `[[hooks]]` block you wrote yourself without referencing `kimi-hook.js` are left untouched. Change permission-mode behavior via env vars (e.g. `CLAWD_KIMI_PERMISSION_MODE`) before re-running the installer instead of hand-editing the `command` field. |
| **opencode: child sessions are background-only** | When opencode emits `session.created` with `event.properties.info.parentID`, Clawd treats that child/subtask as headless background work owned by the root session. It is hidden from HUD/focus surfaces and does not contribute to multi-session fanout animations. |
| **opencode: terminal focus limited to spawning terminal** | The plugin runs in-process with opencode, so `source_pid` points to the terminal that launched opencode. If you use `opencode attach` from a different window, terminal focus jumps to the original launcher. |
| **Pi: state-only integration** | Clawd observes Pi interactive-session lifecycle and tool events through a global extension, but does not intercept permissions or add confirmation prompts. Pi keeps its default YOLO execution behavior. |
| **Pi: session reload may briefly flicker** | Pi emits `session_shutdown` during reload/session replacement, then `session_start` for the new runtime. Clawd may briefly remove and recreate the Pi session. |
| **OpenClaw: state-only local TUI support** | Phase 1 observes OpenClaw plugin lifecycle/tool events for `openclaw tui --local`. It does not provide permission bubbles or terminal focus, and gateway/daemon/messaging deployments may not anchor to a local terminal window. |
| **OpenClaw: JSON5 config is not edited at startup** | OpenClaw accepts JSON5 and include-based config. Clawd startup sync edits only an existing strict JSON `~/.openclaw/openclaw.json`; JSON5/include configs are skipped unless you run the manual installer so OpenClaw's CLI can own the write. |
| **OpenClaw on Windows: native codex relay may fail** | If OpenClaw stalls or reports an unsafe native hook relay bridge when using its native `agentRuntime: codex` path, switch OpenClaw to an OpenAI-compatible model/provider such as `openai-codex/gpt-5.5`. This is OpenClaw-side behavior; Clawd only observes plugin state events and cannot repair the relay. |
| **CodeWhale: global session id cache** | Phase 1 keeps the last CodeWhale session id in a single file under `os.tmpdir()`. Running multiple CodeWhale instances concurrently can overwrite or clear that cache across instances, which may cross-wire state updates or create duplicate HUD labels. |
| **Qoder: state-only integration** | Phase 1 observes Qoder hook events via `~/.qoder/settings.json` for state and sessions. `PermissionRequest` / `PermissionDenied` are surfaced as passive notifications only — the hook always returns `{}` and never answers permission decisions, so every Allow / Deny choice stays in Qoder's native flow, with no Clawd permission bubbles. Startup recovery watches only the Qoder CLI processes (`qodercli` / `qoder-cli`), so an already-open idle Qoder IDE is not treated as active agent work. |
| **Windows Terminal: tab focus is limited** | Windows Terminal exposes one host window/process for multiple tabs, so Clawd cannot reliably activate a specific tab. HUD/Dashboard focus works best with separate classic `cmd.exe`/PowerShell windows, or with separate Windows Terminal windows whose title contains the project folder name. On Windows 11, `cmd.exe` and PowerShell may be hosted by Windows Terminal unless the default terminal application is set to Windows Console Host. |
| **macOS/Linux packaged auto-update** | DMG/AppImage/deb installs cannot auto-update — use `git clone` + `npm start` for auto-update via `git pull`, or download new versions manually from GitHub Releases. |
| **Linux/Wayland: limited dragging & cursor tracking** | Native Wayland forbids client-side window positioning and global cursor queries, so under a Wayland session the pet spawns centered, can't be dragged, and has no mouse tracking. On a Wayland session with an X server available, Clawd relaunches itself once under XWayland (`--ozone-platform=x11`) — Electron fixes the Ozone backend in C++ before any app code runs, so an in-process switch is too late — which restores window positioning and dragging; cursor tracking is then limited to the pet's own surfaces. Full-screen cursor tracking is **not** achievable under Wayland for an ordinary app — use a native X11 (Xorg) login session for that. `CLAWD_OZONE_PLATFORM` controls the automatic relaunch: `x11` forces the XWayland relaunch, `wayland`/`auto` keep the native-Wayland default; an explicit `--ozone-platform=…` you pass on the command line is always honored as-is. See [#441](https://github.com/rullerzhou-afk/clawd-on-desk/issues/441). |
| **No test framework for Electron** | Unit tests cover agents and log polling, but the Electron main process (state machine, windows, tray) has no automated tests. |
| **Claude Code: tools rejected when Clawd is offline** | When Clawd's HTTP server isn't running, the `PermissionRequest` hook (registered by Clawd) fails with `ECONNREFUSED`, and Claude Code currently denies the tool call instead of falling through to its built-in prompt — affecting `Edit`, `Write`, `Bash`, etc. This contradicts CC's documented non-blocking behavior for HTTP hook failures — see [anthropics/claude-code#46193](https://github.com/anthropics/claude-code/issues/46193). Workaround: keep Clawd running (recommended), or temporarily rename the `PermissionRequest` key in `~/.claude/settings.json` to disable the hook. |
| **Claude Code + CC Switch: protected auto-repair pause** | Clawd normally re-registers Claude hooks when another tool rewrites `~/.claude/settings.json`. If the file suddenly shrinks enough to look unsafe, Clawd pauses automatic repair to avoid preserving a partially rewritten config and Doctor reports Claude Code as needing Fix. Use **Settings -> Doctor -> Fix**, restart Clawd, or re-enable automatic Claude hook management to repair. CC Switch's Shared Config Snippet can carry Clawd hooks on the same machine, but those hooks include local paths and ports, so do not treat them as a cross-device snippet. |
