DEV Community: Takashi Matsuyama

Add a Verifiable, Replayable Trail to Your Claude Code Sessions in 5 Minutes

Takashi Matsuyama — Tue, 14 Jul 2026 02:15:39 +0000

Claude Code is already keeping a diary in your repos. It just keeps it as a pile of vendor logs you will never read back — not readable, not verifiable, and nowhere near your code.

Five minutes from now, that changes. You won't change anything about your workflow. And your past sessions are included — retroactively.

What you'll have in five minutes

A .basou/ directory next to your code, holding:

handoff.md, for humans — where things stand, what happened, where to pick up
per-session events.jsonl files under .basou/sessions/, the source of truth — append-only, hash-chained event logs
and basou verify, a machine answer to the question "has this record been tampered with?"

The full picture of basou is in the introduction post. In one line: it's a local-first harness — a full set of tack — for AI coding agents: a saddle (a declarative workspace), reins (orientation that carries intent), and, underneath both, a replayable record of what the agent actually did. Today is hands-on with that bottom layer only: the trail.

Prerequisites and Step 1: install and init (30 seconds)

Three prerequisites: Node.js 20.10.0 or later, Claude Code, and a real repository you've been using Claude Code in.

npm install -g @basou/cli
cd path/to/your-repo
basou init

This article is written against basou v0.34.0 (as of 2026-07-14).

One thing to know up front: what ends up in git. By default, basou keeps the noisy parts out of git — the raw event log, internal logs, and the live orientation view — and leaves the durable summaries trackable: the manifest, handoff.md, decisions.md, and each session's session.yaml, so you can review them in a PR. Those summaries carry real work content — session labels, decision titles, the handoff text itself — so if you'd rather commit nothing at all, run basou init --local-only and the whole .basou/ directory stays gitignored.

Step 2: import what's already there — `basou import`

This is the moment the title promised.

basou import claude-code --all

Imported sessions: 20 path(s) sanitized
Imported 4 session(s) (101 events)

One command, and four Claude Code sessions I had run in this repository — 101 events' worth — became a trail, retroactively. --all just means "everything you can find for this repo"; there is no path to point at and no config to write — basou auto-detects the native logs on disk. If you'd rather look before you leap, add --dry-run first: it writes nothing and returns a preview — Dry run: would import ….

The finer points and the usual gotchas are in the quickstart. The one thing to take away here: you changed nothing about your workflow, and your history became a trail anyway.

Step 3: generate the handoff, read it back — and what "replayable" means

What the import wrote is the record: append-only, hash-chained JSONL under .basou/sessions/. The human view of it is something you ask for:

basou handoff generate

# Handoff

> Generated at 2026-07-13T16:31:18.106Z from ses_01KXE534X7..ses_01KXE534XZ

## Current state

- Last session: claude-code 2026-06-14: 23 commands, 3 files (imported) [ses_01KXE534X7]

## Latest decision

- ████████ の AGENTS.md 文書そのもの（散文本文）の言語をどう改定しますか？ … -> 本文は日本語のまま維持 [decision_01KXE534X0]

(3 decisions total — see decisions.md)

(The Japanese line under Latest decision is my data — a decision title — and basou keeps user data verbatim; this is a real workspace of mine, not a staged demo. The view chrome itself defaults to English; declare language: ja on the anchor repo in the manifest and the headings render in Japanese.)

This is an excerpt of .basou/handoff.md — where things stand, what happened last, where to pick up. Point a teammate at it. Point tomorrow's you at it. Point the next agent session at it.

Now, the part that earns the word replayable in the title. The Markdown you just read is not the record — it's a view, derived from the record. Which means it's disposable. Let's prove it. I could rm it, but I'll move it aside so we can diff afterwards:

mv .basou/handoff.md /tmp/before.md
basou handoff generate
diff /tmp/before.md .basou/handoff.md

4c4
< > Generated at 2026-07-13T16:31:18.106Z from ses_01KXE534X7..ses_01KXE534XZ
---
> > Generated at 2026-07-13T16:32:02.596Z from ses_01KXE534X7..ses_01KXE534XZ

One line moved: the generation timestamp. Everything else came back byte-identical — re-derived from events.jsonl, deterministically, offline, with no LLM involved. Same command, same view, resurrected from the source of truth.

That's what replayable means here. There is no step-through player — there is a source log you can re-consume at any time, and every human-readable view can be rebuilt from it. The handoff, the decision log, the orientation — each is a cheap projection of one verifiable log. Hand-edit the views if you like; when you want the log's version back, regenerate it.

Step 4: verify — and what "verifiable" means

Peek into a session's events.jsonl and you'll see each event holding the hash of the one before it:

{"schema_version":"0.1.0","id":"evt_01KXE534X7…","session_id":"ses_01KXE534X7…","occurred_at":"2026-06-14T06:10:20.317Z","source":"claude-code-import","type":"session_started","prev_hash":"12d50f19…2f70014"}
{"schema_version":"0.1.0","id":"evt_01KXE534X7…","session_id":"ses_01KXE534X7…","occurred_at":"2026-06-14T06:10:25.021Z","source":"claude-code-import","type":"command_executed","command":"bash", … ,"prev_hash":"793df9dd…330ac00"}

Which is why a machine can answer the question: "has this record been tampered with since it was written?"

basou verify

ses_01KXE534X7…  verified (34 events)
ses_01KXE534XJ…  verified (19 events)
ses_01KXE534XV…  verified (45 events)
ses_01KXE534XZ…  verified (3 events)
Sessions: 4 total — 4 verified, 0 unchained, 0 empty, 0 incomplete, 0 in_progress, 0 tampered

The shape you want is that summary line ending in 0 tampered. If even one session had been altered, it would show up as TAMPERED (...) and the exit code would be 1 — which means you can put this in a script. And note that the chain has been intact since the moment the import wrote it. There is no blessing step afterwards.

The trail format itself is vendor-neutral — an adapter reads each tool's native logs, and from there everything lands in the same shape under a common schema. And as you just saw, verification is a local operation against the .basou/ on your disk.

The sessions ahead

Everything so far was about the past. The future is even easier.

Start the morning with basou orient — "where was I?" answered from the record. Day to day, basou refresh is the one-shot that ingests new sessions and refreshes every view. When a design decision lands, basou decision capture; before you step away, basou note "pick up here next". And if you want a session recorded live from the start, basou run claude-code wraps the whole process.

If you use Codex: basou import codex --all — same shape, same kind of chain.

What this is not

Not a dashboard SaaS. Nothing leaves your machine. No LLM calls at runtime. The trail itself lives entirely inside .basou/, and walking away is as easy as deleting that one directory. If you want to browse locally, there's basou view (bound to 127.0.0.1 only) — that too is optional.

Wrapping up

That was the five minutes: install and init, one import, handoff generate, verify. From here the trail keeps growing next to your code, views can be deleted and resurrected from the source of truth, and tampering gets caught by a machine.

The quickstart and the CLI reference have the rest. If something snags on 0.x, issues are welcome.

Ending the CLAUDE.md / AGENTS.md / copilot-instructions.md Sprawl — Declare One Source, Verify the Wiring

Takashi Matsuyama — Sat, 11 Jul 2026 14:25:57 +0000

Open a repository these days and you'll find several nearly identical agent-instruction files sitting side by side — CLAUDE.md, AGENTS.md, .github/copilot-instructions.md. This post is about ending that sprawl not by hand-syncing it forever, but with declaration and verification. Last time I introduced the harness itself, basou. This one is about a smaller, duller problem that sits just upstream of it — and that far more people are quietly stepping on.

"Yet another instruction file"

Over the past year or two, every AI coding tool has brought its own "agent-instruction file." The project's rules, coding conventions, the things not to do. A file meant to be read by the agent, separate from the human-facing README.

The trouble is that each tool uses a different filename. Claude Code reads CLAUDE.md, Codex reads AGENTS.md, GitHub Copilot reads .github/copilot-instructions.md. Use more than one of these tools on the same team and you end up with three copies of the same content in the repo.

And they rot in silence. You fix one and leave the other a version behind. You think you've told the agent "here are the rules," while a different tool is reading the previous generation's rules. Worse, you can't tell by eye which copy is current and which has gone stale.

The scope of this post is a single repository, for an individual or a small team. Not company-wide policy distribution — just the everyday problem of "instruction files keep multiplying in my repo," dealt with in a realistic number of moves.

Why you can't just merge them into one

The naive thought is "just standardize on one AGENTS.md." And in fact, AGENTS.md is becoming the de facto common format. Designed as a "README for agents," it's an open spec that, as of mid-2026, is stewarded by the Agentic AI Foundation (under the Linux Foundation), read by more than twenty tools, and adopted in over 60,000 open-source repositories. Codex CLI, Cursor, Windsurf, Aider, Zed — most of the field has converged on AGENTS.md, and even GitHub Copilot's coding agent now reads it. Google's newer entrants (Jules and friends) do too.

The one that didn't converge is Claude Code. What Claude Code reads is CLAUDE.md, not AGENTS.md. It doesn't even read AGENTS.md as a fallback (the claim that "it reads AGENTS.md if CLAUDE.md is absent" is wrong). Start Claude Code in a repo that has only AGENTS.md and you'll get no error — it just runs, cheerfully, with zero project instructions loaded. That's the quietest place for a "unified" team to break. The request to "please support AGENTS.md" has gathered thousands of reactions on anthropics/claude-code issue #6235, but as of July 2026 the official docs show no sign of it on the roadmap.

Laid out, the matrix looks like this (as of July 2026).

Tool	Instruction file it reads
Claude Code	`CLAUDE.md` (does not read `AGENTS.md`)
Codex CLI	`AGENTS.md`
GitHub Copilot	`.github/copilot-instructions.md` (the coding agent also reads `AGENTS.md`)
Cursor	`AGENTS.md` (`.cursor/rules` is a separate, current mechanism; the old `.cursorrules` is deprecated)

As long as you use Claude Code, you can't delete CLAUDE.md. Standardize on AGENTS.md and you're still left maintaining a second file just for Claude Code. That one asymmetry is what keeps "just merge it into one file" from ever quite working.

Naive solutions, and where they run out

Copy-paste into all of them

The most naive move is to copy the same body into each file. It works the first time. It falls apart from the second time onward: every one-line rule change now obliges you to edit N files, and a human will always forget one of them. And, as above, you can't see which copy has rotted. The cost of syncing, and the inability to detect rot — those two are the intrinsic limits of copy-paste.

Consolidate into one file and reference it via import

Claude Code has an @path import syntax. Write @AGENTS.md as the first line of CLAUDE.md and, at startup, the contents of AGENTS.md are expanded inline and read as-is.

<!-- CLAUDE.md -->
@AGENTS.md

This is a clean instinct. The real body lives in a single place — AGENTS.md — and CLAUDE.md is just a one-line stub. Import also lets you add tool-specific instructions on top of the shared body — if there's a rule you only want Claude Code to follow, put it from line two of the stub onward. It has limits, though. The import syntax isn't common across tools (the same trick doesn't work in Copilot's .github/copilot-instructions.md). And since both files can still carry a body, the moment the "keep the stub to one line" discipline slips, the drift is back.

For what it's worth, running Claude Code's /init in a repo that has an AGENTS.md will read the existing AGENTS.md and incorporate the relevant parts into the generated CLAUDE.md — but that's a copy, not a reference. If consolidation is the goal, writing the one import line by hand is the cleaner move.

Bundle into one real file with a symlink

The more direct option is to make "there is only one real file" true at the filesystem level. Make CLAUDE.md a symlink to AGENTS.md, and when Claude Code opens CLAUDE.md, the OS transparently returns the contents of AGENTS.md. The tool never has to know about the symlink. The worry that "it won't follow the symlink" is, at least for reads, unfounded: the tool does the opening, but the OS does the following. In fact, Claude Code's own official documentation lists ln -s AGENTS.md CLAUDE.md as an option.

For a single repository, this is the sturdiest choice. Here's the actual procedure.

In practice — bundling to one canonical with symlinks

Topology

Make AGENTS.md the canonical (the hub) and let the other files be spokes pointing at it.

myrepo/AGENTS.md                          # canonical (the real file — edit only this)
myrepo/CLAUDE.md                          -> AGENTS.md
myrepo/.github/copilot-instructions.md    -> ../AGENTS.md

The reason to make AGENTS.md the canonical is that it's the format the most tools read out of the box. If Claude Code ever supports AGENTS.md, you just drop one spoke.

Commands

# If the body currently lives in CLAUDE.md, move the real file to AGENTS.md first
git mv CLAUDE.md AGENTS.md

# Make CLAUDE.md a symlink to AGENTS.md
ln -s AGENTS.md CLAUDE.md

# For Copilot (mind the relative path as seen from inside .github/)
mkdir -p .github
ln -s ../AGENTS.md .github/copilot-instructions.md

Making the paths relative is the trick. Clone the repo anywhere and the links resolve entirely within the repo, so they don't break.

How Git handles it

Git records a symlink plainly, as a "blob of mode 120000 whose content is the link target path." So symlinks commit as-is and are restored on clone.

$ git ls-files -s AGENTS.md CLAUDE.md .github/copilot-instructions.md
120000 …  .github/copilot-instructions.md  # symlink
100644 …  AGENTS.md                        # real file
120000 …  CLAUDE.md                        # symlink

The caveat is Windows. Checking symlinks out correctly requires core.symlinks=true plus developer mode or the right privileges. Without that, a symlink is expanded as a plain text file whose content is the link target path. A team with Windows in the mix should just confirm this point up front. (As a general note — I run macOS myself.)

Where this approach runs out

Symlinks are enough within a single repo, but three problems surface as the scope widens.

Public repos and private contents. If the instruction file contains non-public planning information, putting the real file in a public repo's history exposes that content directly. A symlink keeps the contents out, but the link target path — the directory layout on the private side — still lands in the history.
Wanting one canonical across several repos. The more repos you have, the more hand-linking breaks down as a practice.
The wiring rots in silence. A link goes missing, breaks, or points somewhere else — and you can't track that by eye. You've reintroduced instruction-file rot, this time at the symlink layer.

In short, symlinks solve "bundle to one real file," but not "declare" and "verify." You're still linking by hand and checking by hand, forever.

Going further — declare the canonical, verify the wiring

Everything so far stayed inside one repository. From here we step just past the scope I drew in the first section — to when repos multiply and public and private start to mix. The idea is this:

Declare one canonical, generate the wiring to each tool, and verify that wiring.

That three-beat rhythm needs no dedicated tool. Write the canonical's location once (declare), lay the links with a few lines of script (generate), and drop a few lines in CI that diff the expected output of git ls-files -s (verify) — and the shape holds. What separates it from linking by hand is that "the wiring as it should be" exists as code rather than prose, and a machine tells you when it breaks.

What I actually use is this same idea realized in basou. basou is a harness for steering AI coding agents, and one of its features treats the wiring of agent-instruction files declaratively. What follows describes v0.32.0.

Declare

You declare each repository and its attributes (visibility — public or private, language, and so on) in a manifest. The canonical body lives in exactly one place, on a private "anchor" — the repo that aggregates the canonicals (agents/<repo>/AGENTS.md). Each repo's instruction file is treated as wiring pointing there.

The topology is the same hub-and-spoke as before, except the hub points at the anchor's canonical.

<repo>/AGENTS.md                          -> <anchor>/agents/<repo>/AGENTS.md   # hub -> canonical
<repo>/CLAUDE.md                          -> AGENTS.md                          # spoke -> hub
<repo>/.github/copilot-instructions.md    -> ../AGENTS.md                       # spoke -> hub

The canonical is the single file on the anchor side. Each repo's AGENTS.md becomes a gitignored symlink pointing to it. So the canonical (which may contain non-public planning information) is edited exactly once, every tool reads it through the symlink, and it never enters a public repo's history.

Generate

Don't lay the wiring by hand — generate it.

basou project derive    # generate the full wiring from the declaration (dry-run by default; --apply writes)

derive builds, in dependency order, each repo's symlinks, the canonical's boilerplate block, the .gitignore that keeps a public repo clean, and the workspace view that bundles several repos (there are also symlinks / preset / gitignore / workspace to run individually). All of it is non-destructive. It creates only what's missing (preset updates only its own generated block and never touches your hand-written body), it won't overwrite an existing file or repoint a symlink that points elsewhere, and it reports conflicts as conflicts and leaves them to a human. There's also a retrofit for pulling an existing hand-written AGENTS.md into this topology.

Verify

And then, verify the wiring. This is the piece that was missing from the hand-run symlink approach.

$ basou project check     # surface drift between the declaration and the actual wiring (read-only)
✅ Every present repo's and the view's instruction files (AGENTS.md + spokes) are wired as declared.

$ basou project wiring    # inspect the wiring and privacy risk (read-only)
✅ No instruction file is tracked by git in a public-facing repo (no privacy risk).

check reports drift like "the canonical is missing," "a spoke is absent," or "there's a conflict." wiring goes further and surfaces privacy risk — a state where a public repo tracks an instruction file in git and could expose the contents of a private canonical in public history. What the eye couldn't track comes out as a verdict from a single command.

The output above isn't a staged sample. It's the real thing (excerpted), run just now against the repository of the blog you're reading. And this blog's symlinks were laid by hand, following the procedure in the "In practice" section — not through basou's wiring feature. Add the manifest declaration after the fact and run check, and it finds nothing to fix — the hand-laid wiring passes the reconciliation against the declaration as-is. The "In practice" and "Going further" sections aren't an either/or; they converge on the same shape. Start by hand, and nothing is wasted.

The exception — a self-contained private repo

You don't always converge on the anchor with hub-and-spoke. The very blog repo I've been using as the example is private, and it keeps AGENTS.md as a real file and commits it, symlinks and all — the git ls-files output shown in the "In practice" section is, in fact, from this very repository. Its manifest declaration is, in reality, just these three lines.

repos:
  - path: .
    visibility: private
    language: ja

Being private, it has no leakage risk, so rather than aggregating the canonical onto an outside anchor, it's more natural to keep the instruction docs' editing and diffs entirely inside the repo — the single-repo shape, where the repo is its own anchor. In basou you can declare a repo that "commits its instruction files by design" as instructions: self, and a declared repo isn't flagged as a privacy risk even though it tracks instruction files.

Where self really earns its keep is on public repos — an OSS project that deliberately commits AGENTS.md for contributors to read. A private repo doesn't need it: it passes on the strength of its visibility alone (that's what the wiring output above shows). So a public repo hides its canonical and wires to it, while a repo that's fine being self-contained commits the canonical outright — being able to declare even that distinction is the difference from hand-running.

An honest positioning

Let me put the exit up front. If you're on a single repository and don't need per-tool differences, stopping at the symlink from the "In practice" section is fine. This blog itself is still in exactly that shape. Conversely, once you want to add agent-specific instructions, that's the domain of the import from the earlier section — full symlink unification (and basou's wiring too) has no answer for it.

And, to be clear: basou is my own harness, still at a single-author dogfooding stage. What I want to recommend here isn't a product but the shift in framing — from "hand-sync N files" to "declare one canonical, and have the wiring generated and verified." Laying symlinks by hand already gets you half of it today, and verification can start from a few lines in CI. basou is just one example of putting that three-beat rhythm onto a single manifest. What basou itself is, I'll leave to the previous post.

In summary

Each AI coding tool uses a different instruction filename (CLAUDE.md / AGENTS.md / copilot-instructions.md). AGENTS.md is converging toward a de facto standard, but because Claude Code reads only the CLAUDE.md family, never AGENTS.md, you can't collapse everything into one file.
The first hands-on move is the symlink. Make AGENTS.md the canonical and turn CLAUDE.md and friends into symlinks to it: the real file becomes one, and tools read it transparently. Git carries it plainly as a 120000 blob (only Windows needs care).
Symlinks solve "bundle to one real file," but not the mix of public and private, multiple repos, or wiring rot. From there, move onto the three-beat rhythm of declare (one canonical), generate (the wiring), and verify (drift and privacy risk) — and you can start from a few lines of CI, no dedicated tool required.
Take the management of instruction files themselves from hand-syncing to human declaration plus tool generation and verification. The wiring of instruction files is one more rein a human should hold. The scarce resource, again, is control.

The Japanese version of this post — its "paired" article — is already live.

When AI Agents Write the Code, What's Missing Are the Reins — Introducing basou

Takashi Matsuyama — Thu, 09 Jul 2026 02:00:39 +0000

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.

The project is basou. 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/ directory right next to your code. Local-first: nothing leaves your machine.

Code only captures the what

Once 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.

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.

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.

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.

basou 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.

Two foundations — the saddle and the reins

🐎 The saddle: a declarative workspace

You 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) lives — in a manifest. Then basou project derives the rest: which roots to record, the wiring of AGENTS.md / CLAUDE.md / Copilot instruction files, the .gitignore that 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.

Every generating command is dry-run by default (--apply is 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.

🪢 The reins: orientation that carries intent

basou orient answers "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.

The 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 makes 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.

basou note leaves a one-line "pick up here next." basou handoff generate regenerates a handoff document for the next session — or the next teammate.

Underneath: a replayable provenance trail

The two foundations sit on a simple, inspectable base.

The source of truth is JSONL. Observed events — commands run, files changed, decisions, approvals — are appended to .basou/sessions/<session_id>/events.jsonl and linked in a hash chain. Tampering is detectable with basou verify.
Humans read Markdown. .basou/handoff.md and .basou/decisions.md are regenerated from the event log (you can hand-edit them too). Review them in an editor, or right in a PR diff.
Ingestion doesn't depend on any vendor's internal format. basou run claude-code wraps a process from the outside and records it; basou import claude-code / basou import codex derive sessions after the fact from the logs each tool leaves behind. basou refresh does ingestion and Markdown regeneration in one pass, and basou view shows 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.

The real thing — this blog's own records

I 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/ (some paths and identifiers are masked; the Japanese working notes are translated here for readability).

First, the current position basou orient returned when I resumed work. Behind it, handoff.md holds the same content.

# Handoff

> Generated at 2026-07-08T13:20:50Z from ses_01KVZAFJT0..ses_01KX0Y6TPT

## Current state

- Last session: claude-code 2026-07-07: 110 commands, 11 files (imported) [ses_01KX0Y6TPR]
- Last task: (no tasks recorded yet)

## Recently changed files

- src/components/MermaidRenderer.astro
- src/layouts/BaseLayout.astro
- src/pages/ja/index.astro
- …

## Recent decisions

- Use the existing static image for the shared header avatar [decision_01KWYHFVDE]

Next, one decision made during that work, recorded like this — with the reasoning and the road not taken.

## Render Mermaid diagrams as SVG on the client

- date: 2026-07-07
- rationale: Build-time rendering (rehype-mermaid and friends) depends on headless
  Chromium, which risks breaking Cloudflare's build pipeline. Instead, load mermaid.js
  in the browser and swap the Shiki-highlighted pre[data-language=mermaid] for SVG.
- alternatives: Pre-generate the SVG at build time (SSG) with a headless browser
- rejected_reason: Adding a headless-Chromium dependency to the build makes builds
  fragile; that operational risk outweighs the "no JS required" benefit.
- linked_files: src/components/MermaidRenderer.astro, src/styles/global.css

And beneath all of it, the event log and its verification.

{"schema_version":"0.1.0","session_id":"ses_01KW0J3F…","type":"session_started","prev_hash":"1e4d0428…e34dc37"}
{"schema_version":"0.1.0","session_id":"ses_01KW0J3F…","type":"session_status_changed","from":"initialized","to":"running","prev_hash":"e3108afa…efb2bc9"}
{"schema_version":"0.1.0","session_id":"ses_01KW0J3F…","type":"session_ended","exit_code":0,"prev_hash":"9d11ac73…b4b29f0e"}

$ basou verify
ses_01KW0J3F…  verified (5 events)

Markdown 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?"

Design promises

Local-first / zero-network. It reads the agent logs already on your machine and writes only to the .basou/ directory next to your code. Nothing leaves the machine.
Deterministic. No runtime LLM. It just writes down the structure the agent handed it, so the same input produces the same record.
Reversible. Everything stays inside .basou/, and generating commands are dry-run by default and non-destructive. Adopting it — or backing out — is low-risk.
The CLI surface is frozen even at 0.x. The on-disk format is versioned and ships with a JSON Schema. The format and semver guarantees land at 1.0, which is what I'm building toward.
Apache-2.0. A single author dogfooding it daily, aiming for a 1.0 that outside maintainers and teams can rely on.

Start in five minutes

# Node.js >= 20.10
npm install -g @basou/cli

cd /path/to/your/project
basou init

# Try a minimal record by hand
basou task new --title "Refactor login form"
basou note "Starting from a look at auth.ts"
basou handoff generate && cat .basou/handoff.md

# Or ingest in bulk from the agent logs already on disk
basou refresh
basou view   # local UI, 127.0.0.1 only

A walkthrough with sample output and the usual gotchas is at basou.dev/quickstart/.

One more thing: if basou is the side that records what an agent did, there's a companion project, Kozou, for the side that tells an agent what a database means. I'll introduce that one separately too.

In summary

In the age of coding agents, the scarce resource is control — staying in the saddle, driving every project the same way, and not losing the "why" between sessions.
basou is the harness for that: a saddle (a declarative workspace) and reins (orientation that carries intent), with a hash-chained, replayable trail underneath.
All of it as plain files next to your code. Local-first, zero-network, no runtime LLM. Adoption is low-risk, and you can always back out.

The repository is github.com/basou-dev/basou; the docs are at basou.dev. If something trips you up on 0.x, I'd be grateful for an issue.

The Japanese version of this post — its "paired" article — is already live.

Building a Bilingual Blog on Cloudflare Workers Static Assets — and Why I Skipped Pages

Takashi Matsuyama — Fri, 03 Jul 2026 08:00:19 +0000

🔗 This article is republished from https://blog.tak3.jp/en/blog/building-this-blog/ — the original source.

This blog (blog.tak3.jp) is a static Astro site served from Cloudflare Workers static assets, edited through Sveltia CMS, and published in two languages, Japanese and English. When a post goes live, it is automatically syndicated to DEV.to and, by design, to Qiita (a major Japanese developer platform) — either as a summary with a pointer back or in full, chosen per post. If you're reading this on DEV.to, this article reached you through the exact pipeline it describes. (Qiita is the honest exception right now: its API is blocking this account, so that side runs manually for the moment — more on that below.)

One more meta detail before we start: a Japanese edition of this post exists, and it is not a translation of this one. It's a pair — same subject, independently written article. That distinction is a deliberate design decision, and it's half of what this post is about. The other half is why I didn't use Cloudflare Pages.

This is a design write-up, not a tutorial. I'll focus on the decisions: skipping Pages, pairing languages with translationKey, draft safety in a setup where publishing has side effects, and running a Git-based CMS with no auth infrastructure at all.

Requirements and stack

What I wanted wasn't "a blog" but a publishing base with my own site as the single source of origin. Five requirements:

Publish in both Japanese and English
Keep all content in Git (history, no lock-in, editable from both an editor and a browser)
Push operating costs as close to zero as possible (serverless, free tiers)
Auto-syndicate published posts to external platforms (DEV.to / Qiita)
Be implementable by AI coding agents, with a spec document as the single source of truth

The resulting stack:

Area	Choice
SSG	Astro + TypeScript (Content Layer API)
Content	Markdown / MDX + YAML frontmatter
CMS	Sveltia CMS (Git-based, admin at `/admin/`)
Hosting	Cloudflare Workers static assets + a thin main Worker for language routing
Syndication	A separate Worker (Cron + D1 + KV)
RSS / sitemap	`@astrojs/rss` / `@astrojs/sitemap`

The whole system in one picture:

flowchart LR
  subgraph edit[Writing & editing]
    A[Editor / AI agents] --> G
    C[Sveltia CMS /admin/] --> G
  end
  G[(GitHub repo)] -->|push to main| B[Build: astro build → dist/]
  B -->|wrangler deploy| W[Cloudflare Workers<br>static assets + main Worker]
  W --> V[Readers<br>/ja/ and /en/]
  W -->|/feed.json| S[Syndication Worker<br>Cron + D1 + KV]
  S --> Q[Qiita]
  S --> D[DEV.to]

For the CMS I chose Sveltia over Decap (formerly Netlify CMS): it keeps Decap-compatible config while being a newer, lighter, actively developed implementation. I treat a Git-based CMS not as a WordPress replacement but as a UI for editing structured content that lives in Git.

Is Cloudflare Pages deprecated?

Facts first, because this question generates a lot of noise on Reddit and Hacker News. As of July 2026, there is no official end-of-life announcement for Pages. Existing projects are supported, and you can still create new ones.

The practical reality, though, is "not recommended for new projects." Cloudflare's docs ship an official Pages → Workers migration guide and state plainly that development focus is on Workers going forward, recommending Workers for anything new. Feature-wise, Workers now covers nearly everything Pages does, and adds things Pages never had — Durable Objects, Cron Triggers, richer observability. The remaining gaps in the official compatibility matrix are small (branch-build configurability, for one).

One clarification, because it fuels the confusion: the thing that is officially deprecated is Workers Sites — an older, entirely different feature that predates Pages — with a documented migration path to Workers static assets. A good share of the "Pages is deprecated" claims are actually about that.

So no, I didn't skip Pages "because it's deprecated." I skipped it for one defensive reason and two positive ones.

The defensive reason: adopting Pages for a brand-new project means signing up for a future migration on day one.

Positive reason #1: routing as code. This site has /ja/ and /en/ side by side, and no real page at the root /. Static hosting can't read a visitor's language — but a thin main Worker sitting in front of the static assets can handle exactly one path, /, and answer with a 302.

// wrangler.jsonc (excerpt)
{
  "name": "takashimatsuyama-blog",
  "compatibility_date": "2026-05-01",
  "main": "worker/index.ts",
  "assets": {
    "directory": "./dist",
    "binding": "ASSETS",
    "run_worker_first": ["/"] // only the root runs the Worker; everything else is served as-is
  }
}

Language negotiation is a three-step cascade: ① an explicit ?hl=ja|en query from the language switcher (recorded in a cookie), ② the cookie from a previous explicit choice (which outranks browser settings), ③ on first visit, Accept-Language — top preference en* goes to /en/, everything else defaults to /ja/, because this is a Japanese-primary site. The 302 carries Vary: Accept-Language and Cache-Control: private, no-store so the language decision never ends up in a shared cache.

// worker/index.ts (excerpt, simplified)
const isRootDocument =
  url.pathname === '/' && (request.method === 'GET' || request.method === 'HEAD');
// language pages, assets, 404s: straight to static assets
if (!isRootDocument) return env.ASSETS.fetch(request);

// 1. explicit switch → 2. cookie → 3. Accept-Language (default: ja)
const hl = url.searchParams.get('hl');
if (hl === 'ja' || hl === 'en') return redirectToLocale(url, hl, true);
const cookie = readCookie(request, LANG_COOKIE);
if (cookie === 'ja' || cookie === 'en') return redirectToLocale(url, cookie, false);
return redirectToLocale(url, preferredLocale(request.headers.get('Accept-Language')), true);

Positive reason #2: one deploy story. This repo also contains the syndication Worker (Cron / D1 / KV). Instead of maintaining a Pages project and a Workers project side by side, everything is wrangler deploy.

The trade-off, stated honestly: the build-and-preview experience Pages gave you for free becomes your problem. Here, a push to main triggers wrangler deploy, and previews are the URLs issued by wrangler versions upload.

Bilingual design: pairs, not translations

URLs use path prefixes, /ja/... and /en/..., and the hreflang x-default points to /ja/. Most i18n write-ups assume an English-primary site; this one is Japanese-primary, and I wanted zero ambiguity about what a visitor with an unknown language preference sees.

The decision that actually needed thought was how to hold the content collections:

	A: one collection per language	B: single collection + `lang` filter
Queries	call `getCollection('blog_ja')` etc. per language	one uniform query
CMS mapping	1:1 with CMS collections	language is pickable (and mis-pickable) in the UI
Failure mode	low	a forgotten `lang` filter fails silently

I went with A (blog_ja / blog_en / notes_ja / notes_en). The deciding factor: neither a human editor nor an AI agent should ever have to think about which language they're in. Each Sveltia collection maps 1:1 to an Astro collection, lang is a hidden fixed field in the CMS, and the entire class of "silently leaking the wrong language" bugs disappears.

The two languages are linked through a translationKey in the frontmatter:

// content.config.ts (excerpt, simplified)
const blogSchema = z.object({
  title: z.string(),
  pubDate: z.coerce.date(),
  lang: z.enum(['ja', 'en']),
  slug: z.string(),
  translationKey: z.string(),
  tags: z.array(z.string()).default([]),
  draft: z.boolean().default(false),
  syndication: z.record(z.string()).default({}),
});

const blog_en = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/content/blog_en' }),
  schema: blogSchema,
});

The important part: the slug is independent of the translationKey. The two editions of a post may have different slugs, different titles, different structure. What you build is not a translation but a pair — two articles on the same subject, each written for its audience. This very post demonstrates it: the Japanese edition opens differently, orders its arguments differently, and spends more words on the platforms Japanese readers syndicate to.

Since translationKey is typed by hand, a typo fails silently — the language-switch link just doesn't appear. That's fixed with a two-tier build check:

A translationKey that exists in only one language → warning ("not translated yet" is a normal state, so it must be allowed)
A duplicate translationKey within one language → error (that's always a typo)

You cannot mechanically distinguish "no pair yet" from "typo'd key." So route the possibly-legitimate case to a warning and the impossible case to an error.

Draft safety across every output path

Posts with draft: true are excluded from all of this:

Output path	Drafts
Home / lists / detail pages / tags	excluded
RSS / JSON Feed	excluded
sitemap	excluded
Language-switch links, related posts	excluded
External syndication (Worker)	excluded

On a plain static blog, a mis-published draft is fixed with a redeploy. Here, publishing has side effects: it triggers syndication to DEV.to and Qiita. Deleting the post from your own site doesn't recall what already left. So the CMS defaults new posts to draft: true, and the exclusion is enforced not just in HTML but in feeds, the sitemap, and the syndication Worker. Automated syndication and draft discipline only work as a set.

Sveltia CMS with a token — no OAuth proxy

The standard way to run a Git-based CMS against GitHub is to deploy an OAuth proxy for authentication. This site doesn't have one. There's a single editor (me) and a single target repo, and Sveltia offers "Sign in with Token": paste a GitHub fine-grained PAT and you're in.

# public/admin/config.yml (excerpt)
backend:
  name: github
  repo: your-account/your-blog-repo # point at your repo
  branch: main
publish_mode: simple
media_folder: public/images/uploads
public_folder: /images/uploads

The token is scoped down hard:

A fine-grained PAT restricted to this one repository
Contents: Read and write (plus the mandatory Metadata: Read) — nothing else
Expiring. With publish_mode: simple (direct commits to main), no PR permissions are needed

The honest risk assessment: the token lives in the browser's localStorage and goes straight to the GitHub API. You keep zero secrets on your own infrastructure, in exchange for operational rules — don't use shared machines, rotate on expiry. For a single-operator personal blog, removing an entire moving part (the OAuth proxy) is worth that trade.

The syndication pipeline, briefly

The reveal for the opening line. The site emits /feed.json (JSON Feed), where each item carries a _meta block for syndication: the GitHub sourcePath / gitRef / sha, the canonical URL, and the post's syndication settings. A separate Worker polls it on a Cron schedule, detects new posts, and publishes to whichever platforms are set to enabled — with an allowlist: only DEV.to and Qiita are ever posted to automatically; everything else stays manual. Each post chooses whether its syndicated copy is a summary with a pointer back or the full text (via the syndicationBodyMode frontmatter field); either way, the canonical URL stays on this blog. This post is syndicated in full.

One honest caveat: at publish time, Qiita's API returns 403 Forbidden for this account — not a scope or rate-limit problem, but an account-level block on creating items through the API (the same account posted fine a few days earlier). So Qiita is temporarily manual while DEV.to keeps running automatically. A post about automating syndication, tripped up by a real syndication limit — which felt worth stating plainly.

Duplicate protection is single-flight via a unique constraint in D1, and every adapter ran in dry-run mode (no real HTTP, no storage writes) before going live. Retries, rate limits, and partial-success handling deserve their own post, so that's where they'll go.

Gotchas

compatibility_date cannot be in the future. The moment the main Worker was added, deploys started failing runtime validation — because the wrangler config carried a compatibility date Cloudflare hadn't released yet. An assets-only config had accepted it silently.

A single collection for static pages collides. The glob loader uses the frontmatter slug as the entry id, so putting /ja/about and /en/about in one pages collection collides on the same slug. Pages got split per language too (pages_ja / pages_en).

Pin the CMS CDN version. Loading Sveltia from a latest CDN URL means the admin UI can change behavior whenever upstream ships. The script tag in /admin/index.html is version-pinned; upgrades happen on my schedule.

Takeaways

The value of Workers static assets is "static hosting where routing is code." You don't need "Pages is deprecated" as a reason — a thin Worker in front and a single deploy story are positive ones
Design bilingual content as pairs, not translations. Separating slug from translationKey, plus a warning/error split in validation, is the whole implementation
If publishing triggers syndication, draft discipline has to cover every output path, not just HTML. The automation and the discipline only exist together

This repo was implemented primarily by AI coding agents, working from a spec document as the single source of truth. That workflow — and the open-source harness for steering coding agents that I'm building — is a story for another post.

The Japanese pair of this article is already live on the /ja/ side of this blog.

About this blog

Takashi Matsuyama — Wed, 24 Jun 2026 23:00:34 +0000

Starting a personal media that records and shares all my work.

Read the full article 👉 https://blog.tak3.jp/en/blog/hello-blog/

DEV Community: Takashi Matsuyama

Add a Verifiable, Replayable Trail to Your Claude Code Sessions in 5 Minutes

What you'll have in five minutes

Prerequisites and Step 1: install and init (30 seconds)

Step 2: import what's already there — basou import

Step 3: generate the handoff, read it back — and what "replayable" means

Step 4: verify — and what "verifiable" means

The sessions ahead

What this is not

Wrapping up

Ending the CLAUDE.md / AGENTS.md / copilot-instructions.md Sprawl — Declare One Source, Verify the Wiring

"Yet another instruction file"

Why you can't just merge them into one

Naive solutions, and where they run out

Copy-paste into all of them

Consolidate into one file and reference it via import

Bundle into one real file with a symlink

In practice — bundling to one canonical with symlinks

Topology

Commands

How Git handles it

Where this approach runs out

Going further — declare the canonical, verify the wiring

Declare

Generate

Verify

The exception — a self-contained private repo

An honest positioning

In summary

When AI Agents Write the Code, What's Missing Are the Reins — Introducing basou

Code only captures the what

Two foundations — the saddle and the reins

🐎 The saddle: a declarative workspace

🪢 The reins: orientation that carries intent

Underneath: a replayable provenance trail

The real thing — this blog's own records

Design promises

Start in five minutes

In summary

Building a Bilingual Blog on Cloudflare Workers Static Assets — and Why I Skipped Pages

Requirements and stack

Is Cloudflare Pages deprecated?

Bilingual design: pairs, not translations

Draft safety across every output path

Sveltia CMS with a token — no OAuth proxy

The syndication pipeline, briefly

Gotchas

Takeaways

About this blog

Step 2: import what's already there — `basou import`