{"slug": "when-ai-agents-write-the-code-what-s-missing-are-the-reins-introducing-basou", "title": "When AI Agents Write the Code, What's Missing Are the Reins — Introducing basou", "summary": "A developer introduced basou, an open-source harness for steering AI coding agents. The tool addresses three pain points: the loss of decision context between sessions, the cost of re-explaining context, and the inability to audit agent actions. Basou provides a replayable record of agent activity as plain files in a local-first, vendor-independent format.", "body_md": "I closed the previous post with a promise: that the development style behind this blog, and the OSS I've been shipping — a harness for steering AI coding agents — deserved their own write-up. This is that write-up.\n\nThe project is [basou](https://basou.dev). In one line: it's **a harness — a full set of tack — for steering AI coding agents**. A \"saddle\" you declare once per repository to say how the project should be driven; \"reins\" that carry intent from one session to the next; and, underneath both, a replayable record of what the agent actually did. All of it as plain files, in a `.basou/`\n\ndirectory right next to your code. Local-first: nothing leaves your machine.\n\nOnce agents write most of the code, the scarce resource isn't typing — it's **control**. The more I leaned on agents, the more the pain narrowed to three things.\n\n**One: the \"why\" evaporates between sessions.** The answer to \"what does this code do\" lives in the code; even a read-only assistant can reconstruct it. What can't be reconstructed is the living context around a decision — what you intended, which path you rejected, how far you got. That has to be captured in the moment, and what you capture is worthless unless it survives to the next session.\n\n**Two: the cost of re-explaining.** Because it wasn't captured, every session starts with a human re-narrating the context by mouth. Run three projects in parallel and you pay that tax three times over.\n\n**Three: you can't audit it.** What an agent did is buried inside vendor-specific log formats, or nowhere at all. \"That change last week — why did we do it that way?\" has no answer you can verify after the fact.\n\nbasou is my answer to those three. Not a dashboard you glance at, not an audit log you file away — tack you keep in your hands the whole time you're working. The name comes from *basou* (馬装), the Japanese word for tacking up a horse: fitting the saddle and the reins.\n\nYou **declare each repository's nature once** — public or private, what language it's in, where the canonical copy of the agent-instruction file (`AGENTS.md`\n\n) lives — in a manifest. Then `basou project`\n\nderives the rest: which roots to record, the wiring of `AGENTS.md`\n\n/ `CLAUDE.md`\n\n/ Copilot instruction files, the `.gitignore`\n\nthat keeps a private canonical file out of a public repo's history, and a workspace view that bundles multiple repositories. Humans edit the declaration; basou maintains the plumbing.\n\nEvery generating command is **dry-run by default** (`--apply`\n\nis what actually writes), and additive and non-destructive. How to consolidate the ever-multiplying pile of instruction files is a whole post on its own, so I'll save it for another time.\n\n`basou orient`\n\nanswers \"where is the work right now, and what's next\" from the **record**, not from memory. Recent decisions, open tracks, the recorded next step, and a note on whether the record itself has gone stale.\n\nThe decision record has a trick to it. A decision made mid-conversation with an agent — the reasoning, the alternatives, and why you rejected them — normally dies with the chat log. `basou decision capture`\n\nmakes the **agent itself**, while it still holds the conversation in context, emit the decision as structured data, and basou writes it down deterministically. basou never runs an LLM of its own. So the record is yours, verifiable, and works offline.\n\n`basou note`\n\nleaves a one-line \"pick up here next.\" `basou handoff generate`\n\nregenerates a handoff document for the next session — or the next teammate.\n\nThe two foundations sit on a simple, inspectable base.\n\n`.basou/sessions/<session_id>/events.jsonl`\n\nand `basou verify`\n\n.`.basou/handoff.md`\n\nand `.basou/decisions.md`\n\nare regenerated from the event log (you can hand-edit them too). Review them in an editor, or right in a PR diff.`basou run claude-code`\n\nwraps a process from the outside and records it; `basou import claude-code`\n\n/ `basou import codex`\n\nderive sessions after the fact from the logs each tool leaves behind. `basou refresh`\n\ndoes ingestion and Markdown regeneration in one pass, and `basou view`\n\nshows the whole thing in a local web UI bound to 127.0.0.1 only.Keep exactly one source of truth and regenerate the human-facing copies from it — that stance is the \"one source, many uses\" discipline from twenty years of designing business systems, carried straight into the agent era.\n\nI use basou every day, across all of my projects. The repository behind the blog you're reading is one of them. What follows isn't a staged sample — it's a real excerpt from that repository's own `.basou/`\n\n(some paths and identifiers are masked; the Japanese working notes are translated here for readability).\n\nFirst, the current position `basou orient`\n\nreturned when I resumed work. Behind it, `handoff.md`\n\nholds the same content.\n\n```\n# Handoff\n\n> Generated at 2026-07-08T13:20:50Z from ses_01KVZAFJT0..ses_01KX0Y6TPT\n\n## Current state\n\n- Last session: claude-code 2026-07-07: 110 commands, 11 files (imported) [ses_01KX0Y6TPR]\n- Last task: (no tasks recorded yet)\n\n## Recently changed files\n\n- src/components/MermaidRenderer.astro\n- src/layouts/BaseLayout.astro\n- src/pages/ja/index.astro\n- …\n\n## Recent decisions\n\n- Use the existing static image for the shared header avatar [decision_01KWYHFVDE]\n```\n\nNext, one decision made during that work, recorded like this — with the reasoning and the road not taken.\n\n```\n## Render Mermaid diagrams as SVG on the client\n\n- date: 2026-07-07\n- rationale: Build-time rendering (rehype-mermaid and friends) depends on headless\n  Chromium, which risks breaking Cloudflare's build pipeline. Instead, load mermaid.js\n  in the browser and swap the Shiki-highlighted pre[data-language=mermaid] for SVG.\n- alternatives: Pre-generate the SVG at build time (SSG) with a headless browser\n- rejected_reason: Adding a headless-Chromium dependency to the build makes builds\n  fragile; that operational risk outweighs the \"no JS required\" benefit.\n- linked_files: src/components/MermaidRenderer.astro, src/styles/global.css\n```\n\nAnd beneath all of it, the event log and its verification.\n\n```\n{\"schema_version\":\"0.1.0\",\"session_id\":\"ses_01KW0J3F…\",\"type\":\"session_started\",\"prev_hash\":\"1e4d0428…e34dc37\"}\n{\"schema_version\":\"0.1.0\",\"session_id\":\"ses_01KW0J3F…\",\"type\":\"session_status_changed\",\"from\":\"initialized\",\"to\":\"running\",\"prev_hash\":\"e3108afa…efb2bc9\"}\n{\"schema_version\":\"0.1.0\",\"session_id\":\"ses_01KW0J3F…\",\"type\":\"session_ended\",\"exit_code\":0,\"prev_hash\":\"9d11ac73…b4b29f0e\"}\n\n$ basou verify\nses_01KW0J3F…  verified (5 events)\n```\n\nMarkdown is easy to read, but it's only a copy. The source of truth is the hash-chained JSONL — which is why a machine can answer \"has this record been tampered with?\"\n\n`.basou/`\n\ndirectory next to your code. Nothing leaves the machine.`.basou/`\n\n, and generating commands are dry-run by default and non-destructive. Adopting it — or backing out — is low-risk.\n\n```\n# Node.js >= 20.10\nnpm install -g @basou/cli\n\ncd /path/to/your/project\nbasou init\n\n# Try a minimal record by hand\nbasou task new --title \"Refactor login form\"\nbasou session note --body \"Starting from a look at auth.ts\"\nbasou handoff generate && cat .basou/handoff.md\n\n# Or ingest in bulk from the agent logs already on disk\nbasou refresh\nbasou view   # local UI, 127.0.0.1 only\n```\n\nA walkthrough with sample output and the usual gotchas is at [basou.dev/quickstart/](https://basou.dev/quickstart/).\n\nOne more thing: if basou is the side that records what an agent *did*, there's a companion project, [Kozou](https://kozou.org), for the side that tells an agent what a database *means*. I'll introduce that one separately too.\n\nThe repository is [github.com/basou-dev/basou](https://github.com/basou-dev/basou); the docs are at [basou.dev](https://basou.dev). If something trips you up on 0.x, I'd be grateful for an issue.\n\nThe Japanese version of this post — its \"paired\" article — is already live.", "url": "https://wpnews.pro/news/when-ai-agents-write-the-code-what-s-missing-are-the-reins-introducing-basou", "canonical_source": "https://dev.to/takashimatsuyama/when-ai-agents-write-the-code-whats-missing-are-the-reins-introducing-basou-1m62", "published_at": "2026-07-09 02:00:39+00:00", "updated_at": "2026-07-09 02:41:17.847292+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-tools", "ai-infrastructure", "ai-safety"], "entities": ["basou", "Claude", "Codex", "Copilot"], "alternates": {"html": "https://wpnews.pro/news/when-ai-agents-write-the-code-what-s-missing-are-the-reins-introducing-basou", "markdown": "https://wpnews.pro/news/when-ai-agents-write-the-code-what-s-missing-are-the-reins-introducing-basou.md", "text": "https://wpnews.pro/news/when-ai-agents-write-the-code-what-s-missing-are-the-reins-introducing-basou.txt", "jsonld": "https://wpnews.pro/news/when-ai-agents-write-the-code-what-s-missing-are-the-reins-introducing-basou.jsonld"}}