wraith

# Wraith CLI [](https://github.com/JavaLyHn/wraith/releases/latest) [](https://github.com/JavaLyHn/wraith/releases) [](https://github.com/JavaLyHn/wraith/releases/latest) A mature Java Agent product: from the first phase's `ReAct` single-agent loop to the sixteenth phase's `TUI productization`, and then to desktop apps and resident IM gateways (QQ / DingTalk single-chat bot). The core engine (ReAct / Plan / Multi-Agent / RAG / MCP / Skill / HITL) reuses the same Java kernel across CLI, desktop, and IM. ## Download Desktop version (macOS · Apple Silicon): Go to **[Releases](https://github.com/JavaLyHn/wraith/releases/latest)** to download `Wraith-<version>-arm64.dmg`. Self-contained JRE, no system Java required. > ⚠️ This version is not signed/not notarized, and Gatekeeper may quarantine it, reporting "damaged and cannot be opened" (right-click "Open" does not work). Solution: drag `Wraith.app` to `/Applications`, then run `sudo xattr -cr /Applications/Wraith.app` in the terminal (will prompt for login password; must add `sudo` because the built-in JRE contains read-only files), then double-click to open. Current progress: Completed phase 16.1 inline streaming TUI correction, phase 17 `LSP diagnostic injection` MVP, phase 18 `Git Side-History snapshot and rollback` MVP, phase 19 `Prompt hierarchical architecture` MVP, phase 20 `Asynchronous background tasks + Runtime API` MVP, phase 21 `Image copy-paste input` MVP, phase 23 `WeChat iLink channel` text MVP, phase 24 `IM gateway` (QQ / DingTalk single-chat bot + desktop configuration panel + scheduled task delivery). ## Test Strategy Daily development does not require running all tests. `mvn clean package` skips tests by default, prioritizing manually verifiable jars; regression testing is done based on changes: ```bash # Phase 16 terminal / TUI / inline renderer smoke test mvn test -Pphase16-smoke # Quick regression, skipping external process / network timeout / command timeout slow tests mvn test -Pquick # Code search deterministic golden set mvn test -Dtest=CodeSearchGoldenSetTest -DskipTests=false # Run full tests before release or major refactoring mvn test -DskipTests=false ``` ## Evolution ### Phase 1: ReAct Agent CLI - Single-turn dialogue-driven `ReAct` loop - Supports tool calls: read file, write file, list directory, file glob, code grep, execute command, create project, RAG semantic search, internet search, MCP dynamic tools - More suitable for simple tasks or single-step operations ### Phase 2: Plan-and-Execute + DAG - Adds complex task planning capabilities on top of `ReAct` mode - Supports breaking down tasks and executing them in dependency order - Adds `/plan` entry for one-time plan execution, enhancing default `ReAct` - Plan generation confirmed with user before execution - More suitable for multi-step, dependency-related complex tasks ### Phase 3: Memory + Context Engineering - Short-term memory manages current dialogue and tool results - Long-term memory saves key facts through `/save <fact>` or explicit user command "remember" - Project-level memory injected through `WRAITH.md` / `.wraith/WRAITH.md`, suitable for team-shared rules in repositories; `WRAITH.local.md` / `.wraith/WRAITH.local.md` for local overrides - Injected memory uses only long-term stable facts, not short-term dialogue - Automatic summarization when dialogue approaches budget - Adds `/memory` to view status, `/memory list/search/delete/clear` to manage long-term memory, `/save` to manually save facts; Agent calls `save_memory` when user says "remember" ### Phase 4: RAG Retrieval + Codebase Understanding - Code vectorization (Embedding), supporting local Ollama and remote API - SQLite persistence + cosine similarity semantic search - Code chunking (file/class/method granularity) and AST parsing - Code relationship graph (extends/implements/imports/calls/contains) - Adds `/index`, `/search`, `/graph` CLI commands - `search_code` as semantic search tool; precise code location uses `glob_files` / `grep_code` / `read_file` ### Phase 5: Multi-Agent Collaboration + Role Division - Three roles: Planner, Worker, Reviewer - Master-slave architecture: Orchestrator coordinates SubAgents - Planner breaks down tasks -> Worker executes -> Reviewer reviews quality - Review failure with feedback retry (up to 2 times), conflict resolution - Adds `/team` CLI command, entering multi-agent collaboration mode ### Phase 6: Human-in-the-Loop + Approval Flow - Static rule recognition for dangerous operations: `write_file`, `execute_command`, `create_project`, `revert_turn` - Three-level danger rating: high-risk (`execute_command`), medium-risk (`write_file` / `create_project`) - Approval decision: approve / allow all / reject / skip / modify parameters and execute - HITL disabled by default, enabled through `/hitl on` - Adds `/hitl` CLI command, supporting `/hitl on`, `/hitl off`, `/hitl` (view status) ### Phase 7: Asynchronous Execution + Parallel Tool Calls - Same turn LLM returns multiple `tool_calls`, tool layer executes in parallel - ReAct, Plan-and-Execute, Multi-Agent Worker reuse unified batch tool execution entry - Tool results still filled in original `tool_calls` order, ensuring message history protocol stability - Unified timeout and cancellation for batch tool calls, individual `execute_command` retains 60-second command-level timeout - Plan-and-Execute and Multi-Agent support parallel execution of independent tasks in batches ### Phase 8: Multi-Model Adaptation + Runtime Switching - `LlmClient` interface abstraction + `AbstractOpenAiCompatibleClient` template base class - Built-in six slim implementations: `GLMClient`, `DeepSeekClient`, `StepClient`, `KimiClient`, `FreeLlmApiClient`, `XfyunMaaSClient` - `/model glm-5.1` / `/model glm-5v-turbo` explicitly switch to GLM model; `/model deepseek` / `/model step` / `/model kimi` / `/model freellmapi` / `/model xfyun` switch provider and read specific model from config - `freellmapi` is universal **OpenAI compatible** entry: point `--base-url` to any OpenAI compatible endpoint to access custom model without code changes - Configuration persisted to `~/.wraith/config.json`, API Key can be read from config, environment variables, or `.env` ### Phase 9: Internet Capability + Web Tools - `web_search` abstracted as `SearchProvider` interface, with three built-in implementations: ZhiPu Web Search (default, shares key with GLM, 0.01–0.05 yuan/ query), SerpAPI (international paid), SearXNG (open-source self-hosted free) - `web_fetch` new tool: URL → OkHttp fetch → Jsoup parse → simple readability → Markdown content - When current model is `step-3.7-flash*` and auto/explicit `step_search` remote server is ready, built-in `web_search` / `web_fetch` prioritize StepSearch MCP; fallback to original provider on failure - ReAct pre-checks for temporal problems like "latest/current/today/this year/2026/trends/news/version" with `web_search` and injects into context - Default security policy: shields `file://` / intranet / loopback; 30-second timeout; 5MB response limit; 30 queries per minute - Boundary handling: SPA / anti-crawling sites return empty content + known boundary hints, Agent falls back to browser MCP route ### Phase 10: MCP Protocol Core - Introduced `com.lyhn.wraith.mcp` module, supporting stdio subprocess server and Streamable HTTP remote server - Reads `~/.wraith/mcp.json` and `.wraith/mcp.json` at startup, project-level config overrides user-level config by server name - MCP `${VAR}` supports system environment variables, system properties, project `.env`, user `~/.env`; detects `STEP_API_KEY` and automatically builds `step_search` remote MCP - MCP tools automatically registered as `mcp__{server}__{tool}`, parameter schema cleans `$ref` / `anyOf` / long description to reduce model call failure rate - All MCP tools default to HITL approval and auditing, auditing parameters desensitize token / key / password / Authorization / Bearer credentials - Supports MCP resources: server declares `resources` capability, automatically registers `mcp__{server}__list_resources` / `mcp__{server}__read_resource` virtual tools - Plain input supports `@server:protocol://path` explicit resource reference, expands to `<resource>` inline block before submitting to Agent - Passively handles `notifications/tools/list_changed`, `notifications/resources/list_changed`, `notifications/resources/updated` - Running input `/cancel` and pressing Enter requests cancellation of current Agent run - CLI commands: `/mcp`, `/mcp restart <name>`, `/mcp logs <name>`, `/mcp disable <name>`, `/mcp enable <name>`, `/mcp resources <name>`, `/mcp prompts <name>` - `~/.wraith/mcp.json` is automatically created with default chrome-devtools config if it does not exist; project-level `.wraith/mcp.json` can override by server name ### Phase 12: Long Context Engineering - `LlmClient` declares model capabilities: `maxContextWindow()`, `supportsPromptCaching()`, `promptCacheMode()` - GLM-5.1 defaults to 200k window, DeepSeek V4 defaults to 1M window, StepFun defaults to 256k window, Kimi K2.6 defaults to 256k window, FreeLLMAPI defaults to conservative 128k budget - `AgentBudget` dynamically calculates budget based on current model, defaulting to `80% * maxContextWindow`, can be overridden by system properties - Three context modes: short / balanced / long; long context mode skips summarization, semantic search topK can be increased to 20 - `search_code` adaptively sets `top_k` based on context mode; default code location still prioritizes real-time grep/read - Long context mode automatically injects MCP resources' URI / description index into system prompt, not injecting content - Inline mode displays token / cached input tokens / estimated cost / time consumption at the bottom status bar, avoiding occupying output area - `/context` displays current context mode, prompt cache mode, RAG topK, and resource auto-indexing status ### Phase 13: Chrome DevTools MCP - Defaults to Google's official `chrome-devtools-mcp@latest`, registering browser tools like `mcp__chrome-devtools__navigate_page`, `take_snapshot`, `click`, `fill_form` - `~/.wraith/mcp.json` is automatically created with a template if it does not exist, using `--isolated=true` temporary browser profile by default - Used for handling SPA / JS rendering / anti-crawling / form interaction pages; sites like WeChat official accounts, Zhihu columns, Twitter, and Xiaohongshu that fail `web_fetch` are guided to use browser MCP - HITL's "allow all" supports MCP server dimension, continuous browser operations can confirm once for `chrome-devtools` - `image` type results are attached as image input to the next turn; text fallback remains for logs, human-readable summaries, and API that does not accept images - MCP initialize defaults to 60-second timeout; CLI first screen waits up to 8 seconds, then enters interaction; unfinished server remains `starting` and continues in the background, can be tracked with `/mcp` and `/mcp logs <name>` ### Phase 14: CDP Session Reuse + Login State Access - Adds `/browser status`, `/browser connect [port]`, `/browser disconnect`, `/browser tabs` command group, exposing internal `browser_connect` / `browser_disconnect` / `browser_status` tools to Agent - Defaults to `--isolated=true` temporary browser profile; after `/browser connect`, runtime switches `chrome-devtools` to `--autoConnect`, reusing the login state Chrome allowed for remote debugging at `chrome://inspect/#remote-debugging` - When encountering login pages, permission denied, or pages requiring login state, Agent calls `browser_connect` to switch to shared; public pages like WeChat official accounts do not switch - `/browser connect <port>` retains old CDP port compatibility path: probes `127.0.0.1:<port>/json/version`, then switches to `--browser-url=http://127.0.0.1:<port>`; fails to change MCP startup parameters and outputs Chrome startup commands for macOS / Windows / Linux - Switching shared / isolated modes clears `chrome-devtools` server dimension allow-all, avoiding old trust continuation across modes - In shared mode, `close_page` can only close tabs created by Wraith CLI; tabs not proven to be created by Wraith CLI are rejected by policy layer - Sensitive pages trigger rules, and modifying tools like `click` / `fill_form` / `evaluate_script` must undergo single-step HITL approval, not reusing allow-all; read-only tools like `take_snapshot` continue to be used - Audit logs append optional browser metadata for chrome-devtools tools: `browser_mode`, `sensitive`, `target_url`, readable by old JSONL format ### Phase 15: Skill System + Built-in Web-Access Skill Extracts how an Agent thinks from hardcoded system prompts into reusable units. Each Skill is a directory: `SKILL.md` (decision manual) + `references/` (on-demand reading) + optional `scripts/` (executable dependencies). - Three loading locations (by priority, latter overrides same-named skill): built-in jar < user-level `~/.wraith/skills/<name>/` < project-level `<project>/.wraith/skills/<name>/` - At startup, injects enabled skill `name` + `description` into three Agent system prompt index segments (enabling up to 20 skills, index segments ≤ 4KB) - Built-in `load_skill(name)` tool: when LLM sees matching description in system prompt, it actively calls, and Wraith CLI writes `SkillContextBuffer` with SKILL.md content (truncated to 5KB), automatically injecting before next user message - Built-in web-access skill: decision manual (browsing philosophy four-step method + tool selection table + browser priority + Jina fallback) + 6 site experience files (mp.weixin / zhuanlan.zhihu / x.com / xiaohongshu / github / juejin) + cdp-cheatsheet - Frontmatter uses handwritten YAML subset parsing, not SnakeYAML; parsing failure warns on stderr but does not block startup - CLI commands: `/skill list` / `/skill show <name>` / `/skill on <name>` / `/skill off <name>` / `/skill reload` - Enabled status persisted to `~/.wraith/skills.json`'s `disabled` list, defaulting to all enabled - Collaborates with HITL: Skill invoking dangerous tools like `execute_command` still undergoes existing HITL approval, following `execute_command` tool dimension allow-all; no separate approval dimension for Skills Design intention: evolves from "writing tools" to "packaging expert manuals". When tools pile up (Wraith CLI currently has 9 built-in + 60+ MCP tools), using Skills provides LLM with a scene-specific "expert manual", more scalable than stuffing system prompts. ### v16: TUI Productization (v16.1: Dual-Mode Switchable) v16.1 extracts the `Renderer` interface and three implementations: | Mode | Enable Method | Visual Style | |---|---|---| | **inline Streaming TUI** (default) | Direct run / `WRAITH_RENDERER=inline` | Claude Code / Qoder style: WRAITH intro animation + top-left resident banner, direct output on main screen, `│ › ` bottom-left input box, JLine `Status` managed bottom dock (YOLO/HITL, MCP, Skill, model, ctx, token, cwd, etc. key fields with subtle color highlighting; ctx is current context estimation, in/out/cache is call statistics), right-side input suggestions, inline collapsible tool blocks (`Read 3 files (ctrl+o to expand)`), inline git diff, HITL single-character `[y/n/a/s/m]` prompt | | **lanterna Full-Screen TUI** | `WRAITH_RENDERER=lanterna` (or compatible old `WRAITH_TUI=true`) | v16 three-column full-screen: file tree + conversation flow + status bar + bottom input bar, HITL modal popups | | **plain Fallback** | `WRAITH_RENDERER=plain` | Pure println, no folding / status bar, equivalent to v15 behavior | - Three modes share the same `Agent` / `ToolRegistry` / `MemoryManager` / MCP server / SkillRegistry / HITL handler, without creating isolated empty sessions - Normal input goes through ReAct; `/plan <task>` goes through Plan-and-Execute; `/team <task>` goes through Multi-Agent; `/cancel` can cancel running tasks - Universal commands: `/clear`, `/context`, `/memory`, `/memory clear`, `/save <fact>`, `/export`, `/hitl`, `/hitl on`, `/hitl off`, `/config`, `/exit` - Conversation history saved to `~/.wraith/history/session_*.jsonl` - Compatible with old settings: `WRAITH_TUI=true` automatically maps to `WRAITH_RENDERER=lanterna` (deprecated) - `WRAITH_NO_STATUSBAR=true` disables JLine bottom dock in inline mode (not suitable for ANSI cursor control terminals) - `NO_COLOR=1` disables all ANSI colors, preserving layout - Smart Tab: when input line shows fish-style history prediction (gray autosuggestion), press `Tab` to complete the suggestion; otherwise, `Tab` still goes through `/` command completion - Intro animation: WRAITH logo with ANSI-Shadow 3D white, with model / MCP / capability information in bold cyan highlighting below, **resident in top-left corner** (kept visible when conversation scrolls; automatically degraded to scroll with conversation when terminal is too short or does not support scrolling) - Input box: "bottom-left box": line-start dark-gray vertical line `│` + `› ` prompt, with dock self-drawn ` ╰────` underline (`╰` aligned with `│` in the same column) - Multi-line input: line-end `\` + Enter to continue line; `Ctrl+J` (and some terminals' `Alt+Enter`) inserts a line break at the cursor; `Enter` submits. Continued lines show aligned continuation prompts (`│` vertical line continuous across lines), and paste multi-line content as usual. Continued line `\` is consumed when submitted (final text has clean line breaks); **pasted** content's `\` + line breaks are preserved (C macros / shell continuation not swallowed) - Mouse click positioning: click in input area with left mouse button, cursor jumps to corresponding position (aware of multi-line / continued lines). Enabled by default, only effective during `readLine` (Agent output / review scrolling has native mouse selection); `WRAITH_MOUSE=off` can disable (users accustomed to dragging selected area to copy, or macOS `⌥`-drag to bypass) ### v17: LSP Diagnostics Injection (MVP) - `write_file` triggers post-edit diagnostics after success, with diagnostic results not blocking the tool's main process - Current MVP uses JavaParser for lightweight syntax diagnostics on Java files, without relying on a locally installed JDT LS - ReAct, Plan-and-Execute, and Multi-Agent paths inject pending diagnostics before the next LLM request - Diagnostics are formatted with error / warning / info, file, line and column numbers, and message, with a maximum of 20 injected by default - Configuration: `WRAITH_LSP_ENABLED=false` can disable, `WRAITH_LSP_MAX_DIAGNOSTICS=20` can adjust the injection limit - Future enhancements: integrate with JDT LS / rust-analyzer / pyright / gopls stdio JSON-RPC transport ### v18: Git Side-History Snapshot and Rollback (MVP) - Create `pre-turn` snapshot before each ReAct / Plan / Team turn, and asynchronously create `post-turn` snapshot after the turn - Snapshot repository uses JGit pure Java implementation, default location `~/.wraith/snapshots/<project_hash>/<worktree_hash>/.git`, without writing to the user's project `.git` - `/snapshot` views recent snapshots, `/snapshot status` views configuration and side-git directory, `/snapshot clean` cleans the current project snapshot directory - `/restore <N>` restores to the Nth `pre-turn` snapshot; creates a `pre-restore` snapshot before restoration - Agent built-in `revert_turn` tool, included in HITL and AuditLog risk tool chain - Configuration: `WRAITH_SNAPSHOT_ENABLED=false` can disable, `WRAITH_SNAPSHOT_MAX=50`, `WRAITH_SNAPSHOT_EXCLUDES=...`, `WRAITH_SNAPSHOT_DIR=...` can adjust strategy ### v19: Prompt Layered Architecture (MVP) - ReAct, Plan task executor, Multi-Agent three roles, and Planner's system prompt have been separated from Java hardcoding to `src/main/resources/prompts/` - `PromptAssembler` assembles according to `base -> personality -> mode -> approval -> runtime_context -> project_context -> skills -> context_mgmt -> handoff`; `runtime_context` injects current date and time zone, dynamic project context injected later - `project_context` injects `WRAITH.md` project memory, then injects relevant long-term memory and MCP resource index retrieved from `/save` - Supports user-level override `~/.wraith/prompts/...`, project-level override `.wraith/prompts/...`, with project-level priority highest - Override is a whole file replacement; `base.md` and final prompt must contain `## Language` - Prompt change audit template see `docs/prompt-analysis-template.md` ### v20: Asynchronous Background Tasks + Runtime API (MVP) - `DurableTaskManager` uses SQLite to persist background task queue, default location `~/.wraith/tasks/tasks.db` - Task lifecycle: `enqueued -> running -> completed / failed / canceled` - `/task`, `/task add <task content>`, `/task cancel <task_id>`, `/task log <task_id>` provide CLI closed-loop - Worker Pool defaults to 2 background workers, adjustable via `WRAITH_TASK_WORKERS` - `java -jar target/wraith-1.0-SNAPSHOT.jar serve --http --port 8080` starts localhost Runtime API - Runtime API endpoints: `POST /v1/threads`, `POST /v1/threads/{id}/turns`, `GET /v1/threads/{id}/events` - Runtime API requires `WRAITH_RUNTIME_API_KEY` or `-Dwraith.runtime.api.key` - Detailed documentation see `docs/phase-20-runtime-api.md` ### v21: Image Copy-Paste Input (MVP) - `LlmClient.Message` supports `ContentPart`, including `text`, `image_base64`, `image_url` - Request body outputs content array with image blocks when containing images, still keeping string content for pure text - `LlmClient` public interface does not declare image capability; input layer only reads, compresses, and attaches images, with provider API responsible for final reception or error return - GLM package users can switch to GLM-5V-Turbo multi-modal model via `/model glm-5v-turbo`, then input images with Ctrl+V or `@image:`; local base64 images are written to `image_url.url` in ZhiPu format - MCP `image` content retains base64 and `mimeType`, and is used as user message feedback after ReAct / Plan / SubAgent tool results - Users can reference local images via `@image:file:///abs/path.png`, `@image:/abs/path.png`, or `@image:relative/path.png` - Local and MCP images are preprocessed according to Claude Code strategy: not OCR to text, but compressed and scaled as image blocks sent; PNG with alpha channel is laid with white background and re-encoded; source, size, and coordinate mapping metadata are additionally injected - Local `@image:` messages require the model to prioritize analysis of the current image; unless the user explicitly requests combination with history, historical conversation and tool results cannot replace current image content - New round of ReAct / SubAgent tasks skips historical image payload before starting, only retaining text metadata; model `reasoning_content` writes logs / display by default, and DeepSeek V4 / Kimi thinking tool-calls continue to bring back previous round assistant reasoning according to provider protocol - DeepSeek streaming calls use HTTP/1.1 by default to avoid `stream was reset: INTERNAL_ERROR` caused by some HTTP/2 gateway long SSE responses being reset ### v23: WeChat iLink Channel (Text MVP) - New process-level entry: `wraith wechat setup`, `wraith wechat start`, `wraith wechat status`, `wraith wechat daemon start|stop|restart|status|logs` - New interactive entry: input `/wechat` in Wraith CLI main interface to scan code and bind, then start WeChat channel in current process background; `/wechat setup` re-scans code and binds, `/wechat status` views status, `/wechat stop` stops the channel - WeChat channel is not enabled by default; users must actively execute `setup` and scan code to confirm binding - Supports displaying 260px PNG QR code in compatible terminals like Warp / iTerm2 / WezTerm; falls back to character QR code and link when terminal image protocol is not supported - WeChat side uses iLink `getupdates` long polling to receive messages, `sendmessage` to send messages in chunks, without relying on SSE; this is an independent channel, not a Skill, nor Runtime API - Only accepts private chat from bound users at runtime; normal messages are queued and sent one by one; `/help`, `/status`, `/pause`, `/resume`, `/stop` go through out-of-queue control path - WeChat user messages are echoed to Wraith CLI terminal transcript; Wraith CLI terminal continues to display thinking / tool call process, while WeChat side only receives assistant text. iLink protocol layer is still `text_item.text` text message, without explicit Markdown parse mode; Wraith CLI retains ClawBot stable-supported Markdown subset (lists, quotes, bold, inline code, real code blocks), converts headings to bold headings, tables to mobile-friendly key-value / lists, and filters incompatible markup like image Markdown / H5-H6 / Chinese italics; iLink does not provide real SSE or single message capability - WeChat channel uses non-interactive default reject strategy: read-only tools are allowed by default, `write_file` / `create_project` are still restricted by workspace PathGuard, `execute_command` must exactly hit the command whitelist, `mcp__*` must hit MCP whitelist, `revert_turn` and browser session switching are rejected by default - Current text MVP retains media metadata hints for images / file messages, but CDN download decryption, image block input, and `/send` file push are still pending media link completion ### v24: IM Gateway (QQ / Feishu Single Chat Bot + Desktop Configuration Panel + Scheduled Task Delivery) Connect Wraith as a resident IM bot: a local Java daemon process `wraith gateway` receives and sends messages, runs Agent turns, and pushes HITL approval to the IM end. All built-in tools + MCP + Skill + memory are available in IM form. - **Multi-platform provider architecture** (`gateway/spi/ImProvider`): SPI defines `platform / start / stop / deliveryAdapter / surfaceScheduledApproval`; daemon iterates through configured providers, each running on a separate daemon thread, with the main thread blocking and resident. Session core (`SessionRouter` / `ImTurnDriver` / `GatewaySession` / `GatewayRenderer` / `Authorizer` / `Dedup`) is platform-independent and reused by each provider; each provider has its own independent session routing and does not interfere with other providers. Adding a third platform is purely incremental. - **QQ Single Chat** (`gateway/qq`): official personal bot, `wraith gateway bind` scans code to bind and obtain appId / key, WS gateway direct connection + REST feedback; HITL uses QQ inline keyboard three-button; restricted by QQ passive reply window (60 minutes / ≤4 messages per msg_id), delivery uses "pending queue + next station flushing". - **Feishu / Lark Single Chat** (`gateway/feishu`): official Java SDK (`com.larksuite.oapi:oapi-sdk`) **long connection** receives events - only outgoing, no public URL required, suitable for local daemon; REST `im.message.create` feedback, unified use of `open_id` (authentication / session key / feedback target integration); HITL uses Feishu **interactive card buttons** (`card.action.trigger` callback sent via the same long connection); Feishu can actively send messages at any time, with result delivery and approval card immediately sent (no pending queue). Credentials are manually filled in after building a self-built application on Feishu open platform; owner identity uses fail-closed + open_id pairing and feedback (first private chat bot feedback your open_id, fill in desktop to bind). Feishu / Lark dual-region switchable. - **Authentication**: deny-all, only allowing bound owner's openid - incoming messages and button callbacks are verified according to platform-authenticated real identity. - **Desktop Configuration Panel**: desktop "IM Gateway" screen visual configuration - platform card switching, manual key filling (package only reports `hasSecret`, **never returns plaintext**), start / stop daemon process, structured status light (daemon process output `WRAITH_GATEWAY_STATUS`, desktop light), log viewing. Backend `AppServer`'s `gateway.config.get/set` RPC with `platform` parameter (default QQ, backward compatible), read and write `~/.wraith/config.json`. - **Scheduled Task Delivery** (`automation/`): resident scheduler (interval / daily / weekly) runs unattended turns, `Deliverer` + `DeliveryAdapter` SPI delivers results to desktop notifications or IM (`DesktopDeliveryAdapter` / `QqDeliveryAdapter` / `FeishuDeliveryAdapter`); HITL approval for scheduled tasks can also pop up on IM and wake up suspended turns. cron is independent of IM - no IM configured, only runs scheduled tasks. - **Secret Red Line**: appId / clientSecret / appSecret only lands in `~/.wraith/config.json` (outside repository), never into logs or RPC response; IM environment values do not appear in any return transmission. ### Phase 6 HITL Enhancement (Path Fencing / Fast Command Rejection / Operation Audit) `com.lyhn.wraith.policy` package, as an auxiliary layer outside HITL (not a sandbox, no process isolation): - `PathGuard` path fencing: file-type tools are strictly limited within the project root, intercepting absolute path escape / `..` traversal / symbolic link escape - `CommandGuard` fast command rejection: HITL pre-fast-fail blacklist (`sudo` / `rm -rf entire disk` / `mkfs` / `dd of=/dev` / fork bomb / `curl|sh` / `find /` / `chmod 777 /` / `shutdown`), reducing HITL pop-up disturbance - `AuditLog` structured audit: dangerous tool calls are written to JSONL in `~/.wraith/audit/` by day, containing `outcome (allow|deny|error)` and `approver (hitl|policy|none)`; `revert_turn` is also included in the risk tool chain - `write_file` single file 5MB limit - CLI command: `/policy` views security policy status, `/audit [N]` views recent N audit logs **Why not called sandbox**: local Agent CLI (refer to Claude Code / Cursor / Aider) does not use container/VM sandbox by default - sandbox weakens Agent capability, gives false security, and worsens experience. Production-level Agent sandbox is actually microVM-level (Devin / Modal / Anthropic Computer Use uses Firecracker / gVisor). Wraith CLI's security model is **HITL + path verification + fast command rejection + audit**, not isolation. ### Current Startup Interface The current startup output is based on the actual command line output: ```text ██╗ ██╗██████╗ █████╗ ██╗████████╗██╗ ██╗ ██║ ██║██╔══██╗██╔══██╗██║╚══██╔══╝██║ ██║ ██║ █╗ ██║██████╔╝███████║██║ ██║ ███████║ ██║███╗██║██╔══██╗██╔══██║██║ ██║ ██╔══██║ ╚███╔███╔╝██║ ██║██║ ██║██║ ██║ ██║ ██║ ╚══╝╚══╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═╝ ╚═╝ ╚═╝ Wraith CLI v16.1.0 Model DeepSeek-V4-Flash (freellmapi) MCP 1/1 · 29 tools · 1/1 skills · ReAct ReAct · Plan · MCP · Browser · Image · Tools · Memory · RAG Tips for getting started: 1. Type / for commands and Tab completion 2. Ask coding questions, edit code or run commands 3. Attach context with @path or @image: ``` ## Features ### Phase 1 - 🤖 Intelligent dialogue based on GLM-5.1 - 🔄 ReAct Agent loop (think-act-observe) - 🛠️ Tool calls (file operations, deterministic code search, shell commands, project creation, RAG semantic search, web search, MCP dynamic tools) - 💬 Interactive command line interface - 📝 Normal tasks and slash commands will write back the original input as a dark block to the transcript; - 🧠 Default model output obtained through streaming interface; - 🖥️ Terminal renders common Markdown (headers, lists, tables, code blocks) before displaying; ### Phase 2 - 📋 Plan-and-Execute + DAG task decomposition and sequential execution - ⌨️ `/plan` enters plan execution at once - 🧭 Clearer execution sequence and dependency display for complex tasks - ⚖️ Simple tasks automatically generate minimal plans, no longer extending irrelevant steps ### Phase 3 - 🧠 Short-term memory, long-term memory, and related memory retrieval - 📦 Long conversation summary compression and token budget management - 🧮 Dynamic budget for long context, prompt cache visibility, and cost estimation - 💾 `/memory` and `/save` memory management portal ### Phase 4 - 🔍 Real-time code base search + RAG semantic assistance (precise positioning priority glob/grep/read, natural language fuzzy query then search_code) - 🕸️ Code relation graph (class inheritance, interface implementation, method call) - 📡 Local Ollama Embedding + remote API configurable - 🗃️ SQLite vector storage and persistence ### Phase 5 - 👥 Multi-agent collaboration (planner + executor + inspector) - 🎯 Master-slave architecture scheduler automatically allocates tasks - 🔍 Inspector reviews quality, automatic retry if failed - 🛠️ Executors share toolset, support file operations and code retrieval ### Phase 6 - 🔒 Static rule identification for dangerous operations (`write_file` / `execute_command` / `create_project` / `revert_turn`) - ⚠️ Three-level risk display (high/medium/low) - ✅ Approval decision: approve, allow all, reject, skip, execute after modifying parameters - 🔓 HITL defaults to off, `/hitl on` enables, `/hitl off` disables ### Phase 7 - ⚡ Multiple tool calls in the same round will execute in parallel, suitable for reading multiple files, listing directories, and running independent checks simultaneously - 🧵 ReAct, Plan-and-Execute, and Multi-Agent Worker share the same parallel tool execution mechanism - ⏱️ Tool batches have unified timeout, timed out tools will be canceled and results will be returned to the model - 📋 Plan-and-Execute and Multi-Agent will advance independent tasks in parallel according to DAG dependencies ### Phase 8 - 🔄 GLM-5.1, GLM-5V-Turbo, DeepSeek V4, StepFun, Kimi K2.6, FreeLLMAPI, and Xfyun MaaS (xfyun) multi-models, - 🧱 `LlmClient` interface + `AbstractOpenAiCompatibleClient` template method base class, adding a provider requires only ~20 lines - 🔌 Custom model access: any OpenAI compatible endpoint uses `freellmapi` - 💾 Default model persisted to `~/.wraith/config.json` ### Phase 9 - 🌐 `web_search` tool supports four options: - 📰 `web_fetch` tool: fetch URL → readability extraction → return Markdown content - 🛡️ Built-in network access policy: shield intranet, loopback, `file://`; 5MB response limit; 30 requests per minute - 🚧 Boundary clear: SPA / anti-climbing returns empty content + known boundary prompts, no retry ### Phase 6 HITL Enhancement - 🛡️ Path fence: file tool forced to limit within project root, - 🧯 Command fast reject: HITL pre-fast-fail blacklist - 📦 Resource limit: `write_file` 5MB; `execute_command` 60s timeout + 8KB output truncation - 📋 Structured audit: dangerous tool calls written to `~/.wraith/audit/` in JSONL format - 🧱 Positioning: auxiliary layer outside HITL, not sandbox, no process isolation ## Quick Start ### 1. Configure API Key Copy `.env.example` to `.env` and fill in your GLM, DeepSeek, StepFun, Kimi, FreeLLMAPI, or Xfyun MaaS (xfyun) API Key: ```bash cp .env.example .env # Edit .env file and fill in your API Key ``` Or set environment variables: ```bash export GLM_API_KEY=your_api_key_here # Or export STEP_API_KEY=your_step_api_key_here export STEP_MODEL=step-3.5-flash # Or export KIMI_API_KEY=your_kimi_api_key_here export KIMI_MODEL=kimi-k2.6 # Or export FREELLMAPI_API_KEY=your_freellmapi_unified_key_here export FREELLMAPI_BASE_URL=http://localhost:5173/v1 export FREELLMAPI_MODEL=auto ``` You can also write to `~/.wraith/config.json` using commands within Wraith CLI: ```text /config provider freellmapi --base-url http://localhost:5173/v1 --api-key <key> --model auto /model freellmapi ``` Long-term memory is saved in `~/.wraith/memory/long_term_memory.json` by default. Long-term memory only saves stable facts under explicit save intention: `/save <fact>`, or when the user explicitly says "remember / save for later" in natural language, the agent calls `save_memory`. It is saved by default for the current project scope; global preferences can be saved using `/save --global <fact>` or `save_memory(scope=global)`. You can view long-term memory using `/memory list`, search for memories in the current project using `/memory search <keywords>`, and delete a single memory using `/memory delete <id>`. Project-level memory uses Markdown files for maintenance, different from long-term memory saved with `/save`: - `~/.wraith/WRAITH.md`: user-level stable preferences, visible to all projects. - `WRAITH.md` / `.wraith/WRAITH.md`: project-level team rules, recommended to be submitted to git. - `WRAITH.local.md` / `.wraith/WRAITH.local.md`: local override, suitable for personal debugging conventions, recommended to be added to `.gitignore`. - `@relative/path.md`: import relative files within the project root in `WRAITH.md`; You can generate a short `WRAITH.md` for the current project using `/init`. This command does not overwrite existing files by default; use `/init --force` to rebuild. Code index is saved in `~/.wraith/rag/codebase.db` by default. Debug logs are written to `~/.wraith/logs/wraith.log` by default, and old logs are automatically cleaned according to retention days and total capacity. ReAct / Plan task / SubAgent / Planner model `reasoning_content` is written to this log in the form of `LLM reasoning [...]`, which is convenient for troubleshooting. If you want to specify a separate directory for a certain run, you can pass: ```bash # Specify memory directory java -Dwraith.memory.dir=/tmp/wraith-memory -jar target/wraith-1.0-SNAPSHOT.jar # Specify RAG index directory java -Dwraith.rag.dir=/tmp/wraith-rag -jar target/wraith-1.0-SNAPSHOT.jar # Specify log directory and retention policy java -Dwraith.log.dir=/tmp/wraith-logs \ -Dwraith.log.level=DEBUG \ -Dwraith.log.maxHistory=3 \ -Dwraith.log.maxFileSize=5MB \ -Dwraith.log.totalSizeCap=20MB \ -jar target/wraith-1.0-SNAPSHOT.jar ``` You can also put it in `.env` or environment variables: ```bash WRAITH_LOG_LEVEL=DEBUG WRAITH_LOG_DIR=/Users/yourname/.wraith/logs WRAITH_LOG_MAX_HISTORY=7 WRAITH_LOG_MAX_FILE_SIZE=10MB WRAITH_LOG_TOTAL_SIZE_CAP=100MB ``` ### 2. Optional: Configure MCP Server MCP subsystem is enabled by default. When `~/.wraith/mcp.json` does not exist, Wraith CLI will automatically create a default chrome-devtools configuration: ```json { "mcpServers": { "chrome-devtools": { "command": "npx", "args": ["-y", "chrome-devtools-mcp@latest", "--isolated=true"] } } } ``` When you need to access other servers, you can edit `~/.wraith/mcp.json` or `.wraith/mcp.json` in the project: ```json { "mcpServers": { "fetch": { "command": "uvx", "args": ["mcp-server-fetch"] }, "git": { "command": "uvx", "args": ["mcp-server-git", "--repository", "${PROJECT_DIR}"] }, "remote-demo": { "url": "https://mcp.example.com/v1", "headers": {"Authorization": "Bearer ${REMOTE_TOKEN}"} }, "step_search": { "url": "https://api.stepfun.com/step_plan/v1/mcp/web_search/mcp", "headers": {"Authorization": "Bearer ${STEP_API_KEY}"} } } } ``` `command` represents stdio server, `url` represents Streamable HTTP server. `${PROJECT_DIR}` / `${HOME}` are built-in variables, other `${VAR}` reads from environment variables; missing variables will be prompted directly at startup. `step_search` is a conventional name: if the project `.env`, user `~/.env`, or system environment variables contain `STEP_API_KEY`, Wraith CLI will automatically build this remote MCP; the above manual configuration is only used to override the default address or customize authentication. When the current model is `step-3.7-flash*`, built-in `web_search` / `web_fetch` will prefer to proxy to this MCP server. When reusing the current login status, Chrome 144+ recommends enabling `chrome://inspect/#remote-debugging` and checking `Allow remote debugging for this browser instance`. For older versions or when a explicit CDP port is required, you can start Chrome with a remote debugging port and an independent user-data-dir, and complete the login in this debugging Chrome: ```bash # macOS open -na "Google Chrome" --args --remote-debugging-port=9222 --user-data-dir=/tmp/wraith-chrome-profile # Windows start chrome.exe --remote-debugging-port=9222 --user-data-dir=%TEMP%\wraith-chrome-profile # Linux google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/wraith-chrome-profile ``` Usually, no user action is required; if the agent encounters a login page, it will call `browser_connect` automatically. You can also execute in Wraith CLI for manual debugging: ```text /browser status /browser connect /browser tabs /browser disconnect ``` `/browser connect` only switches `chrome-devtools` to shared mode in the current process, without modifying `~/.wraith/mcp.json`. If you want to default to shared mode after startup, you can manually change the args to: ```json ["-y", "chrome-devtools-mcp@latest", "--autoConnect"] ``` Old CDP HTTP JSON port can also be used: ```json ["-y", "chrome-devtools-mcp@latest", "--browser-url=http://127.0.0.1:9222"] ``` Browser testing can directly let the agent read dynamic pages, for example: ```text Help me see what this article https://mp.weixin.qq.com/s/RB7kF_BbsJZ5_Hmu9PxWdg says ``` When the expected path `web_fetch` fails, it falls back to `mcp__chrome-devtools__navigate_page` and `take_snapshot`. If the server supports resources, you can directly view or reference: ```text /mcp resources filesystem /mcp prompts filesystem Help me see @filesystem:file://README.md this document ``` OAuth and `sampling/createMessage` are not implemented yet; remote servers requiring authentication still use `headers` + environment variable injection Bearer token. ### 3. Compile and Run ```bash # Compile (skip test by default) mvn clean package # Run (local Ollama needs to be started and nomic-embed-text pulled) java -jar target/wraith-1.0-SNAPSHOT.jar ``` Or run directly: ```bash mvn clean compile exec:java -Dexec.mainClass="com.lyhn.wraith.cli.Main" ``` ### 4. How to Enter Plan Mode The default mode is `ReAct`. To enter `Plan-and-Execute`, use `/plan`: 1. Input `/plan` 2. The next task will be executed in plan mode 3. Execution will automatically return to default `ReAct` If you want to execute a task in plan mode and then switch back, you can directly input: ```text /plan Create a demo project, then read pom.xml, and finally verify the project structure ``` After the command is executed, it will automatically return to the default `ReAct` mode. After the plan is generated, CLI will wait for confirmation: - Press `Enter`: execute according to the current plan - Press `Ctrl+O`: expand the complete plan - Press `ESC`: fold the complete plan or cancel the plan - Press `I`: input supplementary requirements and re-plan - Pressing arrow keys will not trigger cancellation; only pressing `ESC` alone will cancel the plan to be executed ## Example Usage ### Part 1: ReAct Example ```text * Create a Java project called myapp Thought Process: The user wants to create a Java project. I will first call the create_project tool to generate the basic structure, and then confirm whether it was successful based on the tool's return result. Final Result: The Java project "myapp" has been successfully created, including a basic Maven structure. ``` ### Part 2: Plan-and-Execute Example ```text 💡 Tips: - Enter your question or task - Enter '/' and press Tab for command completion - Enter '@server:protocol://path' to explicitly reference MCP resources - Press ESC to cancel the current task while it's running - The default mode is ReAct - Unrecognized '/xxx' commands will prompt "Unknown command" and will not be processed as an ordinary conversation by the Agent * /plan Create a Java project named demoapp, then read pom.xml, and finally verify the project structure 📋 Using Plan-and-Execute mode 📋 Planning task: Create a Java project named demoapp, then read pom.xml, and finally verify the project structure ╔══════════════════════════════════════════════════════════╗ ║ Execution Plan: Create a Java project named demoapp, then read... ║ ╠══════════════════════════════════════════════════════════╣ ║ 1. ⏳ task_1 [COMMAND ] Dependencies: None ║ ║ Create demoapp project structure ║ ║ 2. ⏳ task_2 [FILE_READ ] Dependencies: task_1 ║ ║ Read demoapp/pom.xml content ║ ║ 3. ⏳ task_3 [VERIFICATION] Dependencies: task_2 ║ ║ Verify project structure and Maven configuration ║ ╚══════════════════════════════════════════════════════════╝ 📝 Plan generated. - Press Enter: Execute the plan with the current settings - Press ESC: Cancel this plan - Press I: Enter additional requirements and replan I Supplement> Please check the README before execution 📝 Additional requirements received, replanning... 🚀 Starting to execute the plan... ``` ## Available Tools - `read_file` - Read file content - `write_file` - Write file content - `list_dir` - List directory content - `glob_files` - Find files in the project by filename glob (read-only, automatically skip common build/dependency directories) - `grep_code` - Search project code by keyword or regular expression, prioritizing ripgrep, returning file, line number, optional context, partial state, and suggested reads - `execute_command` - Execute a short-term Shell command in the current project directory (default 60-second timeout, blacklist intercepts destructive commands) - `create_project` - Create project structure (Java/Python/Node) - `search_code` - Semantic search code library (natural language query, suitable as an auxiliary when fuzzy semantics or conventional search yields no results) - `web_search` - Search the internet for real-time information - `web_fetch` - Fetch a known URL and extract the Markdown body - `revert_turn` - Revert to the recent Nth pre-turn snapshot (go through HITL and audit) - `todo_write` - Maintain a real-time task list visible to users (multi-step tasks): Each time pass the complete list and replace it, each step status switch (pending→in_progress→completed) the model calls once, and the terminal prints as `Tasks N/M` + `✓/▶/○` progress blocks - `mcp__{server}__{tool}` - External tools dynamically provided by MCP server - `mcp__{server}__list_resources` / `mcp__{server}__read_resource` - Virtual tools automatically registered by MCP server supporting resources When the model returns multiple tool calls in the same round, Wraith CLI will execute them in parallel; if there are dependencies between tools, the model should call them in multiple rounds. File and code retrieval tools (`read_file` / `write_file` / `list_dir` / `glob_files` / `grep_code` / `create_project`) paths are strictly limited within the project root; out-of-bounds requests will be rejected by the policy layer; `execute_command` intercepts destructive commands through the command blacklist, such as `sudo` / `rm -rf full disk` / `mkfs` / `dd of=/dev` / fork bomb / `curl|sh`, etc. `revert_turn` will batch write back the workspace, triggering HITL and audit by default. All tools with the `mcp__` prefix trigger HITL and audit by default. See `/policy` for details. ## Commands Process-level entry: - `wraith wechat setup` - Bind WeChat iLink channel, select workspace, and complete scan confirmation - `wraith wechat start` - Start WeChat channel in the foreground - `wraith wechat status` - View binding status and daemon pid - `wraith wechat daemon start|stop|restart|status|logs` - Manage the local WeChat channel background process - `wraith --continue` - Start and continue the recent session of the current project - `wraith --resume [id]` - Continue the specified session; without id, list historical sessions of the project for selection Interactive slash commands: - `/wechat` - Scan and bind, then start WeChat iLink channel; if already bound, start directly - `/wechat setup` - Rescan and bind, then start WeChat channel - `/wechat status` - View the current Wraith CLI process's WeChat channel status - `/wechat stop` - Stop the current Wraith CLI process's WeChat channel - `/plan` - Use Plan-and-Execute mode for the next task - `/plan <task>` - Directly execute the task in Plan-and-Execute mode - `/team` - Use Multi-Agent collaboration mode for the next task - `/team <task>` - Directly execute the task in Multi-Agent collaboration mode - `/cancel` - Request to cancel the current task while running; when idle, prompt that there is no task running - `/hitl on` - Enable human approval for dangerous operations (HITL) - `/hitl off` - Disable HITL approval - `/hitl` - View the current HITL status - `/mcp` - View all MCP server statuses - `/mcp restart <name>` - Restart a single MCP server - `/mcp logs <name>` - View the recent 200 lines of stderr logs of the MCP server - `/mcp disable <name>` - Disable the MCP server at runtime and remove its tools - `/mcp enable <name>` - Enable the MCP server at runtime - `/mcp resources <name>` - View resources exposed by the MCP server - `/mcp prompts <name>` - View prompts exposed by the MCP server (view only, not injected into conversation) - `/policy` - View security policy status (path fencing / command blacklist / resource limit / audit directory) - `/audit [N]` - View recent N dangerous tool audit records (default 10) - `/snapshot` - View recent Side-Git snapshots - `/snapshot status` - View Side-Git snapshot status - `/snapshot clean` - Clean up the Side-Git snapshot directory of the current project - `/restore <N>` - Revert to the recent Nth pre-turn snapshot - `/memory` / `/mem` - View memory system status - `/memory list` - View long-term memory list - `/memory search <keyword>` - Search visible long-term memory in the current project - `/memory delete <id>` - Delete a single long-term memory - `/memory clear` - Clear long-term memory - `/save <fact>` - Manually save key project-level facts to long-term memory; `/save --global <fact>` saves cross-project general preferences - `save_memory` - Built-in Agent tool, only called when users explicitly request to save long-term preferences or stable facts; default `scope=project`, cross-project general preferences use `scope=global` - `/init` - Generate a concise project-level memory `WRAITH.md`; if it exists, do not overwrite, `/init --force` can rewrite - `/export` - Export the current ReAct conversation record as Markdown (including complete system prompt), write to `~/.wraith/exports/session-*.md` - `/index [path]` - Index code library (default current directory) - `/search <query>` - Semantic search code (RAG-assisted path) - `/graph <class name>` - View code relationship graph - `/clear` - Clear current conversation history, short-term memory, Skill context to be injected, and last-round retrieval memory injection; long-term memory is retained (and open a new session file) - `/resume` - Continue the historical session of the project (弹 panel selection); `/resume <id>` directly continue the specified session - `/exit` / `/quit` - Exit the program ## Operating Effect ### Part 3: Current Operating Effect ```text ██╗ ██╗██████╗ █████╗ ██╗████████╗██╗ ██╗ ██║ ██║██╔══██╗██╔══██╗██║╚══██╔══╝██║ ██║ ██║ █╗ ██║██████╔╝███████║██║ ██║ ███████║ ██║███╗██║██╔══██╗██╔══██║██║ ██║ ██╔══██║ ╚███╔███╔╝██║ ██║██║ ██║██║ ██║ ██║ ██║ ╚══╝╚══╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═╝ ╚═╝ ╚═╝ Wraith CLI v16.1.0 Model glm-5.1 (glm) MCP 4/4 · 61 tools · 2/2 skills · ReAct ReAct · Plan · MCP · Browser · Image · Tools · Memory · RAG Tips for getting started: 1. Type / for commands and Tab completion 2. Ask coding questions, edit code or run commands 3. Attach context with @path or @image: * Hello, please list the files in the current directory Thought Process: The user wants to understand the current directory structure. I will first read the directory and then provide a classified description based on the results, rather than just returning the raw file list. Final Result: The current directory contains `src`, `target`, `pom.xml`, `README.md`, etc., which is a standard Java Maven project. * /exit Goodbye! ``` ## Technical Stack - Java 17 - Maven - Multiple LLM Providers (GLM / DeepSeek / StepFun / Kimi / FreeLLMAPI / 讯飞星辰, all compatible with OpenAI) - OkHttp - Jackson - JLine 4 (terminal interaction, status, input widgets) - SQLite (vector and graph persistence) - JavaParser (AST analysis) - Ollama (local Embedding) - Feishu Open Platform Java SDK (`com.larksuite.oapi:oapi-sdk`, IM gateway Feishu long connection + card callback) - Electron + React + TypeScript (desktop app, independent sub-project `desktop/`) ``` src/main/java/com/lyhn/wraith ├── agent/ │ ├── Agent.java # ReAct Agent │ ├── PlanExecuteAgent.java # Plan-and-Execute Agent │ ├── AgentRole.java # Agent Role Enumeration │ ├── AgentMessage.java # Agent Communication Message │ ├── SubAgent.java # Configurable Sub-Agent │ └── AgentOrchestrator.java # Multi-Agent Orchestrator ├── cli/ │ ├── Main.java # CLI Entry │ ├── CliCommandParser.java # Command Parser │ └── PlanReviewInputParser.java # Plan Review Input Parser ├── llm/ │ ├── LlmClient.java # Provider (Capability Declaration: window / prompt cache) │ ├── AbstractOpenAiCompatibleClient.java # OpenAI Compatible Template Base Class (Authorization: Bearer) │ ├── LlmClientFactory.java # Provider Name → Specific Client Factory │ ├── GLMClient.java # GLM; glm-5.1 uses Coding endpoint, glm-5v-turbo uses Multi-Modal endpoint │ ├── DeepSeekClient.java # DeepSeek V4 Client │ ├── StepClient.java # StepFun Client │ ├── KimiClient.java # Kimi / Moonshot Client │ ├── FreeLlmApiClient.java # General OpenAI Compatible Gateway Client (Custom Model Access Entrance) │ └── XfyunMaaSClient.java # Xfyun MaaS Client ├── context/ │ ├── ContextMode.java # Short / Balanced / Long Mode │ ├── ContextProfile.java # Model Window and Context Strategy │ └── TokenUsageFormatter.java # Token / Cache / Cost Display ├── memory/ │ ├── MemoryEntry.java # Memory Entry │ ├── ConversationMemory.java # Short-Term Memory │ ├── LongTermMemory.java # Long-Term Memory │ ├── ContextCompressor.java # Context Compression │ ├── TokenBudget.java # Token Budget Management │ ├── MemoryRetriever.java # Memory Retrieval │ └── MemoryManager # Memory Facade Class ├── plan/ │ ├── Task.java Task Definition │ ├── ExecutionPlan.java # Execution Plan │ └── Planner.java # Planner ├── rag/ │ ├── EmbeddingClient.java # Embedding API Client │ ├── VectorStore.java # SQLite Vector Storage │ ├── CodeChunk.java # Code Chunk Model │ ├── CodeChunker.java # Code Chunker │ ├── CodeAnalyzer.java # AST Relationship Analysis │ ├── CodeRelation.java # Code Relationship Model │ ├── CodeIndex.java # Index Manager │ └── CodeRetriever.java # Retrieval Entrance ├── tool/ │ └── ToolRegistry.java # Tool Registry (11 Built-in Tools) ├── config/ # WraithConfig: provider / api key / model / base_url (Read/Write ~/.wraith/config.json) ├── mcp/ # MCP Client: stdio + Streamable HTTP, resources, step_search, @mention expansion ├── web/ # web_search (Zhihu/SerpAPI/SearXNG), web_fetch (Jsoup readability), Network Security Policy ├── browser/ # Chrome DevTools MCP Session, CDP Reuse, Sensitive Page Policy, /browser commands ├── skill/ # Skill System: SKILL.md loading, load_skill, built-in web-access ├── hitl/ # Human-in-the Approval Flow (Renderer / Terminal handlers) ├── policy/ # Path Fencing, CommandGuard Command Blacklist, AuditLog Audit ├── prompt/ # PromptAssembler Hierarchical Prompt Assembly (resources/prompts/ + User/Project-level coverage) ├── lsp/ # LSP Diagnostic Injection (Java Diagnosis) ├── snapshot # Side-Git Snapshot and Rollback (JGit) ├── runtime/ # Asynchronous Background Tasks (SQLite Queue) + Runtime HTTP API / # Image Input: Compress / Scale, @ parsing ├── wechat/ Chat iLink Channel (Text MVP) ├── gateway/ # daemon: ImProvider SPI/) + QQ (qq/)ishu (feishu/) + openclaw binding (bind/) + / Driver / Authentication ├── automation/ # Scheduled Task Scheduling (Scheduler: interval/daily/weekly Deliverer / DeliveryAdapterdelivery/: desktop / QQ /) ├── render/ # Renderer Interface + Inline Streaming / Plain Diff, Bottom Status Bar ui/ # Lan-Screen TUI,ing, Conversation History Snapshot util/ # An, Markdown Rendering, and other Public Tools ``` > Desktop App (Electron + React + TypeScript) in independent sub-engine `desktop/`: (Session / Plan / IM Gateway / Automation Panel), preload `window.wraith` bridge, main process (Java app-server sidecar + gateway process management), reused via JSON-RPC with the same