dscode

The open source spec-driven MCP-first AI agent for DeepSeek — built for digital creation, not just coding.

_中文文档

Terminal or browser — one agent harness. MCP-native tooling, agentic workflows, purpose-built for DeepSeek.
From context management to memory systems to permission control — everything you need in one tool.

npm · Philosophy · Architecture · Roadmap

Why dscode

Spec-driven development

dscode is built entirely through spec coding — every feature is first defined as a formal spec in OpenSpec, then implemented by AI agents. AGENTS.md + openspec/specs/ serve as the complete project blueprint.

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

Digital work, not just coding

dscode connects external tools through MCP (Model Context Protocol), extending DeepSeek's capabilities to broader digital workflows — from Blender 3D modeling to browser automation, from document and spreadsheet processing to design and content production.

The screenshots above demonstrate controlling Blender via blender-mcp, manipulating a 3D scene with natural language. Creative toolchains like this are just one example of digital work — dscode uses the standard MCP protocol to let DeepSeek models access a much broader ecosystem of digital tools.

Install in 30 seconds

# Node.js >= 20
npm install -g @wangcan26/dscode
dscode --version
dscode

npm install
npm run build
node dist/dscode.mjs

If you like this project, give it a ⭐ Star, 👀 Watch, and 👍 on GitHub! Your support keeps dscode evolving, and every piece of feedback is deeply appreciated.

First launch

/config key sk-your-deepseek-api-key
/config model deepseek-v4-pro

Configuration written by the /config command is persisted to ~/.dscode/config.json — no need to repeat setup on subsequent launches. The cwd field records the project directory associated with the current session; it is only reused when you manually run /config cwd <path>. Declarative settings go in settings.json: user-level at ~/.dscode/settings.json, project-level at <project>/.dscode/settings.json.

Web UI

In addition to terminal interaction, dscode also offers a clean, modern browser interface with full feature parity with the TUI.

Global npm install:

dscode --web                  # Default port 3000
dscode --web --web-port 8080  # Custom port

Build from source:

npm run build:web             # Build frontend first
node dist/dscode.mjs --web    # Start web mode

Open http://localhost:3000 in your browser:

Web UI features:

Web UI and CLI share the same Agent backend — all features are fully consistent. No reconfiguration needed when switching modes.

What you get

MCP connector

MCP configuration example

Place MCP config in ~/.dscode/settings.json or <project>/.dscode/settings.json, not in the /config-managed config.json.

{
  "mcpServers": {
    "blender": {
      "description": "Blender 3D modeling via MCP",
      "command": "uvx",
      "args": ["blender-mcp"]
    },
    "playwright": {
      "description": "Browser automation",
      "command": "npx",
      "args": ["@anthropic/mcp-playwright"]
    },
    "custom-api": {
      "description": "Remote API server",
      "url": "http://localhost:3000/mcp"
    }
  }
}

MCP tools are registered as Drivers with naming format mcp_<server>_<tool>, e.g. mcp_blender_get_scene_info. Connection failures don't block startup; error messages are output to the console.

Type /mcp in the TUI to open the interactive browser: select an MCP server, then view its tool list, load status, transport, protocol version, compatibility mode, and refresh status.

Model configuration

Manage configuration in the TUI with /config — no file editing or environment variables needed:

/config                     # View current config
/config model <id>          # Switch model (immediate)
/config thinking <level>    # Set thinking intensity
/config key <api-key>       # Set API Key
/config cwd <path>          # Set working directory for current project (restart to apply)
/config help                # Show help

Defaults to deepseek-v4-flash. Recommended to switch to deepseek-v4-pro for stronger reasoning/thinking:

DeepSeek V4 series all support a 1 million token context window with a maximum output of 384K tokens.

Under the hood is pi-ai, extensible to 25+ providers including OpenAI, Anthropic, Google, and more.

Thinking levels

DeepSeek reasoning models control thinking intensity via thinkingLevel. The default is automatically set when switching models (pro → medium, others → off), and can be manually overridden:

/config thinking xhigh

Skills system

dscode uses an Agent as OS architecture: Drivers (kernel modules, always loaded) and Skills (user-mode programs, activated on demand).

~/.dscode/skills/
├── git-workflow/
│   └── SKILL.md
└── docker/
    └── SKILL.md

SKILL.md format:

---
name: git-workflow
description: Advanced git operations for PR workflows
tools:
  - read_file
  - list_files
  - grep
  - bash
---
## Instructions
When the user asks about git workflows, use these tools.
Always push the branch before creating a PR.

• YAML frontmatter declares name, description, tools whitelist
• When activated, instructions are injected into the system prompt; tools are filtered from loaded Drivers by the whitelist
• All scanned Skills are auto-activated at startup; manual activation via /skills activate <name> is also supported

CLI commands

Exit: type exit or press Ctrl+C twice. Interrupt generation: single Ctrl+C. In Web UI, commands correspond to sidebar and button actions.

Configuration reference

We recommend separating configuration into two categories:

• User command config written by /config: ~/.dscode/config.json (includes cwd record for current project)
• Declarative settings:
  • User-level: ~/.dscode/settings.json
  • Project-level: <project>/.dscode/settings.json

Project-level configuration always uses <project>/.dscode/settings.json.

/config command config

{
  "modelId": "deepseek-v4-flash",
  "thinkingLevel": "high",
  "cwd": "/absolute/path/to/project/subdir",
  "cwdProjectPath": "/absolute/path/to/project"
}

settings.json

{
  "skills": ["git-workflow"],
  "permissions": {
    "deny": ["**/.env", "**/.env.*", "**/secrets/**"]
  },
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@anthropic/mcp-playwright"]
    }
  }
}

Environment variables

Examples

examples/ provides runnable sample projects demonstrating dscode's MCP integration and interactive UI capabilities.

MCP App

The screenshot above shows scenario-modeler rendering an MCP App HTML inline in the Web UI — click "Open App ▼" to expand an interactive SaaS financial modeling dashboard.

More usage instructions in:

• examples/scenario-modeler/README.md

Project structure

src/
├── core/           # Entry, host assembly, config, shared types
├── session/        # Session persistence
├── context/        # Token estimation, context compression
├── memory/         # Cross-session memory
├── drivers/        # Driver registry + built-in drivers (fs, shell, search)
├── skills/         # Skill manager + SKILL.md loader
├── mcp/            # MCP client (stdio / streamable-http / legacy SSE) + manager + MCP App host/runtime
├── permissions/    # Permission interception
└── ui/             # TUI (terminal), Web UI (browser), streaming renderer, slash commands

Permission model

When confirming, you can choose: Y (allow this time), N (deny), A (always allow this tool for the current session).

Configure permissions.deny with glob patterns to block reading/writing sensitive files. User-level and project-level deny lists are merged.

Development

npm start
npm run typecheck
npm test

Web UI development:

# Install frontend dependencies
cd web && npm install && cd ..

# Build frontend + start web mode
npm run build:web
dscode --web

# Development mode (frontend HMR + backend hot reload)
npm run dev:web

Tech stack: TypeScript + tsx · React + Vite + Tailwind CSS (Web UI) · pi-agent-core · pi-ai · DeepSeek API

Contributions welcome! Please read CONTRIBUTING.md for philosophy alignment and PR process.

Known limitations

• The summarize-prefix context compression strategy currently falls back to sliding-window
• Automatic memory extraction is off by default; use /memory add manually
• Image input is OCR-based, text extraction only — no visual understanding
• If there's no output on first launch, it's usually an invalid API Key or network issue

More docs

• Architecture docs
• Roadmap

License

MIT