One Shell That Drives Every Coding Shell

A video went up a few hours ago walking through the architecture of DeepSeek's internal coding harness. I watched it with the specific discomfort of someone recognising their own diagrams.

Then I went and pulled the commit dates.

The thing itself

The hard part of driving another coding agent is not the loop. It is refusing to reimplement the agent.

Everyone's first instinct is to rebuild Claude Code's behaviour against the raw API — you control the prompt, you control the tools, it feels tidy. It is a trap. You inherit none of the skills, none of the hooks, none of the account handling, and you spend the next six months reimplementing a product that is shipping updates faster than you can track them.

So aither-adk doesn't. It resolves the real binary:

raw_bin = claude_bin or os.environ.get("AITHER_CLAUDE_RUNNER_BIN", "claude")
# shutil.which honors PATHEXT — required on Windows, where the claude
# launcher is a .cmd shim rather than an extensionless executable.
self.claude_bin = shutil.which(raw_bin) or raw_bin

and then runs the actual product, headless, with a scope:

argv = [
    self.claude_bin,
    "-p",
    "--output-format", "stream-json",
    "--allowedTools", ",".join(scope.allowed_tools),
]

The task prompt goes in over stdin, never argv — argv is visible in the process table, and a prompt routinely carries things you would not want a local ps to show. Each run gets its own CLAUDE_CONFIG_DIR, so two concurrent subagents can't fight over one account's state. A watchdog kills the process tree on timeout.

That is aither-adk/adk/claude_runner.py, and it is 1,997 lines, because the interesting part was never the spawn — it was the scope validation, the concurrent record locking, and the teardown.

Then I stopped writing runners

The second version is the one I'm actually proud of, and it came from being annoyed.

Writing a bespoke integration per agent doesn't scale — you end up with a claude_runner.py, a codex_runner.py, a gemini_runner.py, each drifting from the others. So the harnesses became data:

HarnessSpec(
    id="codex",
    label="OpenAI Codex CLI",
    transport=Transport.ONESHOT_PER_TURN,
    binary="codex",
    version_argv=["--version"],
    install_hint="npm i -g @openai/codex",
    json_lines=True,
    build_argv=lambda spec, launch: [spec.binary, "exec", "--json", launch.prompt],
)

A tenth harness is a row in a table, not a new driver. The registry currently declares ten: claude, codex, gemini, aider, opencode, acp, aither, terminal, sandbox, and a group harness that fans one task across several at once.

It also tells you what it could drive and how to install it — there is a comment in that file that reads "instead of silently pretending the world is Claude-only", which is the whole design in one line.

The commit message was: "one shell that drives every coding shell."

The receipts

I publish this architecture as I build it, so the dates are not a claim, they're a git log:

Twenty-eight days on the runner. Thirteen on the generalisation.

I want to be precise about what that does and doesn't mean. It does not mean anyone copied anyone — DeepSeek has been building agent infrastructure far longer than I have, and internal systems predate the talks that describe them. It means the design space has a shape, and two people walking it independently found the same corners: don't reimplement the product, one task out one answer back, tear down the tree.

Where they beat me

If I only told you the parts where I was early, this would be a worse post and you'd be right to distrust it.

Their fourth pillar is "the folder is the status." Decision notes live in .agents/notes/, and the directory is the lifecycle state — implemented/, archived/, proposed/, rejected/. Their counts, from the talk: 505 implemented, 142 archived, 25 proposed.

Mine is a markdown ledger with a status column. So I measured it:

TECH_DEBT.md + archive:  1,604 rows
                           827  open
                           123  resolved
                            16  fixing
                             4  refuted
                           632  UNPARSEABLE

Thirty-nine percent of my decision records have a status no parser can read. Not because anyone was careless — because free text drifts. open, open,, refuted-my-own-cwd-not-a-repo-defect. My own rules file already diagnoses it: "the archive accumulated ~1,200 distinct status strings, which is how the sweeper came to be blind to 90% of its queue."

A directory can't drift. There are four spellings, the filesystem enforces them, and the report is ls | wc -l. Their chart is trivially derivable; mine needed a bespoke parser that then failed on 39% of the rows.

That is a better design than mine and I'm taking it.

They're also deeper on Codex specifically — they run a persistent codex app-server over stdio, where my spec is one process per turn. Same product, shallower integration.

What this actually tells me

Convergent evolution is the strongest evidence a design is correct, and it is much better news than being first.

Two people, working independently, on different continents, at wildly different headcounts, walked into the same room and put the furniture in the same places: don't reimplement the product, resolve the real binary, one task out and one answer back, tear down the tree. Nobody decided that. It's just where the problem pushes you once you take it seriously.

What I'd add for anyone building in this space: the generalisation is worth reaching for earlier than feels justified. I wrote one runner, felt the pull toward writing a second, and turned the thing into a table instead. That table is why an eleventh agent CLI is a five-line row rather than a fortnight — and why, when the next one ships, I'll support it the same afternoon.

And I'm taking their ledger idea. Folder-as-status is better than what I have, for a reason that generalises well past decision notes: a filesystem path cannot drift, and a free-text field always will. Four directories the OS enforces beats a status column every time, and the report is ls | wc -l.

The harness is aither-adk, and it's open — pip install aither-adk, then adk shell harnesses to see what your machine can drive. The talk that prompted this is worth your time; the folder-as-status idea alone paid for the hour.