prashant joshi

Case study · 2026 · Shell, Python, Claude Code

A harness for coding agents on one laptop

Status: in daily use; the repository is private. This page describes the design. A cleaned-up public extract of the reusable parts is planned.

The problem

Coding agents are fast, but they are also confidently wrong, and willing to run git push --force. I wanted agents to do real work on my own machine across research, implementation and verification, under three constraints:

  1. Nothing destructive or externally visible happens without me.
  2. Everything is observable afterwards: what ran, what it decided, what it cost.
  3. Parallelism is bounded by the machine, not by optimism.

Principle: the agent runtime is the platform; add only thin glue

Claude Code already provides the main loop, subagents, tools, hooks and memory. Building another orchestrator on top would duplicate it. So the custom code is small, about 250 lines across the runner and the hooks, and every piece fills a gap I could demonstrate.

The pieces

Piece What it does Why
Guard hook (PreToolUse) Classifies every shell command and file path before it runs. Catastrophic commands are denied outright. Privilege escalation, destructive git, pipe-to-shell, recursive deletes, publishing actions (git push, gh pr create/merge, npm publish) and secret-bearing paths require my approval. Turns “please be careful” in a prompt into an enforced policy. Heredoc bodies are stripped before matching, so text about a command doesn’t trigger it, but heredocs fed to a shell or interpreter are still inspected.
Trace hook (PostToolUse / Stop / SubagentStop) Appends a JSONL event for each tool call and gate decision. An audit trail I can grep, and later the basis for reports on tokens and cost.
DAG runner (aos-run, stdlib Python) Runs a JSON spec of shell and agent tasks with dependencies and per-task checks. Concurrency is min(spec cap, advised parallelism), taken from live memory pressure. Every failure is typed: timeout, transient (retried), exit_nonzero, check_failed, dep_failed, spawn_error. --resume re-runs only the tasks that didn’t pass. Bounded, observable fan-out with honest failure semantics, instead of “ran 5 agents, something happened”.
Specialist agents researcher (every claim needs a source URL), implementer (isolated git worktree, tests), verifier (skeptical re-check against acceptance criteria). Separating the producer from the checker caught real errors.
Ops glue One-screen resource and token status; secrets via the OS keychain; scheduled encrypted backups with a restore drill that must pass before the schedule can be installed; a doctor command as the acceptance check. A system you can’t restore isn’t a system.

Evidence

Trade-offs

What it taught me