The workspace
dsh is a pnpm workspace declared in the root package.json:
"workspaces": [
"vendor/*",
"packages/*/*",
"native/landlock-run",
"native/landlock-run/packages/*",
"apps/*",
"website"
]The three structural patterns are visible here:
packages/*/*— the product, organized aspackages/<group>/<pkg>, the familiar "group of packages" shape.vendor/*— the vendored framework layer (Cordis and friends), which behaves like a separate tier.apps/*,native/...,website,examples,python— product assemblies and deployment roots.
Top-level layout
apps/ product launchers: `cli` (the `dsh` bin) and `web` (the frontend)
docs/ the official VitePress documentation site (upstream)
examples/ runnable demos, one directory per interface (headless, jsonrpc, mcp, acp, ...)
native/ native code: `landlock-run` and its platform-split packages
packages/ the product tier — 49 group directories
python/ the Python SDK and its runtime
scripts/ repo tooling (gates, generators, release)
vendor/ source-vendored Cordis framework + foundation libs
website/ another docs/VitePress entry (`@deepseek-ai/website`)The packages tier: 49 groups
Counting by directory, packages/ holds 49 group directories, and resolving the packages/*/*/package.json glob gives 219 package-tier packages — the exact number behind the home page's "One command, 219 packages" headline. The reproducible numbers at this commit are 49 groups, 219 package-tier projects, and 237 workspace members once apps/vendor/native/examples/website/python are added. The groups and their role:
| Group | One-line role |
|---|---|
core | the agent loop, sessions, scope, tools registry, system prompt |
session | the SessionEvent log, session domain, projection/reference material |
context | context sources feeding model-visible history |
compaction | turning long logs into summarized context |
sandbox | confinement backends, sandbox policy, fs observation |
fs | filesystem service, local/sandbox providers, fs tools |
shell | the bash/pwsh capability seam + tools (canonical seam example) |
llm | the LLM service, DeepSeek provider, token meter |
api | API gateway and remotes (Host↔Client RPC) |
host | Host platform: webserver, frontend-static, apiproxy |
client | the browser/runtime side and every UI module (ui-*) |
sdk | the JSON-RPC SDK: client, server, protocol |
subagent | the subagent capability seam + its many providers |
workflow | workflow/worker-thread orchestration |
goal | same-session goals and goal-round driving |
plan | plan mode |
skill | skills registry, filesystem skills, tool-skill |
mcp | the MCP client |
lsp | LSP integration |
acp | the Agent Client Protocol server surface |
hooks | Claude Code / Codex hooks bridges |
storage | persistence backends |
settings | the settings service |
credentials | credential storage |
guard | timeout / repeat-reminder guards |
feedback | user feedback capture |
identity | node identity / session identity |
interaction | commands, questions, approvals at runtime |
jobs | the background-jobs service |
schedule | durable reminders |
spill | context-overflow spill |
attachment | attachments to messages |
bundle | the composition bundles: base, web-app, headless |
boot | boot glue and cmdline: app-boot, cmdline |
code-runtime | code execution runtimes |
e2b | the E2B provider |
examples | additional example/demo packages |
extensions | extra extension points |
runtime-diagnostics | runtime diagnostics tooling |
test-support | test harnesses, mock LLM server |
typert | the type-reflection / code generator |
util | small shared utilities (home-paths, timeout, brand, ...) |
web | web/search capability tools (tool-web, web-fetch-http, search providers) |
workspace | workspace model (roots, selection) |
preset | the agent preset composition |
session-query | querying/log-export over sessions |
subprocess | process spawning |
terminal | persistent terminal (PTY) backends |
todo | the todo tool |
(Some groups add their model-facing tools in a sibling group — e.g. todo/tool-todo, session-query/tool-session-query — rather than inline, which is why passing a group's role in one line is approximate. The docs/module-graph.md file is the generated, authoritative dependency map.)
The other tiers
Beyond packages/, the workspace contains:
| Tier | Members | Role |
|---|---|---|
apps/ | cli (@deepseek-ai/dsh), web (@deepseek-ai/dsh-web-frontend) | the dsh launcher and the browser frontend build |
vendor/ | 9 packages (cordis, loader, include, group, hmr, timer, logger-console, cosmokit, schemastery) | source-vendored framework, renamed into @deepseek-ai scope |
native/ | landlock-run + Linux arm64/x64 platform packages + entry | the Landlock sandbox launcher |
examples/ | headless-agent, jsonrpc-agent, mcp-memory, web-cordis, web-schedule, acp-agent | runnable demos |
website/ | @deepseek-ai/website | the docs site |
python/ | sdk-runtime | the Python SDK distribution/deploy root |
The vendor tier is arguably the most consequential for the code-reader: importing cordis anywhere in the product actually resolves to @deepseek-ai/cordis from vendor/cordis, so the framework is itself a pinned, diffs-guarded part of this repository (see Vendored Libraries).
Naming convention
Every product package is @deepseek-ai/dsh-<name> — the harness family. Notably:
- The CLI package is just
@deepseek-ai/dsh(no suffix), the root manifest is@deepseek-ai/dsh-root, and the frontend is@deepseek-ai/dsh-web-frontend. - The vendored framework uses the same scope but a different family marker:
@deepseek-ai/cordis,@deepseek-ai/cordis-plugin-loader, and so on, keeping the harness packages (dsh-*) visually distinct from the hosted framework (cordis-*). - Within one group, packages share the
dsh-prefix and often a role suffix:@deepseek-ai/dsh-tool-bash,@deepseek-ai/dsh-bash-local,@deepseek-ai/dsh-bash-sandbox.
One capability seam → several packages
The naming is a symptom of the deeper organizational principle: one capability seam maps to several packages, one package per role. The canonical example is the bash/shell seam in packages/shell/:
| Package | Role |
|---|---|
@deepseek-ai/dsh-shell | Service Definition — ShellExecutor (ctx.shell) + vocabulary |
@deepseek-ai/dsh-bash-local | Service Provider — local subprocesses |
@deepseek-ai/dsh-bash-sandbox | Service Provider — same mechanics, confined via ctx.sandbox |
@deepseek-ai/dsh-tool-bash | Consumer — the model-facing bash tool |
This is exactly the three-role Service Definition / Provider / Consumer pattern from docs/architecture.md, and it recurs across the monorepo: subagent (definition subagent/subagent, providers subagent-*, consumer tool-subagent), filesystem (fs/fs, fs/fs-local + fs/fs-sandbox, fs/tool-fs), LLM (llm/llm, the llm-* providers, no single tool). A package may combine roles, but a single role alone is not a seam — which is why the repository tends to have several small packages in a group instead of one fat one.
Where the counts come from
Two generated files give ground truth for the structure:
docs/module-graph.md— an inter-package dependency graph derived from each package'speerDependenciesand grouped bypackages/<group>/<pkg>.docs/graph-atlas.md— an index of the relationship diagrams (module graph, tool catalog, capability seams, app compositions, event matrix, lifecycle).
Regenerate the module graph with pnpm run gen-module-graph; verify with pnpm run verify-module-graph. The apps/cli/composition.md file renders the composed dsh-base shared profile for the CLI.
Further reading
- What Is DeepSeek Harness? — what the 49 groups assemble into.
- “Everything Is a Plugin” Philosophy — the seam model behind the layout.
- Vendored Libraries — the
vendor/*tier in detail. docs/module-graph.md— the generated dependency graph.docs/graph-atlas.md— the diagram index.packages/shell/shell/README.md— the canonical seam, documented in miniature.