Repository navigation
MiniDSH 1.0.0
Minimal surface. Complete architecture.
MiniDSH 1.0.0 is the first public release: the smallest coding-agent harness a developer can install, point at a repository, and use daily without reading the architecture — and a reference architecture small enough to read in a sitting. It studies DeepSeek Harness as an architecture textbook and re-derives from it the minimum system that keeps the properties that matter. It is an independent educational and engineering project, not affiliated with DeepSeek.
npm install -g minidsh # Node ≥ 24; DEEPSEEK_API_KEY or ANTHROPIC_API_KEY in the environment
minidsh chat --cwd path/to/repoWhat ships
- One runtime, three ways in.
minidsh run(headless),minidsh chat(terminal) andminidsh web(browser), plusminidsh serve, a newline-delimited JSON-RPC host on stdio. The terminal and the browser are protocol clients that hold no semantics of their own. - The session log as the only truth. An append-only JSONL log with twenty-seven event kinds; resume and fork from any stored log; crash repair that closes an interrupted turn; a single-writer lease; and a runtime invariant that what the model sees is exactly what the log derives.
- Authority as a durable plane. Sandbox modes, an approval policy and named presets, every switch and decision an event. File writes are fenced inside the filesystem provider; shell commands are confined by bubblewrap on Linux and Seatbelt on macOS, each probed before it is claimed, with what the host delivered recorded on every session's opening stamp. Delegated children open under a ceiling they cannot widen.
minidsh sessions show <id> --auditreads the whole plane back. - Two providers, one vocabulary. DeepSeek and Anthropic adapters over a provider-neutral stream; the route is a durable fact a session can change mid-conversation, and a
model-rolesrow sends a purpose (a compaction summary, a delegated child, a vision verifier) down a different route. - Context that manages itself without losing anything. A pure meter over the log, compaction that replaces a range while the shadowed events stay, bounded recall of what was shadowed, spill for oversized output,
AGENTS.mdas context. - Composition from disk. Thirty-five built-in plugin rows layered by
~/.minidsh/composition.jsonand--patchfiles, with per-row provenance and a composition stamp in every session.
Verification behind this tag
pnpm check(typecheck, lint, the dependency gate, 676 tests) green on Ubuntu, macOS and Windows in CI, each followed by packing the tarball, installing it into an empty directory and starting the installed binary.- The eight live end-to-end arcs against the real providers, run three times on Windows and three times on Linux under bubblewrap before the tag;
live.ymlgreen on Ubuntu (bubblewrap) and macOS (Seatbelt), both driving a real task through the installed package. - The published tarball installed into an empty directory and driven through a real task.
Known limitations
The full register is ARCHITECTURE.md §13. The ones most likely to matter first: Windows has no shell confinement backend, so every command there asks; confinement bounds file effects only, not the network or the environment; the filesystem fence cannot follow hard links; tool execution is sequential and delegation is foreground.