{"id":"27ea0154-cbdd-4ee3-b0bc-aef4e8f1efa1","slug":"hermenics-deepseek-code","kind":"mcp","name":"deepseek-code","summary":"A DeepSeek-powered coding assistant that lives in your terminal.","owner":"Hermenics","repoUrl":"https://github.com/Hermenics/deepseek-code","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":4,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-04-13T02:11:49.000Z","addedAt":"2026-10-21T17:11:55.463Z","logoUrl":"https://avatars.githubusercontent.com/u/297012551?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools"],"tags":["ai","bun","coding-assistant","deepseek","react","terminal","tui"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-25T23:16:08.266Z","sample":false,"url":"https://conduits.dev/tools/hermenics-deepseek-code","language":"TypeScript","transports":["stdio"],"install":{"npm":"@hermenics/deepseek-code"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"
\n\n\"DeepSeek\n\n
\n\n

\n \"npm\n \"DeepSeek\"\n \"Apache\n \"CI\"\n

\n\n

An open-source, DeepSeek-powered coding assistant that lives in your terminal.

\n\n
\n\n---\n\n
\n \"DeepSeek\n
\n Real DeepSeek Code CLI with a deterministic local model and an isolated demo project.\n
\n\n---\n\n## Features\n\n- **Agentic coding** — reads/writes files, runs shell commands, searches code, manages git\n- **Multi-provider** — DeepSeek API, Amazon Bedrock, Google Vertex AI, or any local model (Ollama, LM Studio)\n- **Full TUI** — alternate-screen interface with streamed thinking, rich markdown, and vim mode\n- **Session command center** — press Left on an empty prompt to search, switch, rename or delete saved sessions across projects\n- **Unified agents** — scoped primary agents and sub-agents with editable base prompts\n- **DeepSeek Pods** — persistent agents that keep scheduled and queued work running under a host supervisor\n- **Settings center** — fullscreen, searchable User/Project/Local configuration with visible origins\n- **MCP support** — connect to any Model Context Protocol server for extended tooling\n- **Project guidance** — loads a root `AGENTS.md` alongside `DEEPSEEK.md`\n- **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\n- **Extensible** — slash commands, custom tools, memory, sessions, themes\n\n## Quick start\n\n```bash\nbun add -g @hermenics/deepseek-code\n```\n\nThen run `deepseek` inside any project. On first run you'll pick a **provider** and configure authentication.\nRun 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.\n\nFor automation, use headless pipe mode:\n\n```bash\necho \"explain this project\" | deepseek --pipe\ncat src/index.tsx | deepseek --pipe --json \"summarize\"\n```\n\n### DeepSeek Pods on your own server\n\nPods 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:\n\n```bash\ndeepseek pods host install ubuntu@YOUR_SERVER_IP\n```\n\nThe 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.\n\nThe 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](docs/persistent-agents.md#install-on-a-server-you-control).\n\n### Requirements\n\n- [Bun](https://bun.sh) 1.4.0+\n- Node.js 18+ (starts Bun without loading the current project's `.env` or `bunfig.toml`)\n- A supported LLM provider (see below)\n\n## Providers & authentication\n\n| Provider | How to authenticate | Env / config keys |\n|----------|--------------------|--------------------|\n| **DeepSeek API** (default) | API key from [platform.deepseek.com](https://platform.deepseek.com/api_keys) | `DEEPSEEK_API_KEY`, `DEEPSEEK_BASE_URL` |\n| **Amazon Bedrock** | AWS IAM credentials via `~/.aws/credentials` | `AWS_REGION`, `AWS_PROFILE` |\n| **Google Vertex AI** | GCP service account JSON key | `GCP_PROJECT`, `GCP_LOCATION`, `GCP_CREDENTIALS` |\n| **Local (Ollama / LM Studio)** | No auth — point to your local endpoint | `LOCAL_BASE_URL`, `LOCAL_MODEL` |\n\nLegacy 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](docs/settings.md).\n\n## Models\n\nSwitch models at any time with `/model`:\n\n| Model ID | Description | Context |\n|----------|-------------|---------|\n| `deepseek-flash` | Native visual understanding; fast, general purpose (default) | 1M |\n| `deepseek-v4-pro` | Advanced reasoning | 1M |\n\nEach provider also exposes provider-specific models (Bedrock, Vertex, local).\n\n## Slash commands\n\n| Command | Description |\n|---------|-------------|\n| `/model` | Switch model |\n| `/agent` | Spawn a sub-agent |\n| `/memory` | Manage persistent memory |\n| `/plan` | Enter plan mode |\n| `/review` | Code review |\n| `/vim` | Toggle vim keybindings |\n| `/theme` | Change color theme |\n| `/tools` | List available tools |\n| `/doctor` | Check runtime, workspace, credentials, settings, and MCP configuration |\n| `/verify` | Run the detected project test command |\n| `/sessions export [json\\|md]` | Export a sanitized session transcript |\n| `/catalog`, `/marketplace` | Browse curated MCP, plugin, and skill integrations |\n| `/skill list`, `/plugin list` | Inspect available skills and installed plugins |\n| `/permissions` | Explain mode, allow/deny rules, risk checks, and session approvals |\n| `/config`, `/settings` | Open the fullscreen settings center |\n| `/help` | Show all commands |\n\n## Built-in tools\n\nThe agent has access to these tools out of the box:\n\n`ReadFile` · `WriteFile` · `EditFile` · `PatchFile` · `Shell` · `Glob` · `Grep` · `Lsp` · `Git` · `ReadFolder` · `WebFetch` · `Skill` · `SubAgent` · `AskAgent` · `Workflow` · `Memory` · `Todo` · `Introspect` · `MoA` · `AskUserQuestions`\n\nShell 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.\n\nSkills 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](docs/skills-plugins-mcp-research.md).\n\n### Experimental browser\n\nThe 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.\n\nEach 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`.\n\n`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:\n\n```json\n{\n \"configurations\": [\n {\n \"name\": \"web\",\n \"runtimeExecutable\": \"bun\",\n \"runtimeArgs\": [\"run\", \"dev\", \"--host\", \"127.0.0.1\"],\n \"port\": 3000\n }\n ]\n}\n```\n\nThe 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`.\n\n## TUI behavior\n\n- Uses the terminal **alternate screen** by default; it can be disabled for the next session in `/settings`\n- Settings adapt from three panes to a sequential category → list → detail flow on narrow terminals\n- Thinking output is streamed as full multiline blocks and persisted after each response\n- Build, Plan, Review and Auto are real interaction modes. Review is read-only; Plan can only write its designated plan.\n\n---\n\n## Development\n\n### Prerequisites\n\n- [Bun](https://bun.sh) >= 1.4.0\n- Node.js >= 18\n\n### Setup\n\n```bash\ngit clone https://github.com/Hermenics/deepseek-code.git\ncd deepseek-code\nbun install\n```\n\n### Commands\n\n```bash\nbun run dev # Start in dev mode (watch)\nbun run start # Run from source\nbun run build # Production build\nbun run typecheck # Type check (tsc --noEmit)\nbun run test # Isolated serial suite, matching CI\n```\n\n### Background task recovery\n\n`/tasks` and `/task 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.\n\nFor 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.\n\n### LSP text edit proposals\n\nWith 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:\n\n```json\n{\"operation\":\"code_actions\",\"path\":\"src/example.ts\",\"line\":1,\"character\":1,\"kind\":\"source.organizeImports\"}\n{\"operation\":\"code_action_preview\",\"path\":\"src/example.ts\",\"action_id\":\"\"}\n```\n\nOptional `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.\n\nRead 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.\n\nSource hashes and diagnostic hints do not prove complete semantic indexes or build correctness; verify the resulting change separately.\n\n### Real TypeScript LSP check\n\n`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.\n\n```bash\nbun test tests/lsp-real-server.test.ts\n```\n\nSet `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.\n\nUser-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:\n\n```json\n{\n \"initializationOptions\": {\n \"tsserver\": { \"useSyntaxServer\": \"never\" }\n }\n}\n```\n\nThe 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.\n\n### Project structure\n\n```\nsrc/\n├── agent/ # Core agent loop, providers (DeepSeek, Bedrock, Vertex)\n├── commands/ # Slash command definitions\n├── ui/ # React TUI components and app state\n├── ink/ # Local Ink-compatible terminal renderer\n├── tools/ # Agent tools (file ops, shell, git, search, etc.)\n├── services/ # Cross-cutting services such as compaction\n├── hooks/ # Pre/post tool execution hooks\n└── index.tsx # Entry point\ntests/ # Test suite\n```\n\n---\n\n## Contributing\n\nContributions are welcome! Here's how to get started:\n\n1. **Fork** the repo and create a branch from `main`\n2. **Install** dependencies with `bun install`\n3. **Make your changes** — keep files under 500 lines\n4. **Run checks** before submitting:\n ```bash\n bun run typecheck && bun run test\n ```\n5. **Open a PR** with a clear description of what changed and why\n\n### Guidelines\n\n- Follow existing code style (TypeScript, functional where possible)\n- Write tests for new features — tests live in `tests/`, never in `src/`\n- One concern per PR — don't bundle unrelated changes\n- Commit messages should explain the \"why\", not just the \"what\"\n\n### Reporting bugs\n\nFile a [GitHub issue](https://github.com/Hermenics/deepseek-code/issues) with steps to reproduce, or use `/help` inside the TUI.\n\n---\n\n## License\n\n[Apache 2.0](./LICENSE)\n\n---\n\n
\n

Made with ❤️ by Hermenics

\n
\n"}