Principles
Replaceable plugins. An honest journal.
The official design comes down to two sentences. Boot, loop, seams, and UI all unfold from them.
plugin
Everything is a plugin
Every ability is a brick: brain, hands, journal, fence, loop, and window. Replace one without tearing down the city.
DeepSeek Harness is built on Cordis. Model adapters, tools, skills, sessions, sandboxes, storage, loops, scheduling, and UI are plugins. Configuration selects, replaces, or extends them without editing dsh source. There is no privileged kernel to patch.
trace
Every run is traceable
Every sentence the model sees is already written in an append-only journal. Close it, reopen it, and the story remains.
System prompts, reasoning, tool calls and results, subagent scheduling, and every context injection are appended to the Session log. Resume, fork, search, and replay all use the same event stream. A runtime invariant enforces: model-visible means logged.
Four agent outfits
A Profile decides how the whole city is assembled. An agent preset decides what one agent wears by mounting a smaller tree inside an isolate realm.
standard
Standard mode
A full coding agent: edit files, run commands, browse, use skills, plan, track goals, ask helpers, and orchestrate.
The full toolset and coding persona. Agent preset: standard.
code
PTC Mode
The standard kit plus a lab where TypeScript can orchestrate many operations together.
The UI label is now PTC Mode; the internal code preset and Code Mode SDK names remain.
minimal
Minimal mode
Only a mouth and an eraser, useful for evaluating a model.
Persistent bash plus str_replace_editor, designed for benchmarks.
creator
Creator mode
The agent may inspect its current plugins and attach new bricks to itself.
Standard abilities plus runtime introspection, in-memory plugin trials, and new preset composition.
Where new behavior belongs
Find the right hook here before changing the loop itself. The source calls this the ownership location for new behavior.
| Goal | Hook | Plain-language version |
|---|---|---|
| Add a model provider | ctx.llm | Invite another teacher. The classroom stays put. |
| Add a model-facing capability | ctx.tools | Put a tool in the cabinet; its instructions join the handbook. |
| Give one session a different capability set | agent preset + isolate | Change this agent's outfit and give it its own tap. |
| Add shell execution | ctx.shell → ctx.subprocess | The mouth gives an order; the runner performs it. |
| Add a persistent terminal | ctx.terminals + dsh-tool-terminal | Hang up a blackboard that never closes. |
| Add human commands | ctx.commands | Issue the command yourself without asking the model. |
| Add slow background work | ctx.jobs · job_* tools | Put work in the washing machine and check later. |
| Add a filesystem or write policy | ctx.fs or fs/* events | Replace the desk or add a rule before writing. |
| Restrict spawned processes | ctx.sandbox.confine(argv) | Put up the fence before going out. This is not a move. |
| Intercept requests, tools, or turns | agent/* or tools/* | A hall monitor can stamp the pass or stop the school day. |
| Add model-visible context | agent.inject() | Slide a note under the door. Do not ring; wait for the next claim. |
| Add a UI or editor | ctx.agents + session/event | The window watches journal broadcasts; it never invents the story. |
| Add a conversation node | ConversationNodeDefinition | Pin another picture into the felt board. |
| Add persistent session state | extend SessionEventMap | Add a sentence type to the journal; replay reads it there too. |
| Generate session titles | the single ctx.sessionTitle provider | Only one person may name the journal. |
| Manage goals in one session | ctx.goals + agent/* | Pin a goal to the fridge and remove it when done. |
| Fork a journal still being written | ctx.sessions.fork(...) | Copy the journal and start a new story from one page. |
| Scope registrations to one agent | agent.ctx | Put the item in this person's locker, not the lobby. |