I built this mainly to answer one question while trying to understand coding-agent systems:
What's the smallest agent harness that is still architecturally complete?
By "complete" I don't mean feature-complete. I mean that the system still has clear answers to questions like: where truth lives, who owns state, where permissions are enforced, how models and tools are composed, how a session survives a crash, and whether adding another feature requires another agent implementation.
I studied DeepSeek Harness as the main reference. I found it interesting because its architecture is fairly explicit: capabilities have lifecycle and dependency semantics, model-visible history is derived from durable session state, authority is separated from model reasoning, and user surfaces sit over a shared runtime.
Rather than fork-and-prune to make it look smaller, I tried to re-derive those properties into a minimal system, which now exists as a small open-source project called MiniDSH.
The resulting design ended up with a few principles that matter more than LOC:
- the append-only session log is the canonical source of truth;
- models, tools, persistence, authority and context have explicit seams and owners;
- the model proposes an effect, but policy and the effect boundary decide whether it happens;
- the model is a routed capability, not synonymous with the agent;
- terminal, browser and headless are surfaces over one runtime;
- something gets a first-class composition boundary only if it actually needs to be replaced, scoped, removed or independently owned.
The last point became a useful rule:
everything evolvable has a seam, but not everything needs to become a plugin.
Another valuable experiment was the development process itself.
Most of this project was built through Claude Code sessions. One failure mode I kept noticing in AI-assisted development: coding agents are very good at producing locally reasonable code, while the overall system quietly becomes fragile and incoherent over time.
A feature needs browser verification, so a browser module appears; Another needs memory, so a memory manager appears. Each addition can make sense locally while the architecture gradually becomes a collection of parallel subsystems rather than a self-consistent system.
So I tried to invert the process:
architecture defines sessions; sessions do not define architecture.
Before implementing a new feature, I tried to answer where it belongs, what it owns, what it may depend on, what its lifecycle is, and where its durable state goes. If there was no clear architectural home, I treated that as an architecture problem rather than an excuse to create another parallel subsystem.
Meanwhile, the architecture itself wasn’t treated as sacred. Several sessions were deliberately hardening/review sessions whose job was to falsify the existing design. They found documented invariants that were not actually true, implementation assumptions that failed against real providers or operating systems, and some original plans that contradicted the implementation evidence or upstream DSH research.
That combination now seems important to me:
design the system space before filling it, but continuously try to falsify the system space itself.
This project is the concrete experiment behind these ideas. It's still an early v1 and deliberately incomplete; I don't consider it a mature coding-agent product like Claude Code, DSH, Codex, etc. The useful part for me has been making the architecture explicit enough that a later session can still answer "where does this belong?" before touching code.
GitHub: https://github.com/earthwalker17/MiniDSH
If you want to try it in browser:
npm install -g minidsh
minidsh web --cwd .
I’d especially appreciate feedback from people who have worked on agent runtimes, plugin ecosystems, compilers, distributed systems, or similar things.
Where do you think this architecture is over-designed, under-designed, or simply wrong?
And more broadly: what do you consider the true minimum set of invariants/components for a modern agent harness?
Top comments (4)
The distinction between the append-only session log and the model-visible context is where most agent systems either stabilize or slowly rot.
Early agent architectures often treat the conversational context window as the state machine itself. As sessions stretch across hours or days, context compaction and window sliding quietly discard early constraints, turning long-running execution into random walk behavior.
Treating the raw event log as immutable and deriving the prompt context as a lossy, point-in-time projection keeps the actual system state decoupled from the model's token limits. If a tool call fails or a network connection drops mid-flight, the session replay reconstructs the exact world state without having to rely on the model remembering what happened ten turns ago.
Yes. Sessions can last longer and longer, but the model's context window won't grow infinitely. So there comes failure modes where session history grows over model context and it keeps forgeting things or doing stupid walkaround.
I used three parts to solve this problem in my project:
These seem essential for making long-running execution stable and trustworthy.
The shared runtime makes cross-surface approval an interesting optional stress test. Could a terminal-started tool action pause for human approval in the browser and resume in the same runtime, without adding another agent implementation?
Yes, with one caveat. In V1, approvals belong to the runtime/protocol rather than terminal UI. They’re keyed by a durable approval ID, so if the terminal and browser are attached to the same runtime/session, a tool call started from the terminal can pause, be answered from the browser, and then continue the same agent turn. No second agent implementation needed.
The caveat is that separately launched terminal and web processes don’t automatically converge onto one shared host today; both clients need to be attached to the same runtime instance.
I agree this is a very good stress test for the “surfaces own transport/presentation, not agent semantics” rule. Planning to improve it in future versions.