中文 | English
Craft around your project.
An Agent Harness crafting a persistent AI workspace around your project.
From Desktop, CLI, editors, chatbots, APIs — everywhere you work.
| 📁 Project-First Sessions, memory, skills, and config live under .craft/ and follow the project |
⚡ Unified Session Core Desktop, CLI, editors and bots share one session model |
🛡️ Observable Built-in approvals, traces, Dashboard, and optional sandbox isolation |
- ⚡ Unified Session Core: unified execution path across all channels
- 💻 Rich Client Matrix: C# CLI, Rust TUI, Electron Desktop — full coverage from terminal to desktop
- 🛠️ Modern Agent Infrastructure: File, Shell, Web, SubAgent tools with full MCP, Skills, Hooks, and slash commands support
- 🖥️ ACP Editor Integration: native integration with Unity, JetBrains IDEs, and Obsidian
- 🔗 Server Capabilities: OpenAI-compatible API and AG-UI protocol to use DotCraft as an Agent backend
- 🌐 Extensible Channel Integration: Python and TypeScript SDKs for quick integration with Telegram, WeChat, Discord, and other social platforms
- 👥 Automation Pipeline: support for local tasks and GitHub issue/PR orchestration
- ⚗️ Context-Friendly: auto-compaction, memory consolidation, deferred MCP tool loading for efficient long sessions
Prerequisites:
- A supported LLM API key (OpenAI-compatible format)
Option 1 — Download from Releases (no build required):
Download the latest pre-built binary from GitHub Releases:
| Platform | Archive |
|---|---|
| Windows | DotCraft-win-x64.zip |
| Linux | DotCraft-linux-x64.tar.gz |
| macOS | DotCraft-macos-x64.tar.gz |
Extract the archive and optionally add the directory to your PATH:
# Windows — extract DotCraft-win-x64.zip, then (optional) add to PATH
powershell -File install_to_path.ps1
# Linux / macOS — extract and (optional) move to a directory on $PATH
tar -xzf DotCraft-linux-x64.tar.gz # or DotCraft-macos-x64.tar.gzOption 2 — Build from Source:
Requires .NET 10 SDK.
# Windows
build.bat
# Linux / macOS
bash build_linux.bat
# Add to PATH (optional, Windows)
cd Release/DotCraft
powershell -File install_to_path.ps1First launch:
cd my-project
dotcraftOn the first run, DotCraft initializes .craft/ for the workspace. If no ApiKey is configured, it opens a local Dashboard to guide setup. After saving, run dotcraft again to enter the CLI.
Example session:
You > Summarize the recent changes in this repo
DotCraft is thinking...
I've reviewed the recent git history. Here is a summary of the
changes in the last week: ...
For manual editing or the full configuration reference, see the Configuration Guide.
For first-time setup, use the built-in Dashboard for visual configuration. Later, you can continue using the Dashboard Settings page for workspace adjustments.
For the full configuration reference, config layering details, or manual editing, see the Configuration Guide.
All entry points share one execution engine — the Unified Session Core. Here is how that differs from a traditional gateway-style architecture:
| Dimension | Gateway-style (nanobot / OpenClaw) | DotCraft |
|---|---|---|
| Session model | Flattened MessageBus (InboundMessage / OutboundMessage) |
Unified Session Core |
| Channel integration | Gateway routes events to a generic message bus | Each adapter is a full bidirectional Wire Protocol client |
| Platform-native UX | Lost after flattening into bus messages | Preserved — each adapter owns its own platform rendering |
| Approval / HITL | Cannot express platform-native approval flows | Bidirectional: server issues approval requests, adapter renders native UX (Telegram inline keyboard, QQ reply, etc.) |
| Cross-channel resume | Not supported | Server-managed threads resumable across channels |
| Workspace persistence | Not defined at framework level | .craft/ — sessions, memory, skills, and config scoped to the project |
flowchart LR
Cli["CLI"]
Tui["TUI"]
Desktop["Desktop"]
AppSrv["AppServer"]
Ide["ACP / IDE"]
Bots["QQ / WeCom / ..."]
ExtCh["External Channels (Telegram, WeChat, ...)"]
Api["API / AG-UI"]
Automations["Automations"]
LocalSource["Local Source"]
GitHubSource["GitHub Source"]
subgraph Workspace [".craft/"]
Core["Unified Session Core"]
end
Dashboard["Dashboard"]
Cli --> AppSrv
Tui --> AppSrv
Desktop --> AppSrv
Ide --> AppSrv
AppSrv --> Workspace
AppSrv --> Automations
Automations --> LocalSource
Automations --> GitHubSource
Bots --> Workspace
ExtCh -->|"SDK / JSON-RPC"| AppSrv
Api --> Workspace
Workspace --> Dashboard
style Core fill:#0969da,color:#ffffff,stroke:#0550ae
style Workspace fill:#ddf4ff,stroke:#54aeff,color:#0550ae
style Dashboard fill:#e5a50a,color:#ffffff,stroke:#bf8700
style Cli fill:#57606a,color:#ffffff,stroke:#424a53
style Tui fill:#57606a,color:#ffffff,stroke:#424a53
style Desktop fill:#57606a,color:#ffffff,stroke:#424a53
style AppSrv fill:#57606a,color:#ffffff,stroke:#424a53
style Ide fill:#57606a,color:#ffffff,stroke:#424a53
style Bots fill:#57606a,color:#ffffff,stroke:#424a53
style ExtCh fill:#57606a,color:#ffffff,stroke:#424a53
style Api fill:#57606a,color:#ffffff,stroke:#424a53
style Automations fill:#8250df,color:#ffffff,stroke:#6639ba
style LocalSource fill:#f6f8fa,color:#57606a,stroke:#d0d7de
style GitHubSource fill:#f6f8fa,color:#57606a,stroke:#d0d7de
| If you want to... | Start here |
|---|---|
| Work in a local terminal | CLI |
| Use a rich terminal UI | TUI |
| Run DotCraft as a headless server | AppServer |
| Use a graphical desktop client | Desktop |
| Use DotCraft in an editor or IDE | Editors and ACP |
| Expose DotCraft as a service | API / AG-UI |
| Connect a chat bot | QQ / WeCom |
| Build a custom channel adapter | External Channels |
| Run automations (Local / GitHub) | Automations |
CLI mode is the default starting point for working directly in a project directory.
TUI is a terminal interface built on Ratatui, connecting to AppServer over Wire Protocol.
AppServer exposes DotCraft's Agent capabilities as a wire protocol (JSON-RPC) server over stdio or WebSocket, enabling remote CLI connections, multi-client access, and custom integrations in any language. See the AppServer Guide.
DotCraft Desktop is an Electron + React application that acts as a graphical client for AppServer. Over the Wire Protocol it consumes server-side session, approval, plan, cron, and automation capabilities, providing a three-panel workspace with multi-session management, real-time streaming conversation, and inline diff review with one-click revert.
See the Desktop Client README for details.
DotCraft supports ACP-compatible editors including Unity, Obsidian, and JetBrains IDEs. The ACP client acts as a protocol bridge between the editor (ACP/JSON-RPC over stdio) and an AppServer instance (wire protocol), so all session state, agent execution, and tool invocation are handled by AppServer — just like CLI, TUI, and Desktop clients. The bridge can spawn a local AppServer subprocess automatically, or connect to an already-running remote AppServer via --remote ws://host:port/ws.
Start with the ACP Mode Guide; for Unity specifically, see the Unity Integration Guide and the Unity Client README.
Expose DotCraft as a service or connect it to frontend experiences. See the API Mode Guide and AG-UI Mode Guide.
Connect the same workspace to chat bot entry points. See the QQ Bot Guide and WeCom Guide.
DotCraft can also integrate with external channels over the AppServer wire protocol, so you can connect platforms such as Telegram, Discord, Slack, or your own internal chat system without embedding the adapter into the main process.
The Python and TypeScript SDKs (DotCraftClient, ChannelAdapter) make it easier to wire up external channels. Adapters can show approval flows with each platform's native UI, so integration stays flexible.
The repository includes two reference adapters:
-
Telegram (Python SDK): long polling, inline-keyboard approvals, and full end-to-end integration. See the Python SDK.
-
WeChat (TypeScript SDK): WebSocket transport, QR-code login, text-keyword approvals. See the TypeScript SDK.
DotCraft Automations uses a shared AutomationOrchestrator to run automation tasks across multiple sources, currently Local and GitHub. Enabling the Automations module runs local tasks; enabling GitHubTracker additionally contributes GitHubAutomationSource, so GitHub issues and pull requests are polled, dispatched, and reviewed through the same AppServer-hosted pipeline and appear alongside local tasks in the Desktop Automations panel. See the Automations Guide.
DotCraft includes a built-in Dashboard for inspecting sessions, traces, and configuration. When ApiKey is missing, it can also run in setup-only mode as the initial configuration entry point. See the Dashboard Guide for details.
If you want Shell and File tools to run in an isolated environment, DotCraft supports OpenSandbox. Installation, configuration, and security details are covered in the Configuration Guide.
When many MCP servers are connected, injecting all tool definitions upfront adds significant token overhead and can reduce tool selection accuracy. Deferred Loading keeps MCP tools out of the initial context — the Agent discovers and activates them on demand via SearchTools. Once activated, tools are available immediately and the tool list grows monotonically within a session to keep the prompt cache stable.
For configuration details and the recommended Skill-based guidance pattern, see the Configuration Guide.
You can customize agent behavior through files such as .craft/AGENTS.md, .craft/USER.md, .craft/SOUL.md, .craft/TOOLS.md, and .craft/IDENTITY.md, and add custom slash commands under .craft/commands/. Detailed usage belongs in the dedicated docs and examples.
Setup and operations
- Configuration Guide: configuration, tools, security, approvals, MCP, sandbox, Gateway
- Dashboard Guide: Dashboard pages, debugging, and visual configuration
- Automations Guide: local tasks and GitHub issue/PR orchestration, agent dispatch, and human review flow
Entry points
- AppServer Guide: wire protocol server, WebSocket transport, remote CLI
- Desktop Client Guide: Electron desktop application, build, launch, and feature overview
- API Mode Guide: OpenAI-compatible API, tool filtering, SDK examples
- AG-UI Mode Guide: AG-UI SSE server and CopilotKit integration
- QQ Bot Guide: NapCat, permissions, and approvals
- WeCom Guide: WeCom push notifications and bot mode
- ACP Mode Guide: editor/IDE integration (JetBrains, Obsidian, and more)
- External Channel Adapter Spec: wire protocol contract for out-of-process channel adapters
- Python SDK: build external adapters with
dotcraft-wireand the Telegram reference example - TypeScript SDK: build external adapters with
dotcraft-wire(TypeScript) and the WeChat reference example
Editor integrations and extension points
- Unity Integration Guide: Unity Editor extension and AI-powered scene and asset tools
- Hooks Guide: lifecycle hooks, shell extensions, and security guards
- Documentation Index: full documentation navigation
TUI
- Rust TUI Guide: build, launch modes, key bindings, slash commands, and theme configuration
We welcome contributions! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.
Getting Started: See CONTRIBUTING.md for development guidelines.
You can contribute with or without AI assistance - the guidelines support both approaches.
Inspired by nanobot and Codex, and built on the Microsoft Agent Framework.
Thanks to Devin AI for providing free ACU credits to facilitate development.
- HKUDS/nanobot
- openai/codex
- microsoft/agent-framework
- alibaba/OpenSandbox
- modelcontextprotocol/csharp-sdk
- agentclientprotocol/agent-client-protocol
- ag-ui-protocol/ag-ui
- openai/symphony
Apache License 2.0