# 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 events can still have polling latency. |
| **Copilot CLI: manual local hook setup** | Local installs still require manually creating `~/.copilot/hooks/hooks.json`. Remote SSH installs are now configured automatically by `scripts/remote-deploy.sh`. |
| **Copilot CLI: no permission bubble** | Copilot's `preToolUse` hook only supports deny, not the full allow/deny flow. Permission bubbles currently work with Claude Code, Codex CLI, CodeBuddy, opencode, and Pi. |
| **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. |
| **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: visible before install** | Hermes is enabled in Settings by default so users can discover it, but Clawd does not write Hermes plugin files until a real Hermes install is detected. Install Hermes, then restart Clawd or run `npm run install:hermes-plugin`. |
| **Hermes Agent: no permission bubble or subagent animation yet** | Hermes plugin events currently cover state, sessions, SessionEnd, tool activity, and terminal focus. Permission bubbles and subagent lifecycle need upstream hooks with a blocking approval contract and paired subagent start/stop events. |
| **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: subtask menu clutter** | When opencode delegates to parallel subagents via the `task` tool, the subagent sessions briefly appear in the Sessions submenu while they run (5-8 seconds), then self-clean. Cosmetic only — the building animation fires correctly. |
| **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: permission bubbles are limited** | Clawd observes Pi interactive-session lifecycle events through a global extension. Pi permission bubbles cover only `bash`, `write`, and `edit` in the first version. If Clawd bubbles are unavailable, disabled, or suppressed by DND, the extension falls back to Pi terminal confirmation. |
| **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. |
| **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. |
| **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. |