deepseek-code

---

---

Features

• Agentic coding — reads/writes files, runs shell commands, searches code, manages git
• Multi-provider — DeepSeek API, Amazon Bedrock, Google Vertex AI, or any local model (Ollama, LM Studio)
• Full TUI — alternate-screen interface with streamed thinking, rich markdown, and vim mode
• Session command center — press Left on an empty prompt to search, switch, rename or delete saved sessions across projects
• Unified agents — scoped primary agents and sub-agents with editable base prompts
• DeepSeek Pods — persistent agents that keep scheduled and queued work running under a host supervisor
• Settings center — fullscreen, searchable User/Project/Local configuration with visible origins
• MCP support — connect to any Model Context Protocol server for extended tooling
• Project guidance — loads a root AGENTS.md alongside DEEPSEEK.md
• Optional code navigation — session-owned language servers expose definitions, references, hover, symbols, one-document diagnostics and rename previews with source/version provenance; rename proposals apply separately through hash-checked edit_file ranges. lsp with operation: "dependency_graph" queries bounded local TS/JS imports and package.json workspace declarations without a server
• Extensible — slash commands, custom tools, memory, sessions, themes

Quick start

bun add -g @hermenics/deepseek-code

Then run deepseek inside any project. On first run you'll pick a provider and configure authentication. Run the installed command directly: invoking its script through bun run starts Bun first, which can load the project's bunfig.toml before the CLI launcher runs.

For automation, use headless pipe mode:

echo "explain this project" | deepseek --pipe
cat src/index.tsx | deepseek --pipe --json "summarize"

DeepSeek Pods on your own server

Pods can keep running after your desktop disconnects by installing the supervisor on a Linux server you control. Create a Debian 12+ or Ubuntu 24.04+ VM with your cloud provider, make sure SSH access works, then run:

deepseek pods host install ubuntu@YOUR_SERVER_IP

The installer uses your SSH connection, prepares Node.js, Bun and Chromium when needed, installs the published DeepSeek Code package, and starts a user-level service. It sends the active DeepSeek API profile through SSH and stores it in a private configuration directory on that host. The panel listens only on loopback; the installer prints an SSH tunnel command and the panel token. It does not create a cloud VM, open a public firewall port, or copy your existing local Pods database.

The host account must have passwordless sudo for one-time OS package installation and enabling the persistent user service. Your cloud provider may require billing details for a free-tier account, and its free quota and availability rules still apply. See the Pods deployment guide.

Requirements

• Bun 1.4.0+
• Node.js 18+ (starts Bun without loading the current project's .env or bunfig.toml)
• A supported LLM provider (see below)

Providers & authentication

Provider	How to authenticate	Env / config keys
DeepSeek API (default)	API key from platform.deepseek.com	DEEPSEEK_API_KEY, DEEPSEEK_BASE_URL
Amazon Bedrock	AWS IAM credentials via ~/.aws/credentials	AWS_REGION, AWS_PROFILE
Google Vertex AI	GCP service account JSON key	GCP_PROJECT, GCP_LOCATION, GCP_CREDENTIALS
Local (Ollama / LM Studio)	No auth — point to your local endpoint	LOCAL_BASE_URL, LOCAL_MODEL

Legacy credentials remain in ~/.deepseek/config.json; saved provider profiles, including their credentials, live in ~/.deepseek/provider-profiles.json with owner-only permissions. Non-secret preferences use settings.json with User < Project < Local precedence; legacy values remain readable for compatibility. Project and plugin MCP servers are off by default and require the User-scoped Enable project MCP servers setting plus workspace approval; restart DeepSeek Code after changing the setting. Plugin changes refresh their integrations live. See docs/settings.md.

Models

Switch models at any time with /model:

Model ID	Description	Context
deepseek-flash	Native visual understanding; fast, general purpose (default)	1M
deepseek-v4-pro	Advanced reasoning	1M

Each provider also exposes provider-specific models (Bedrock, Vertex, local).

Slash commands

Command	Description
/model	Switch model
/agent	Spawn a sub-agent
/memory	Manage persistent memory
/plan	Enter plan mode
/review	Code review
/vim	Toggle vim keybindings
/theme	Change color theme
/tools	List available tools
/doctor	Check runtime, workspace, credentials, settings, and MCP configuration
/verify	Run the detected project test command
/sessions export <id> [json|md]	Export a sanitized session transcript
/catalog, /marketplace	Browse curated MCP, plugin, and skill integrations
/skill list, /plugin list	Inspect available skills and installed plugins
/permissions	Explain mode, allow/deny rules, risk checks, and session approvals
/config, /settings	Open the fullscreen settings center
/help	Show all commands

Built-in tools

The agent has access to these tools out of the box:

ReadFile · WriteFile · EditFile · PatchFile · Shell · Glob · Grep · Lsp · Git · ReadFolder · WebFetch · Skill · SubAgent · AskAgent · Workflow · Memory · Todo · Introspect · MoA · AskUserQuestions

Shell command execution currently requires Linux with a working bubblewrap sandbox. On macOS, Windows, or a Linux host where the sandbox cannot start, commands fail closed before execution.

Skills are listed by origin and loaded on demand through the read-only skill tool. Plugins can contribute skills, slash commands, and MCP servers. Plugin MCP configs require workspace approval before their servers start. See the extension architecture study.

Experimental browser

The agent browser is off by default. Enable it with /features browser on; this exposes both browser and dev_server in Build and Auto modes. The browser runs an installed Chrome, Chromium, Edge or Brave over a debugging pipe, with a temporary profile and a clean environment. It uses accessibility snapshots and native browser input for navigation, inspection, interaction, screenshots, downloads and test export. Browser automation currently supports Linux and macOS; Windows needs a handle-based DevTools pipe implementation.

Each new origin needs approval. Public-page interaction has a separate approval, and typing or uploading on a public page asks every time. Private-network and metadata addresses are blocked, as are sensitive password, payment and one-time-code fields. Downloads stay in a private temporary directory and are removed when the browser closes. Use /browser status, /browser show, /browser hide or /browser close to inspect and control its window; on Linux, a visible window needs DISPLAY or WAYLAND_DISPLAY.

dev_server starts only a server declared in .deepseek/launch.json or .claude/launch.json. Starting it runs a host process outside the shell sandbox, so each start requires approval, as does a changed launch entry. The server stops when the session ends or the project changes. Example:

{
  "configurations": [
    {
      "name": "web",
      "runtimeExecutable": "bun",
      "runtimeArgs": ["run", "dev", "--host", "127.0.0.1"],
      "port": 3000
    }
  ]
}

The same configurations format works in either launch file. .deepseek/launch.json takes precedence when both exist. Each entry needs name, runtimeExecutable, port, and optional runtimeArgs, project-relative cwd, and string-valued env.

TUI behavior

• Uses the terminal alternate screen by default; it can be disabled for the next session in /settings
• Settings adapt from three panes to a sequential category → list → detail flow on narrow terminals
• Thinking output is streamed as full multiline blocks and persisted after each response
• Build, Plan, Review and Auto are real interaction modes. Review is read-only; Plan can only write its designated plan.

---

Development

Prerequisites

• Bun >= 1.4.0
• Node.js >= 18

Setup

git clone https://github.com/Hermenics/deepseek-code.git
cd deepseek-code
bun install

Commands

bun run dev          # Start in dev mode (watch)
bun run start        # Run from source
bun run build        # Production build
bun run typecheck    # Type check (tsc --noEmit)
bun run test         # Isolated serial suite, matching CI

Background task recovery

/tasks and /task <id> status distinguish task-attempt state from recorded process observations. Background shell tasks capture their native process identity. On Linux, status checks revalidate boot, PID namespace and process start time, rather than trusting a saved PID. alive only describes the recorded leader; it does not establish useful progress, descendant cleanup or completed effects. Native exit events retain their actual exit code/signal; a later kernel observation cannot reconstruct a lost result.

For process-backed tasks without an eligible recovery runner, an interrupted attempt remains interrupted even when its recorded leader is alive. Process-backed failures are not automatically retried or replayed through /task resume. Inspect status/artifacts, reconcile possible effects and submit a newly authorized command when appropriate. Eligible Linux background Shell tasks are an exception: their detached supervisor can survive a CLI restart and reattach from the persisted task snapshot without replaying the command. Generic task runners, raw stream reconnection and cross-platform process supervision are not supported.

LSP text edit proposals

With a user-configured server, lsp supports rename_preview, code_actions and code_action_preview. All three are read-only. List actions using a file and 1-based UTF-16 range, then select the returned native ID:

{"operation":"code_actions","path":"src/example.ts","line":1,"character":1,"kind":"source.organizeImports"}
{"operation":"code_action_preview","path":"src/example.ts","action_id":"<id from the listing>"}

Optional end_line/end_character default to the starting coordinates. Kinds include matching subkinds. Listings label disabled, command-dependent and deferred actions, and report omissions. Opaque server data remains inside the native session. IDs expire after another listing, observed source changes, configuration changes or server disposal.

Read each proposed target with read_file, then pass its returned arguments to edit_file. The writer checks the base hash and the runtime read version before committing. Multi-file application remains atomic per file. Command-dependent actions, resource operations and annotated edits are refused rather than partially applied. Deferred edit-only actions use codeAction/resolve when advertised; preview re-queries and requires a unique matching action with unchanged metadata. Actions with unstable provider identities may require a new listing.

Source hashes and diagnostic hints do not prove complete semantic indexes or build correctness; verify the resulting change separately.

Real TypeScript LSP check

tests/lsp-real-server.test.ts uses a temporary project and the repository's typescript-language-server development dependency by default. Set DEEPSEEK_LSP_TEST_SERVER to override its executable. The fixture runs on Node.js >= 18, uses the repository's TypeScript version, and currently skips Windows. It exercises navigation, diagnostic provenance, rename and code action application, version refresh, and independent compiler checks.

bun test tests/lsp-real-server.test.ts

Set DEEPSEEK_LSP_TEST_NODE to select another Node executable. Unversioned publications remain outside the version-bound diagnostic items; their bounded messages appear under unverified.items as investigation hints. Compiler/test verification remains separate.

User-scoped lsp.servers entries accept an initializationOptions JSON object (up to 64 KiB). For the tested TypeScript adapter, this option selects a single semantic server and avoids syntax-only startup routing:

{
  "initializationOptions": {
    "tsserver": { "useSyntaxServer": "never" }
  }
}

The fixture also checks a fresh server's first rename request with this configuration. Each server defines its own initialization options; changing them restarts its session connection.

Project structure

src/
├── agent/           # Core agent loop, providers (DeepSeek, Bedrock, Vertex)
├── commands/        # Slash command definitions
├── ui/              # React TUI components and app state
├── ink/             # Local Ink-compatible terminal renderer
├── tools/           # Agent tools (file ops, shell, git, search, etc.)
├── services/        # Cross-cutting services such as compaction
├── hooks/           # Pre/post tool execution hooks
└── index.tsx        # Entry point
tests/               # Test suite

---

Contributing

Contributions are welcome! Here's how to get started:

1. Fork the repo and create a branch from main
2. Install dependencies with bun install
3. Make your changes — keep files under 500 lines
4. Run checks before submitting:

   bun run typecheck && bun run test
   

5. Open a PR with a clear description of what changed and why

Guidelines

• Follow existing code style (TypeScript, functional where possible)
• Write tests for new features — tests live in tests/, never in src/
• One concern per PR — don't bundle unrelated changes
• Commit messages should explain the "why", not just the "what"

Reporting bugs

File a GitHub issue with steps to reproduce, or use /help inside the TUI.

---

License

Apache 2.0

---