Dscode

See it in action

dscode's editorial workshop — a creative space for code, design, and conversation.

What makes dscode different

🧠 Agent as OS

dscode is designed as an operating system for Agents: the Harness is the Kernel, the Main Agent is PID 1, SubAgents are processes, Agent.md files are Applications, Sessions are TTYs, Drivers are device interfaces, and MCP servers are external devices. This keeps execution generic and composable — new Agent capabilities come from configuration, not specialized runtimes.

Applications are configured. Agents are processes. Sessions are TTYs.

The CLI is assembled on the same reusable headless Agent Host used by internal tests. TUI/Web and process signal handling remain CLI adapters. This is an internal architecture boundary, not a published SDK or public npm API.

Source ownership follows the same boundary: src/application/ coordinates use cases, Agent authoring lives in src/agents/definitions/, Slash Commands and project files have dedicated feature roots, and TUI/Web live under src/ui/tui/ and src/ui/web/. Skills and MCP remain independent sibling owners despite appearing together in the UI.

🔌 MCP-First

Digital studios don't use one tool. They use ten. MCP turns every tool into an API — dscode is the Agent system that orchestrates them. Blender for 3D modeling, PlayCanvas for real-time graphics, browser automation for testing, documents for specs, spreadsheets for data. If your production tool has an MCP server, dscode brings it into the workflow.

Your toolchain. Coordinated Agents. All through MCP.

🧬 Spec-Driven Development

dscode is built entirely through spec coding with OpenSpec. Every feature begins as a formal spec — openspec/specs/ is the source of truth, code is the implementation. We don't encourage manual commits; all design and development flows through the SDD pipeline.

Code is the implementation of specs — not the other way around.

🔍 MCP Tool Search

Too many MCP servers? Context explosion is a real problem when every tool schema competes for token budget. dscode ships with a built-in search_tools driver — MCP tools are discovered on-demand by the model, not pre-loaded. Only the tools actually needed enter the context window. Connect dozens of MCP servers without worrying about overhead.

All the tools. None of the bloat.

🎨 Editorial Workshop

dscode is not a chatbot with a dark theme. It's a digital studio — a creative workspace with editorial typography, generous whitespace, and a warm, tool-like aesthetic. The interface is designed for makers: phase-labeled message groups, serif structural labels, sidebar detail panels, and a Dashboard that's a mode of Chat, not a separate page. Every pixel earns its place.

A creative space. Not just a chat window.

Capabilities

Tip: In TUI, paste clipboard images with Ctrl+V (macOS) or /image clipboard.

Agent as OS

The Main Agent runs as PID 1 and delegates work to independent SubAgent processes. Applications use Claude Code-compatible Agent.md files; dscode automatically discovers user and project definitions from .claude/agents alongside native .dscode/agents directories. Terminal and Web conversations show foreground and background process activity with persisted results.

The bundled vision.md uses the same SubAgent runtime and falls back to Tesseract OCR when needed. See Agent.md configuration and usage for supported fields, discovery priority, and process tools, or read the full Agent as OS architecture.

MCP in 30 seconds

// ~/.mcp.json
{
  "mcpServers": {
    "blender": {
      "command": "uvx",
      "args": ["blender-mcp"]
    },
    "playwright": {
      "command": "npx",
      "args": ["@anthropic/mcp-playwright"]
    }
  }
}

dscode auto-connects on launch. Tools appear as mcp__blender__* and mcp__playwright__*. Agent.md Applications can allow an exact connected tool, such as tools: [mcp__github__search_repos]; MCP Server definitions remain in .mcp.json. MCP servers can also serve sandboxed UI via the App Host — no boilerplate, no SDK, no glue code.

See what MCP can do

Tip: Videos play inline — these are real MCP workflows, click to watch.

Install

npm install -g @creative-dswork/dscode
dscode              # Terminal UI
dscode --web        # Web UI → http://localhost:3000

First launch? Run /config key <your-api-key> and /config model deepseek-v4-pro to get started. Type /help for the full guide.

Build from source:

git clone https://github.com/creativedswork/dscode.git
cd dscode && npm install && npm run build
node dist/dscode.mjs

Configuration

dscode uses two levels of settings.json, merged with project settings overriding user settings:

Note: Model configuration (provider, modelId, apiKey, thinkingLevel) lives in ~/.dscode/config.json, managed via /config commands. Type /help in-session for the full command list.

Quick reference

// ~/.dscode/settings.json
{
  // --- External Integrations ---
  "integrations": {
    "openDesign": {
      "enabled": true,
      "path": "/path/to/open-design",
      "port": 7456,
      "autoStart": true
    }
  },

  // --- Permissions ---
  "permissions": {
    "allow": [
      "Bash(git add *)",
      "Bash(npm *)"
    ],
    "deny": [
      "Bash(rm -rf *)"
    ],
    "rules": [
      { "tool": "Bash(curl *)", "decision": "allow", "priority": 5 }
    ]
  },

  // --- Skills ---
  "skills": ["brandkit", "minimalist-ui"],

  // --- Agent Applications ---
  "agents": { "enabled": true },
  "agentModelAliases": {
    "haiku": "deepseek/deepseek-v4-flash",
    "sonnet": "deepseek/deepseek-v4-pro"
  },

  // --- Retry ---
  // Controls how dscode retries failed API calls (rate limits, timeouts, server errors).
  // Uses exponential backoff: starts at baseDelayMs, doubles each retry, capped at maxDelayMs.
  "retry": {
    "maxRetries": 3,           // Max retry attempts before giving up
    "baseDelayMs": 1000,       // Initial delay before first retry (ms)
    "maxDelayMs": 30000,       // Upper bound on backoff delay (ms)
    "retryOnTimeout": true,    // Retry when the provider times out
    "retryOnRateLimit": true,  // Retry when hitting rate limits (respects Retry-After header)
    "retryOnServerError": true // Retry on 5xx server errors
  },

  // --- @-file limits ---
  "atFileMaxFiles": 5,
  "atFileMaxFileSize": 51200,
  "atFileMaxTotalSize": 204800
}

MCP server config

MCP servers use user-level ~/.mcp.json or project-level .mcp.json, not the Open Design integration object in settings.json:

{
  "mcpServers": {
    "blender": {
      "command": "uvx",
      "args": ["blender-mcp"],
      "env": { "BLENDER_HOST": "127.0.0.1" }
    },
    "my-api": {
      "url": "https://my-mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Each server under mcpServers supports:

Tip: Transport is auto-detected — if url is set without command, streamable-http is used. Otherwise stdio.

Environment variables

Some runtime settings have dedicated environment-variable overrides for CI and containers. settings.json does not have a generic env field:

Open Design

dscode integrates Open Design — a visual design workspace that brings AI-driven frontend generation directly into your workflow. Think of it as Figma meets AI: design tokens, components, and entire layouts generated through natural language, with real-time preview and iteration.

What Open Design does for dscode

• Visual design workspace — create, edit, and iterate on frontend designs without leaving dscode
• Image-to-code — generate production-ready HTML/CSS from design mockups
• Design system management — maintain consistent design tokens, typography scales, and color palettes across projects
• Multi-file artifact generation — produce complete frontend projects with structured file trees

Installation

git clone https://github.com/wangcan26/open-design.git
cd open-design
npm install

Recommended configuration: settings.json

Enable the integration in user-level ~/.dscode/settings.json or project-level .dscode/settings.json:

{
  "integrations": {
    "openDesign": {
      "enabled": true,
      "path": "/path/to/open-design",
      "port": 7456,
      "autoStart": true
    }
  }
}

Open Design uses the typed path and port fields above. Do not place OPEN_DESIGN_DIR or OD_PORT in an env object in settings.json; mcpServers.<name>.env belongs to .mcp.json and only configures that MCP child process.

Project fields override matching user fields. Set autoStart: false when the daemon is managed externally. In that mode, dscode contributes the MCP proxy but does not start or stop the daemon.

Compatibility configuration: .env

Existing .env setups remain supported:

cp .env.example .env

OPEN_DESIGN_DIR=~/Workspace/DeepSeekSpace/open-design
OD_PORT=7456

Start dscode with the one-run compatibility flag:

dscode --with-od
# Development checkout:
node ./dist/dscode.mjs --with-od

The compatibility values provide path and port; --with-od enables the integration and requests auto-start for that invocation. The direct CLI reads only OPEN_DESIGN_DIR and OD_PORT from the project .env. It does not import unrelated variables or write configuration back to disk.

Configuration precedence is:

1. integrations.openDesign in user/project settings.json
2. OPEN_DESIGN_DIR and OD_PORT already present in the process environment
3. OPEN_DESIGN_DIR and OD_PORT in the project .env
4. Disabled defaults with port 7456

If either settings scope contains an integrations.openDesign object, legacy environment values are ignored, including when typed configuration explicitly sets enabled: false.

Runtime behavior

When auto-start is active, dscode:

1. Probes http://127.0.0.1:<port>/api/projects.
2. Reuses a healthy externally managed daemon without claiming ownership.
3. Otherwise starts od --port <port> --no-open through ServiceSupervisor.
4. Derives the open-design MCP server in memory without modifying ~/.mcp.json or project configuration.
5. Captures daemon output in ~/.dscode/logs/dscode.log, applies bounded restart protection, and stops only the daemon process owned by dscode.

For troubleshooting, confirm that <integrations.openDesign.path>/apps/daemon/src/cli.ts exists, inspect ~/.dscode/logs/dscode.log, and check readiness with:

curl http://127.0.0.1:7456/api/projects

Contributing

dscode is currently a single-developer SDD project and does not accept direct code contributions (Pull Requests).

We welcome bug reports, feature ideas, and technical discussions via GitHub Issues. See CONTRIBUTING.md for the full policy.

| CONTRIBUTING.md | Contribution policy & how the SDD workflow operates |

Learn more

Acknowledgments

dscode stands on the shoulders of:

• OpenSpec — the spec-driven development framework that shapes our entire workflow

• @earendil-works/pi-ai / pi-agent-core — agent loop and model abstraction foundation

• taste-skill — Leonxlnx's design taste skill system, inspired our skills architecture

• @_can1357 — hash-anchor editing protocol, the cornerstone of our edit tool