DotCraft

• ⚡ 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:

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.gz

Option 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.ps1

First launch:

cd my-project
dotcraft

On 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.

• dotcraft starts the CLI.
• dotcraft app-server [--listen ...] starts AppServer.
• dotcraft gateway starts the Gateway host.

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:

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

CLI	TUI
Desktop	ACP

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.

Start it explicitly with dotcraft app-server.

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.

Telegram (Python SDK)	QQ / WeCom	WeChat (TypeScript SDK)

DotCraft Automations uses a shared AutomationOrchestrator to run automation tasks across multiple sources, currently Local and GitHub. Automations.Enabled defaults to true, while GitHubTracker.Enabled stays false until you opt in. Bare dotcraft still starts the CLI; use dotcraft gateway when you want a dedicated host process for concurrent channels and automations. See the Automations Guide.

Desktop Automations	GitHub tracker
View automated tasks using the desktop application.	PR Automatic Review.

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.

Usage overview	Session trace
Usage and session statistics, aggregated by channel.	Complete record of tool calls and session history.

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, startup modes, 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-wire and 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