DEV Community: Takashi Matsuyama

It Owns the Merge, Not the Transport — basou's local-first, zero-network design

Takashi Matsuyama — Mon, 31 Aug 2026 04:10:51 +0000

Open ~/.claude/projects/ on your own machine.

What has accumulated there is the full text of every exchange you have had with an AI coding agent for months. Half-finished designs. Pasted stack traces. The directory layout of an internal repository. A requirements discussion with a customer's name in it. The query you re-pasted again and again because it kept failing. And somewhere in there, possibly, a credential you thought you had deleted.

An agent's transcripts are the most sensitive collection of files in a developer's environment. More sensitive than the source code, arguably. Source code records conclusions; a transcript records everything on the way there — the hesitation, the rejected option, the internal politics, the proper noun you said out loud.

basou, which I build, takes exactly those files as its raw material. It reads the agent's logs and turns them into a session trail and a record of decisions. Which means basou had to be designed as a tool that routinely reads the most sensitive files in a developer's environment.

What should a tool like that do with that data?

This post is the record of that design decision. Everything below is against basou v0.37.0 (released 2026-08-04). (v0.38.0 shipped on 2026-08-28 after this was written; the change is to the import event format and does not touch anything discussed here.)

I already made the claim. Today is what sits underneath it

The introduction post put it in a single bullet:

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.

As a claim, that is enough. But a bullet can only state the outcome. What follows is what happened after that was decided.

A constraint like this is easiest at the moment you declare it, and hard afterwards. The center of this post is what happened when a requirement arrived that seemed to need the network — spanning more than one machine — and how it was settled. There were two other decisions that touched the network, and those landed differently. I will come to them briefly, later.

One more thing: part of the bullet above is worded too strongly. I will fix that too.

Why not send it — not taking custody of other people's data

First, let me grant the case for sending it.

It is a trail tool. Of course it would be more useful on a server. Share it with the team. Search across machines. Build a dashboard. View it in a browser. None of that is hard to design. It is, in fact, the normal thing to do.

The problem is that the moment you own one upload path, you have taken custody of other people's data. Custody means making these promises:

How long do you keep it? If someone asks you to delete it, can you reach the copies inside your backups?
Transcripts can contain credentials. When one arrives with a credential inside, how do you handle it?
If there is a breach, whom do you notify? Not only the user — their employer's repository is in those transcripts too.
Which country holds the server? Are logs from work under contract or NDA allowed to sit there?

Parts of each of those have technical answers (credential scrubbing, for one), but the substance is an operational promise that comes with custody. And promises should only be made by people with the capacity to keep them.

There are middle options — with client-side encryption where only the user holds the key, you can offer sync from a server that only ever holds data it cannot read, which structurally removes the credential-exposure problem and greatly lightens breach notification (retention, deletion, and jurisdiction survive it). Even so: basou is a single-author OSS project, still pre-1.0. Saying it would take on those four would, I thought, have been dishonest. It is not the kind of thing you settle with "we'll do our best."

So it takes custody of nothing. That single point is where zero-network comes from. There was no prior ideological commitment to privacy, and this is not a "local is faster" argument. The amount of custody that could be honored was zero, so the structure was built to require none. That is all.

The responsibility did not vanish. It moved

I want to be precise here. Not taking custody does not make the responsibility disappear.

As you will see below, moving data between machines becomes the user's job. Not exposing the local UI's port is an operational condition on the user. If you use the feature that launches an arbitrary command, what that command does is on you.

What this design did was not erasure but a re-drawing of the boundary. It narrowed what the basou project directly carries, down to what it can carry. The remainder did not evaporate; it sits with the user and with the tools the user already chose. I will name where each piece went, later in this post.

This constraint is also not the kind that bends if the maintainer's capacity changes. basou's specification lists zero-network as a property of the design rather than of any release, and states that it is not expected to change across major versions.

The main case — it owns the merge, not the transport

The first requirement arrived quickly.

You write on a laptop, but the actual builds and tests run on a dev box you reach over Remote-SSH. That setup is common. In it, Claude Code runs on the remote side, which means the transcripts only ever exist on the remote side.

So what happens? You run basou orient — the command that tells you where you currently are — on the laptop, and you see half of what exists. Decisions made on the dev box are simply not there. For a trail tool, that is a problem.

The naive fix is to stand up a sync server and push from both ends. That builds precisely the path the previous section refused.

So give up? No. What happened instead was a re-drawing of the interface.

Define "another host's trail" as a local path

basou has a registry at ~/.basou/hosts.yaml. This is the whole of it:

# ~/.basou/hosts.yaml
version: 1
hosts:
  - label: devbox
    path: ~/mirrors/devbox/service-api   # repo root holding another host's .basou

What goes in path is a local path this machine can see normally. Whether that is an SSHFS mount, an rsync mirror, or a Syncthing target, basou does not care. If it reads as a directory, that is enough. (It must be absolute; a leading ~ is expanded. Give one entry a relative path and it is not just that entry that is dropped — the whole hosts.yaml is discarded and the run continues local-only, printing basou: ignoring ~/.basou/hosts.yaml (Host paths must be absolute (or start with '~').); showing local sessions only. to stderr, with exit code 0.)

The implementation comment (packages/cli/src/lib/hosts-config.ts) says it directly:

basou performs NO network I/O: the operator's own tooling (over the SSH they
already use) keeps these paths in sync.

The CHANGELOG puts it more briefly:

it owns the merge, not the transport

That sentence holds the core of the design.

Why was that sufficient? Break the feature down and it needs two things: transport and merge. And the transport usually already exists. If you SSH into the dev box, the route and the keys are already in your hands. Bringing basou's own transport alongside that means one more key to manage and one more path to review. Where the existing route has already been through an organization's approval, the difference is larger still.

The only thing that had to be newly owned was the merge.

What it actually looks like

I built two stores locally to check. One decision and one note on the local side; one decision and one note on devbox. Both excerpts below are trimmed, with omissions marked ….

Without hosts.yaml, you get what you would expect:

> Generated at 2026-08-31T02:02:46.019Z · sessions 2 · newest 8s ago · pending 0 · suspect 0
…
- Latest decision: Stream the CSV export instead of buffering it [decision_01M1ARVSEC] (just now)
…
✅ The capture is current. Last work: just now (manual note). No uncaptured native sessions.
…

Add the registry and it changes:

> Generated at 2026-08-31T02:02:46.204Z · sessions 4 · newest 8s ago · pending 0 · suspect 0
> hosts: local, devbox

## Where you are now

- Last session: Ad-hoc note: Run the migration against staging first (completed) [ses_01M1ARVT1H] @devbox
- Latest decision: Use a partial index rather than a full one [decision_01M1ARVSX2] (just now) @devbox
…
## Recent direction (last 5 sessions)

- Ad-hoc note: Run the migration against staging first (just now) @devbox
- Ad-hoc capture: 1 decision (just now) @devbox
  - Decisions: Use a partial index rather than a full one
- Ad-hoc note: Add an integration test for the export path (just now)
…
## Is this current

✅ The capture on this host (local) is current. Last work: just now (manual note). …
…
Note: the freshness verdict covers only this machine's local store. Missed work on other hosts cannot be assessed here (run `basou refresh` on each host to sync).

sessions 2 became sessions 4, and a > hosts: local, devbox line appeared in the header.

The part worth looking at is @devbox. Merged entries keep the host they came from. Merging normally destroys provenance; here it does not. Which machine a decision was made on is not information a trail is allowed to drop.

The same screen states its own limit

There is one more change in that output.

The last line went from The capture is current to The capture on this host (local) is current, and a note was added at the end: the freshness verdict covers only this machine's local store, and missed work on other hosts cannot be assessed here.

That is the direct cost of not owning the transport. Whether another host's mirror is current cannot be known without running the import on that host. If the mirror's contents are three days old, there is no way to tell from here.

What matters is that it does not paper over it. Quietly printing "probably current" was technically available. Instead, the shrinking of the verdict's scope was written on the screen.

The feature's reach is also not uniform yet. The merge applies on the basou orient path, and the orientation.md that path writes carries the host attribution too. Handoff, decisions, basou view, and the orientation.md that basou refresh regenerates are local-only as of v0.37.0.

One disclosure: this feature appears in neither the README nor docs/spec/. The only descriptions are CHANGELOG 0.16.0 (2026-06-23) and the implementation, which is what this post is written from. There is currently nowhere to turn if you set it up and get stuck.

The rule that came out of it

Generalized:

When a requirement seems to need the network, the options are not only "add the network" and "give up." The third is to re-draw the interface and hand the transport to something the user already has. But whatever you hand off, you can no longer vouch for its freshness — which brings an obligation to print the degradation on the screen.

Read "multi-host support" as "a sync feature" and you are down to two options. Read it as "a merge feature" and the third appears.

The same judgment, in two other places

Two other decisions touched the network. Neither was settled the way the first one was. One was deferred; the other was accepted with conditions. Calling all three "solved" would be a lie, so let me mark the difference.

Deferral — fix the schema, don't build the endpoint

Put a human approval step in front of an agent's actions and the obvious follow-up is wanting to approve while away from your desk. The specification (docs/spec/overview.md) says:

Remote approval is a core capability: the schema is fixed and a local CLI provides the minimal implementation. Remote endpoints are out of scope.

So the original requirement is not met. There is no way to approve from your phone. What exists is that the approval events have a fixed schema. The events that record an approval or a rejection have a dedicated field for what resolved them, and the only value that goes in it today is the local CLI (local-cli). The requesting event uses the generic "where did this come from" field shared by all events, which carries the agent-side adapter name (claude-code-adapter).

Those fields are plain strings; nothing is reserved for a remote future. Still, having the shape settled first means that when a remote resolver does appear, it writes into the same record. Less that a vessel was built than that the migration pressure was lowered. That is the single thing that separates deferral from procrastination: settling the data's shape needs no network.

Bounded acceptance — one socket

This one starts with an admission.

basou opens a socket. basou view is a local web UI, and it stands up an HTTP server. This is not an instance of "no network was added." It is a choice to add a loopback listener and still own no outbound path.

So the definition has to be exact. Zero-network here does not mean "opens no socket"; it means "owns no path out." That is not the same as saying nothing can leak from the receiving side — reach it and get a response back, and it has leaked. So the one socket that is open is defended on that assumption (packages/cli/src/lib/view-server.ts):

// :108 — default bind
  const { port, host = "127.0.0.1", deps } = opts;

// :664-667 — Host header check, on every request
function hostAllowed(req: IncomingMessage, port: number): boolean {
  const host = req.headers.host;
  return host === `127.0.0.1:${port}` || host === `localhost:${port}`;
}

// :669-673 — Origin check, on POST only; an absent Origin is allowed
function originAllowed(req: IncomingMessage, port: number): boolean {
  const origin = req.headers.origin;
  if (origin === undefined) return true; // non-browser client (curl, tests)
  return origin === `http://127.0.0.1:${port}` || origin === `http://localhost:${port}`;
}

The reason it does not stop at the bind is that binding 127.0.0.1 still leaves the route through the user's own browser. Get them to open a page, rebind DNS so the attacker's domain resolves to 127.0.0.1, and as far as the browser is concerned it is same-origin with the server on your machine (DNS rebinding). The Host header carries the attacker's domain at that point, so checking it rejects the request.

The specification (docs/spec/cli-commands.md) is blunt about the limit: the server stays localhost-only and unauthenticated — do not expose the port. Put it behind a reverse proxy and the checks above will not save you: they exist to stop browser-mediated access, and a client calling directly can forge Host and simply omit Origin.

Holding one honest exception, together with its conditions, makes the whole claim easier to check. "It opens no sockets at all" would be a cleaner line, and a false one. Mix one falsehood into a claim and the moment a reader tries to verify it, all of it becomes suspect.

Where it actually writes

Now the correction I promised.

In the introduction post I wrote that basou "writes only to the .basou/ directory next to your code." That was too strong. The same bullet list two lines down says "Everything stays inside .basou/," which overstates it in the same way.

As the storage location of the trail itself, .basou/ is right. But the set of files the CLI as a whole may write is wider.

.basou/ — the trail itself.
The workspace's .gitignore — basou init appends the lines that keep raw logs out of history.
The agent's own config files, by default — this one needs care. A plain basou refresh updates the orientation block in ~/.codex/AGENTS.md every time, and basou run codex does the same immediately before spawning. That is default behavior, not an option (best-effort, though: if ~/.codex/ does not exist it does not create the directory and skips — refresh says so with codex channel skipped: …, while the pre-spawn path stays silent). basou protocol sync writes a marker block into ~/.claude/CLAUDE.md; basou hook install registers a Stop hook in ~/.claude/settings.json. Each keeps a one-time <target>.basou-bak.
Wiring in declared repositories — with --apply, basou project generators write a .gitignore and the AGENTS.md / CLAUDE.md / .github/copilot-instructions.md symlinks into the target repository (these generators are dry-run by default). The aggregated workspace view is created outside the repository by default — as a sibling directory. --prune deletes view symlinks independently of --apply.
Any path the user names — basou report generate --out <path>, for instance.

Conversely, basou never writes the configuration under ~/.basou/ (hosts.yaml, portfolio.yaml, protocols.yaml). It only reads it.

basou's own specification is accurate about where the trail lives:

the workspace trail lives under .basou/ next to your code; optional integrations may also write user-level files (~/.claude/, ~/.codex/). Everything stays on-machine — nothing is sent off-machine.

That is an invariant about the trail and optional integrations, not an inventory of everything the CLI emits. The introduction post read that sentence as the whole picture and then added "only" on top of it. "Nothing leaves the machine" was right — in the sense that basou itself sends nothing (a command you hand to basou exec going out is a separate matter, covered below). What was inaccurate was the scope of where it writes.

How to check any of this

So far this has been design. What is actually worth something to a reader, I think, is whether you can check it yourself. Every number below is as of v0.37.0.

Start with the dependencies. Do it somewhere empty, so you do not dirty a working directory:

mkdir /tmp/basou-audit && cd /tmp/basou-audit && npm init -y
npm install --omit=dev @basou/cli@0.37.0

The production transitive closure is 13 packages (npm counts the root and prints audited 14); two of those are basou's own, so 11 are third-party. ulid, yaml, zod, and commander have no dependencies; simple-git brings five directly, and its debug brings ms. There is no HTTP client in there.

Run it with outbound traffic denied

There is a faster check than reading dependencies: run it in an environment where outbound traffic is forbidden. On macOS that is one profile handed to sandbox-exec.

; deny-out.sb
(version 1)
(allow default)
(deny network-outbound)

Denying only the outbound direction is the point. A profile that forbids network operations wholesale ((deny network*)) also stops inbound, bind, and Unix domain sockets, which makes it impossible to tell what caused a failure. Direction is the thing under test here, so the block is drawn by direction.

Save the profile as deny-out.sb in that same /tmp/basou-audit, and run the following from there. Confirm first that the block is real — skip this and nothing that follows proves anything. Use a peer you stand up yourself; point it at a third party and a reader cannot tell a block from a dead host.

# a listener, outside the sandbox
node -e "require('net').createServer().listen(48080,'127.0.0.1',()=>console.log('listening'))" &
sleep 1

# connect from the plain environment — this is the baseline
node -e "require('net').connect(48080,'127.0.0.1')
  .on('connect', function () { console.log('connected'); this.end() })
  .on('error', e => console.log('blocked:', e.code))"

# connect to the same peer, from inside the sandbox
sandbox-exec -f "$PWD/deny-out.sb" \
  node -e "require('net').connect(48080,'127.0.0.1')
    .on('connect', function () { console.log('connected'); this.end() })
    .on('error', e => console.log('blocked:', e.code))"

kill %1

listening
connected
blocked: EPERM

The same peer: reachable from outside, EPERM from inside. That is outbound being blocked. Child processes inherit it, so a route like basou exec curl … cannot get out from inside either.

Now run basou against a repository that has a .basou/. Pass -f as an absolute path (the profile stays in the audit directory), and call the binary by path — npm install was a local install, so basou is not on your PATH.

AUDIT=/tmp/basou-audit
cd /path/to/your/repo

sandbox-exec -f $AUDIT/deny-out.sb $AUDIT/node_modules/.bin/basou orient
sandbox-exec -f $AUDIT/deny-out.sb $AUDIT/node_modules/.bin/basou refresh
sandbox-exec -f $AUDIT/deny-out.sb $AUDIT/node_modules/.bin/basou view

All three go through. orient and refresh exit 0; view starts (it is a server, so it does not exit — Ctrl-C when you have seen it).

basou view running at http://127.0.0.1:4319
Localhost only, no authentication. Do not expose this port beyond your machine. Press Ctrl+C to stop.

Note the second line. The operational condition quoted from the specification earlier — localhost only, unauthenticated, do not expose the port — is printed by the tool itself on every start.

Blocking outbound breaks nothing, and the loopback listener comes up normally. Both halves of the shape described earlier — no path out, one socket open for the local UI — show up at once.

What this experiment does not show

This needs stating precisely. What those three lines let you claim is narrower than it looks.

The import did not run here. Look at what refresh printed:

claude-code: skipped (no source logs for this project)
codex: skipped (no source logs for this project)
handoff: regenerated (sessions: 2, decisions: 1)
decisions: regenerated (1)
orientation: regenerated (in-flight: 0, pending approvals: 0, suspect: 0)
…

In a repository with no agent logs, the importers pass straight through. What actually ran was Markdown regeneration. The merge is the same story: without ~/.basou/hosts.yaml, the federation path is never entered. Checking import and merge under the same conditions needs a repository with real logs and a registry pointing at a second store.

It also only ran three commands. basou --help lists 25 commands (one of them is help itself, so 24 real ones). If a branch that only executes under some other command reaches out, this check does not see it.

And it only observes success. An implementation that sends, swallows the failure, and carries on would sail through an outbound-blocked environment. This check shows that basou does not depend on outbound traffic succeeding — not that it sends nothing.

Back it with a static scan

So look at the code as well. The question here is whether the tools for connecting outward are in the bundle at all.

grep -rlE "(from|require\()[[:space:]]*['\"](node:)?(http|https|http2|net|tls|dgram|dns)['\"]|\bfetch\(|WebSocket|XMLHttpRequest" \
  node_modules --include='*.js' --include='*.cjs' --include='*.mjs'

It catches both node:-prefixed and bare specifiers, and both static import and require. Bundler output is not consistent, so an expression that only looks for one form misses easily. I got this wrong three times while writing this post — an expression that ignored bare specifiers, one that only looked at require, and one that missed the from "http" form. Offered here as material for re-deriving what follows.

Two files match, both from basou's own bundle. Swap -l for -n and you see what matched:

node_modules/@basou/cli/dist/index.js:10902:import { createServer } from "http";
node_modules/@basou/cli/dist/index.js:11076:    return fetch(path, opts).then(function (res) {
node_modules/@basou/cli/dist/program.js:10902:import { createServer } from "http";
node_modules/@basou/cli/dist/program.js:11076:    return fetch(path, opts).then(function (res) {

Four lines, two distinct things (index.js and program.js are separate entry points into the same bundle, so each line appears twice). The only network builtin this expression found is http, and what it takes from it is { createServer }. The fetch( is inside a browser-side JS string. Within the reach of this scan, the tool for building a server is present and the tool for connecting out as a client is not.

Worth checking what a static expression cannot reach, too: the bundle contains one dynamic import("…"), and it resolves readline/promises.

The expression above does not look at child_process, though. Spawn a process and you can get out without importing a network module at all. Add it and the result changes:

grep -rlE "(from|require\()[[:space:]]*['\"](node:)?(http|https|http2|net|tls|dgram|dns|child_process)['\"]|\bfetch\(|WebSocket|XMLHttpRequest" \
  node_modules --include='*.js' --include='*.cjs' --include='*.mjs'

Now it is six files, and commander and simple-git appear. That difference is the more honest result, so let me take those one at a time.

simple-git — spawns git as a child process. What turns up are reads like rev-parse, status, and diff; in the shipped bundle, no call to the writing side (push / fetch / pull / clone) turns up. The library defines those operations — pushTask and friends are in simple-git's bundle — and basou's own test suite pushes once, to a throwaway local repository.
commander — carries the ability to launch executable-file subcommands, which basou does not use.
Processes basou spawns directly — what turns up is which (locating a command), open (opening a local URL in a browser), and git ls-files (called directly, not through simple-git, by basou view's pre-flight check).
basou run — its targets are the fixed subcommands claude-code and codex, not an arbitrary command. The agent it launches, of course, uses the network itself.
basou exec — this one can launch an arbitrary command. Type basou exec curl … and curl goes out, naturally.

So what can actually be said

The two checks reach different places. There are also holes they share.

Check	Reaches	Does not reach
Running with outbound denied	That the executed paths do not depend on outbound traffic succeeding	The 21 subcommands not executed / an implementation that sends and swallows the failure
Static scan	That, in the forms this expression catches, connection APIs are not in the bundle	Paths that assemble a name at runtime / paths that write to a file and let another process carry it

The bottom two cells overlap. An implementation inside an unexecuted branch that assembles a module name and loads it is invisible to the run (it never executes) and invisible to the scan (the shape is different). Stacking the two does not fill that in.

With that said: within what was checked, nothing turns up to suggest basou's own process uses an API for connecting outward. It does use createServer on the receiving side. What goes out goes out because the user handed over a command, or because an agent they asked for was launched — not because basou sent it.

And there is no CI guard forbidding the network. "It's covered by tests" is not something I can say. What is doing the work is that it can be inspected, which is why the steps are here.

One caveat on all of it: sandbox-exec is a command Apple marks deprecated, and the dependency versions are ^ ranges, so there is no guarantee this procedure returns these numbers indefinitely. Every figure above was taken on 2026-08-31, on macOS, against @basou/cli@0.37.0.

What was given up

If you have read this far and think it holds together, look next at what was handed over in exchange. For anyone weighing adoption, this is the part that gives you something to decide on.

1. There is no third-party notarization.
basou detects tampering in its trail, but with no server and no notary, what that yields is a check that the files on hand are internally consistent with each other. The specification is honest about the threat model: someone who rewrites the related files together, consistently, is not detected — the spec puts it as raising the bar from "edit one line" to "recompute and rewrite two coordinated files," which it calls the right primitive for catching accidental and casual mutation. It is not a cryptographic proof from a third party.

2. There is no centralized freshness.
As above. If work was missed on another host, you cannot tell from here. Running the import on each host is the only way.

3. It does not detect a mirror that has gone away.
This one I found by trying it. If the SSHFS mount drops, or the path has a typo, orient does not say "devbox is missing." It quietly returns the local-only result. The only hint is the > hosts: banner disappearing. A warning does appear when the directory exists but cannot be read, and again when the config file's syntax is broken — but when the path simply points at nothing, it says nothing.

Without defending it: this is the underside of a best-effort, non-fatal design. orient is the default command, and if a malformed config file could take it down you would see nothing at all. So it is tuned not to fall over. In exchange, it degrades silently.

4. There is no authenticated shared UI.
The viewer is localhost-only and unauthenticated. Sending a colleague a URL to look at is not a usage this supports.

5. There is no aggregation across a team or an organization.
There is a mode that shows several workspaces side by side, but it is for a single owner to survey their own work, not for watching other people. The specification states that the cards placed side by side carry no work-stats and no per-agent productivity or utilization metrics (there is a separate command that measures output volume; the line is that it stays off the side-by-side survey surface). That one is not something given up — it is an intended non-goal.

If any of those five is unacceptable for your requirements, basou does not fit them. If you want a team's activity aggregated, pick a product built for that. Saying up front where it does not fit seems to me the right way to treat someone weighing adoption.

In closing

Deciding to own no network did not set a ceiling on features. It decided where the boundaries go.

One case is at the center. Against a requirement to span machines, no sync server was written: the transport went to a route the user already had, and only the merge was kept. The other two are not solutions. Remote approval settled the shape and deferred the rest; the local UI accepted a loopback listener with conditions and wrote those conditions down.

And with outbound traffic blocked, basou runs; scan the code and the tools for connecting outward do not turn up. What goes out goes out because the user handed over a command, or because an agent they asked for was launched. That is not a statement of policy — it is something you can check by hand, though only as far as each check reaches, and the reach of each is written above. There is no CI enforcing it either.

The starting point was not an ideology. It was a question about capacity: can a single-author, pre-1.0 OSS project take on the promise of holding other people's data? If it cannot, build the structure so that no custody is required. And that does not make the responsibility disappear — the transport, not exposing the port, and whatever the commands you launch actually do all stay with the user. Writing that part down too is what makes it an explanation of the design.

If you want to try it, basou.dev and the quickstart are the places to start.

Enforce, Don't Issue: Remote MCP with OAuth Without Becoming an Authorization Server

Takashi Matsuyama — Wed, 19 Aug 2026 10:56:02 +0000

Kozou is an open-source tool that exposes structured context from your PostgreSQL database to AI agents — over MCP and a REST API. This post is the record of a design decision: what happened when that MCP surface moved to a remote URL and needed OAuth. The capability shipped in v1.13.0, but the release is not the subject — why Kozou never grew its own authorization server is. Everything below is as of v1.19.0.

The moment you put an MCP server on a remote URL, authentication stops being a footnote and becomes the whole question. Kozou's own "before" state was honest about it: with no auth block configured, a remote call had exactly one shape available — every caller shared a single fixed execution.role. That's fine for a local, single-user setup and useless for anything multi-tenant, because there's no such thing as who is calling. Kozou v1.13.0 is the release where per-caller identity becomes possible at all.

What landed was a choice of mode

Kozou v1.13.0 (released 2026-07-13) brought remote MCP with OAuth (resource-server mode). The MCP transport can now authenticate callers with OAuth, so the execution tool that touches data (call) runs as the verified token's role rather than one shared role. The tools that describe the schema are gated on the scopes the token carries, and read a shared schema context.

The mode matters, and it is the whole point of this post. Kozou did not grow its own authorization server. It became an OAuth resource server: it validates the tokens someone else issued and enforces what they're allowed to do. The setup guide lives at kozou.org/guides/mcp-oauth/, and I'm deliberately not going to reproduce it here — this post is about why the design looks the way it does, not how to configure it.

The posture came first

The tempting story is "the MCP spec says split the roles, so Kozou split the roles." That's backwards. The posture was published first.

On 2026-06-08 — more than a month before v1.13.0 — Kozou's auth posture was already public and settled: Kozou is an enforcement layer; it does not issue identity. That wasn't an aspiration. A week earlier the REST surface had already shipped it: JWT auth and Postgres RLS enforcement landed in #54 on 2026-06-01 and went out in v0.2.0 — validate a JWT against a JWKS endpoint, SET LOCAL ROLE to the identity that token carries, and let Postgres row-level security do the actual enforcement.

So when remote MCP needed authentication, there was no design decision to agonize over. The resource-server shape wasn't chosen to conform to a spec — the shape was already there, and the MCP authorization spec, revision 2025-11-25 happens to describe exactly that split: a resource server that enforces, an authorization server that issues, and a clean boundary between them. v1.13.0 is the JWT → SET LOCAL ROLE → RLS pipeline, already load-bearing on REST, extended onto the MCP transport. Same posture, one more surface.

The order is the argument. The implementation on 2026-06-01, the posture written down on 06-08, the extension onto MCP on 07-13 — code first, words second, the new surface last. "Not chosen to conform to a spec" means exactly that sequence: something already running turned out to match what a later spec described.

What not running an authorization server buys you

Declining to be an authorization server is not a gap in the feature set. It's what makes the rest coherent:

Kozou holds no credentials. There are no user accounts and no identity credentials to store — so there's no token store to breach. It never sees a password. What it checks is a signature and the conditions that come with it — algorithm, expiry, issuer, audience.
You don't have to change identity providers. Because Kozou validates whatever your authorization server issues, enterprise SSO isn't a special integration — it's the same JWKS validation, pointed at your identity provider. That is not the same as nothing to do: your IdP has to be configured to put the right audience, the mcp:* scopes, and a role claim into the token. Getting that wrong is the first thing people trip on — it is the 403 below.
For anything that touches data, the final authorization decision is path-independent. The last word belongs to Postgres RLS, so a query gets the same policy whether it arrived over REST or over MCP's call. The transport changes; the rules don't.

That last point is the quiet payoff. When identity is enforced at the database rather than re-implemented per transport, adding a surface doesn't mean re-deriving your access model — it inherits it.

The MCP surface is deliberately stricter

Here's the part that's easy to miss: the MCP surface is not a copy of the REST surface with a token check bolted on. It is deliberately narrower about what it will accept.

The reason is not "the caller is remote and probably not a human." Put it there and the argument collapses — the person driving claude.ai is a human, and not one of these rules relaxes for them. Two other things drive it, and both have the same shape: one more thing you do not control.

First, you hand your tokens and your advertised metadata to a client you don't run. A remote MCP caller is a hosted client — claude.ai, ChatGPT, Claude Code — the protected-resource metadata Kozou publishes travels to it, and bearer tokens travel to the URLs that metadata names.

Second, you are not the one granting roles. Identity arrives from a federated directory: put Google Workspace behind Keycloak or Auth0, and every first-time user is a principal who authenticated fine and whom nobody assigned a role to.

On REST, Kozou will honor an anonymous role and a default role if you configure them. On MCP it deliberately won't — this is where the second reason bites:

No anonymous access, no default role. A default role here would silently grant authority to a principal your IdP admin never assigned one to — in a federated directory, that is every first-time user. With no role claim there is no clear authority to execute under, so the server fails closed rather than guessing.
Enabling execute requires a non-empty allowedRoles. You have to declare which roles a tool applies to; arbitrary role execution isn't granted by omission. A missing config can't quietly become a privilege escalation.

The remaining rules have no counterpart on REST at all. They come from the first reason — the tokens and metadata you hand to somebody else's client:

The URLs it advertises can't be plaintext http outside loopback. auth.resource and auth.authorizationServers are handed to third-party clients in the protected-resource metadata, and bearer tokens travel to them, so a non-loopback plaintext http URL isn't a warning — it's a startup error. (There's an explicit opt-in for an isolated test network, allowInsecureHttp; using it logs a startup warning.) What's checked is the advertised value, not the listener's TLS — binding Kozou to loopback and terminating https at a reverse proxy or tunnel in front of it is the normal shape.
The resource URI is never derived from the Host header. Headers can be spoofed, so Kozou won't trust the Host header for the kind of decision a DNS-rebinding attack would try to bend.
mcp:admin is a default scope, and is never advertised. Some clients echo the advertised list straight into their own registration request, so listing it would invite them to ask for an admin grant they never need. It stays out of scopes_supported.

The strictness isn't only about refusing things, though. When a token is missing a scope, Kozou (as a resource server) answers with an insufficient_scope challenge that names what's missing — a scope and a resource_metadata pointer — so a client capable of scope upgrade can then go re-authorize. The scopes it advertises are mcp:describe and mcp:execute. In practice this challenge shows up most often when a token carrying no recognized scope at all is refused at the door — usually a setup mistake: the IdP's mapper isn't emitting the scope claim, the audience is wrong, or the token was minted for a different client. With auth.resource set to https://mcp.example.com/mcp, that looks like this:

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", scope="mcp:describe", resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource/mcp"
Content-Type: application/json

{"error":"This operation requires the \"mcp:describe\" scope."}

The same challenge exists per tool, but it is far rarer. tools/list is filtered by scope — a tool whose scope the token lacks is never listed — so a per-tool 403 only happens if a client calls a name it was never shown, or cached tools/list and then had its scopes narrowed.

And the matching case with no credentials at all — per RFC 6750, a 401 with no error attribute, carrying a pointer to where the rules are advertised:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource/mcp"
Content-Type: application/json

{"error":"Missing or malformed Authorization header."}

Both answers carry the same shape of JSON body. But when it is the token itself that failed, the body never says which check it failed — signature, expiry, audience, issuer all collapse into one generic message. A missing scope, which the client can resolve by re-authorizing, is named; a failed verification is not. Only what the client can act on goes in the WWW-Authenticate header.

That's the shape worth internalizing: refusal and discoverability are two halves of the same behavior. A strict server that only ever said "no" would be hostile; one that says "no, and here's precisely the scope you'd need and where to find the metadata" is strict and usable. On the discovery side, Kozou implements both the WWW-Authenticate and the well-known metadata discovery mechanisms, so a client can find the rules either way.

What came after — what used to be implicit became the operator's to declare

One of the things resource-server mode settled is that the resource URI is declared in configuration, never derived — because, as above, the Host header can't be trusted. That refusal to leave things implicit later spread to the deployments that use no OAuth at all.

It started with a mundane confusion. The port you bind is where you are listening. It is not where the client arrives. Those two agree only while nothing sits between them — put a proxy in front, run it through a tunnel, remap the published port, move it inside a devcontainer, and the agreement breaks. Kozou's connection page — the screen that hands a non-engineer a working config — was building the second address out of the first, with no way to correct it once they came apart. It would hand out, confidently, an address that was not the endpoint.

The OAuth side already had the answer. auth.resource is a declared value, never derived from a Host header. v1.18.0's server.mcp.http.advertisedUrl extends that to the deployments that don't configure auth (writing both is a config error). A line drawn against spoofing turned out to be right where nobody was attacking anything — where there was simply one proxy in the way. An unplanned dividend on a rule drawn for strictness.

There is a second one that looks like the same story. v1.17.0's server.mcp.http.enabled (default true) lets an operator declare that the MCP HTTP endpoint should not run. Until then the only lever was the bind address: the endpoint stayed up and its posture depended entirely on network topology. If you are never going to point an agent at it, the choice should be not to run it — not to look for somewhere to hide it.

That one, though, did not descend from OAuth. Its motivation at the time was that the posture had become a byproduct of network topology, which has nothing to do with a spoofable header. Not a descendant of the same rule — a different rule standing next to it. Put side by side they do face the same way, turning something implicit into something declared. I'll leave it at that.

Trade-offs, honestly

None of this is free, and a post that pretended otherwise wouldn't be worth reading:

You need an external authorization server. Resource-server mode means bringing your own issuer. The guide walks through two concrete recipes — Keycloak and Auth0.
Audience handling differs by IdP. Auth0 supports resource indicators (RFC 8707) natively; Keycloak needs a mapper to get the audience into the token. Same destination, different setup step.
Hosted authorization servers vary in their dynamic-registration behavior. This is squarely a client-to-AS concern rather than something the resource server decides, so I'll leave the specifics to the recipes above rather than half-explain them here.

Try it

The minimal setup, the per-IdP recipes, and the troubleshooting are all in one place: kozou.org/guides/mcp-oauth/. There's no point in my retyping the steps — the guide is the source of truth for how.

In summary

Kozou does remote MCP with OAuth as a resource server, not an authorization server — it validates tokens and enforces access, it doesn't issue identity.
That wasn't spec-chasing. The posture ("enforce, don't issue") was public and load-bearing on the REST surface first; the MCP authorization spec's resource-server / authorization-server split simply matched a shape that already existed.
Because the model for touching data is consistent end to end — JWT → SET LOCAL ROLE → Postgres RLS — the MCP surface can afford to be deliberately stricter than the REST one: no anonymous access, no default role, fail-closed by default, and refusals that tell the client exactly what scope is missing.
And "declare it, don't derive it" outgrew resource-server mode: advertisedUrl (v1.18.0, for the deployments that don't set auth — the config refuses the two together) handed the other postures an answer the OAuth side already had. A line drawn for strictness turned out to be the correct answer elsewhere.

It was written with the help of basou, a harness I'm building for steering AI coding agents.

Hide It from People, Tell It to the Agent — What May This Role Touch?

Takashi Matsuyama — Fri, 07 Aug 2026 07:40:20 +0000

Point an AI agent at a database through a least-privilege role and here is what happens. The agent writes a confident query against a table it cannot read. What comes back is permission denied. Or — if all it ever got was a catalog already filtered by privilege — it reads the absence as nonexistence, substitutes a similarly named column, and hands you a number with complete confidence.

The privileges are working. What isn't working is the telling. PostgreSQL is stopping it with GRANT and row-level security (RLS). The only party never told why, or how far, is the one being limited.

So: how should an agent be told what a role may touch? And — does telling it weaken the privileges?

This post is the record of how Kozou — a compiler that turns a PostgreSQL schema into AI context (handed to the agent over MCP, the standard protocol for connecting AI agents to external tools), an Admin UI, and a REST API — answered that. The short version: don't hide it from the agent, tell it. Hide it in the human Admin UI, annotate it in the AI's context: the same information, pointed in opposite directions.

Everything below is as of v1.17.0, using the demo schema bundled with Kozou's quickstart — a small online store (customers / products / orders / order_items plus three reporting views). The support_agent role, its grants, and the RLS are the overlay I added for this post. Version-wise: the privilege annotations require v1.8.0 or later and the RLS signal v1.11.0 or later, so an earlier version omits whichever of the two it predates.

The line already drawn

The Kozou introduction drew a line: Kozou hands meaning over, it doesn't enforce it — the actual access control stays on the PostgreSQL side, in privileges and RLS. The follow-up on writing schema meaning put it from the author's side: if you truly must hide something, stop it with a privilege, not a comment.

This post is about the outside of that line. You stopped it with a privilege. How does the agent find out?

Decision 1 — hide, or annotate?

Kozou's privilege support is opt-in. Turn it on with a role and two surfaces start reflecting what that role can do — and they do it in opposite directions. (The REST API and its OpenAPI document are not among them; they stay schema-wide. The API enforces each request with the caller's role and RLS, so it has no need for an advisory annotation.)

The Admin UI (for people): a table the role cannot SELECT disappears from the navigation. A column it cannot write doesn't disappear from the form, but it renders read-only per form mode — no INSERT privilege makes it read-only on create, no UPDATE privilege makes it read-only on edit.
The MCP describe_table / describe_view tools and kozou docs (for the agent): nothing is hidden. Every relation stays, and each one is annotated with what this role may and may not do.

It's easier to just look at it. Here is describe_table("public.customers") evaluated for support_agent — a support-desk role that can read orders but was never granted SELECT on the customer table (it holds personal data):

{
  "qualifiedName": "public.customers",
  "privileges": { "role": "support_agent", "select": false, "insert": false, "update": false, "delete": false },
  "columns": [
    { "name": "id",        "insertable": false, "updatable": false },
    { "name": "full_name", "insertable": false, "updatable": false },
    { "name": "email",     "insertable": false, "updatable": false }
    // …
  ]
}

select is false — this role has no privilege to read this table. What you see here is the GRANT situation only, evaluated independently of the RLS we'll get to later (Kozou asks has_table_privilege). And the table still comes back whole. Columns, the @ai notes and the @policy business rules written into the table's COMMENT ON — all of it, still attached. kozou docs, the Markdown schema document, does the same: the section for that table doesn't vanish, its Security row just goes all no.

**Security** — effective privileges for role `support_agent` (advisory; PostgreSQL enforces access):

| SELECT | INSERT | UPDATE | DELETE |
| --- | --- | --- | --- |
| no | no | no | no |

Now open the Admin UI with that same configuration. The header reads 3 tables / 0 views. customers is gone from the list, and so are the three views the role was never granted SELECT on. At the same moment, MCP and kozou docs return all seven objects — four tables and three views — each annotated with what the role can and cannot do.

Same privilege information, same configuration, opposite output.

Why point them in opposite directions

People don't look for what isn't there. A button you can't see doesn't get pressed; a menu item that's missing doesn't get demanded. For a human UI, not showing what can't be done is the kinder choice: it keeps controls that cannot succeed out of the way.

An agent, I assumed, is the opposite: it fills in absences by guessing. If the table isn't visible, it concludes no such table exists and reaches for a similarly named column instead. That is the same failure shape as the one in the previous post — an AI that sees only raw DDL, doesn't know which column is a trap, and is plausibly wrong — except now it happens on the privilege side. To be clear, this is not a measured result; it's the direction the design bet on.

So the agent is better told: it's here, and you cannot read it. "select": false isn't a refusal, it's information. The agent learns its limits before it tries.

The split is in the code's own vocabulary. In the comment beside Kozou's config schema, the Admin UI "hides tables the role cannot SELECT", while MCP and docs "do NOT hide — they keep every relation and annotate it". And the docs generator is handed a privilegeDisplay: 'annotate' when privilege mode is on.

The option not taken: hide on the AI side too and ship a narrowed schema. It looks like giving away less, but the agent learns the object doesn't exist and starts guessing to fill the hole where the overall picture used to be. Less information out, more mistakes back.

Decision 2 — read only the booleans

Beyond table-level and column-level GRANTs there's row-level security. What the agent gets about RLS is three booleans and one line of advice.

orders — RLS on, one policy:

"rowSecurity": {
  "enabled": true, "forced": false, "hasPolicies": true,
  "note": "Row-level security is enabled: the rows you can read and the rows you can write are filtered by policy for the connecting role, so do not assume a result is complete or that a write will be accepted."
}

customers — RLS on, and not a single policy defined:

"rowSecurity": {
  "enabled": true, "forced": true, "hasPolicies": false,
  "note": "Row-level security is enabled but no policy is defined, so non-owner roles can read and write no rows (default-deny). RLS also applies to the table owner (roles with BYPASSRLS still bypass it)."
}

That quirk of PostgreSQL — where writing no policy is the strictest setting you can pick, because RLS with no policy is default-deny — travels intact to the agent. forced means RLS applies to the owner too, and that gets a line as well.

What's absent here matters. The USING and WITH CHECK expressions — the policy bodies — are never handed over. Only the booleans are read; the expressions aren't even fetched.

Three reasons.

It would put authorization logic in two places. A copy of the rules living in the context will go stale. That's the same problem as written meaning having a shelf life, from the previous post, now applied to authorization — and a stale explanation of who may see what is worse than a stale column comment.
Knowing doesn't help you get around it. Reading the expression gives the agent no way past RLS; the database enforces it regardless. There's little to gain.
The expressions themselves can be sensitive. How you distinguish between users is often exactly what you don't want disclosed.

What that costs is clear too. The agent can't explain why it was refused. A rejected write at least surfaces as an error; a SELECT is quieter — RLS drops the non-matching rows silently and returns a perfectly normal result. So what gets handed over instead is the warning that a result may not be complete. Explaining the reason is not a job this takes on.

The option not taken: summarize the policy expressions and pass the summary. The moment that summary goes stale, the agent starts lying with confidence — "you should be able to see this row."

Decision 3 — what gets to be opt-in

Two kinds of information have shown up: the role's privileges, and the RLS signal. Their defaults are opposites.

Run describe_table twice against the same database, changing only the configuration:

Field	Default	`respectPrivileges: true`
`privileges`	absent	present
per-column `insertable` / `updatable`	absent	present
`rowSecurity`	present	present

The rule fits in one line: role-dependent facts are opt-in; structural facts are included by default.

privileges is a lie unless you've settled whose privileges these are — which is why the output says whose: "role": "support_agent". Hand out a privilege picture without deciding the role and you've published misinformation, not information. Whether RLS is enabled, forced, or policy-less is a structural property of the table and doesn't depend on any role, so it can go out unasked.

The options not taken: enable both by default (with no role configured, you'd be handing out a privilege picture belonging to nobody), or make both opt-in (an agent walks into a default-deny table, gets an empty result it can't account for, and reasons from it).

One detail worth noting: evaluating the privileges doesn't require connecting as that role. It's has_table_privilege / has_column_privilege, so nothing borrows the role's authority just to describe it.

Decision 4 — don't let describe and act disagree

So far, everything has been about description. Kozou can also execute exposed functions over MCP (opt-in as well), and once execution is in play, a description is only accurate if it matches the role that acts.

Turn execution on and the annotated role is bound to the executing role. The agent cannot pick a role — self-elevation isn't forbidden so much as structurally unavailable.

Running the remote MCP endpoint as an OAuth resource server changes the shape: execution happens as each verified token's PostgreSQL role, and every assumable role must appear in an explicit allowlist. But the privilege annotation can only be combined with that when the allowlist contains exactly one role — any other combination refuses to start. If the acting role varies per caller while the annotation claims a single role, the annotation is a lie. Per-caller annotation doesn't exist yet.

The reason is simple: if the role whose privileges were described isn't the role that acts, the agent is working from an accurate description of the wrong role. A description is only as true as its agreement with execution.

The option not taken: let the annotated role and the execution role be configured separately. More flexible — and it would let you run in a state where the two disagree. So it isn't configurable; the disagreeing combinations fail at startup.

The boundary — this is not permission

Finally, what this deliberately doesn't do.

An annotation is not a permission. "select": true is advice that reading should work, not a grant. Granting is what GRANT and RLS do, and there is nothing Kozou can add to that (on the execution side it can narrow things — the functions it exposes go through an allowlist). The same idea shows up in how functions are published: whether an agent may run a function exposed with @expose: rpc is decided by the EXECUTE privilege. Exposure is not permission.

Executing as a single role is not multi-tenant per-user authorization. There's no per-caller identity in it. That's the job of the REST surface, or of the OAuth path where the role comes from the token.

There is a cost, though. Not hiding means the context ends up carrying the names of tables the role cannot read, their columns, and the business notes written on them. Not one bit of data access changes, but the disclosure surface of the schema as metadata grows. If the audience for that surface is wider than the database role — say you expose the MCP endpoint beyond your machine — that needs designing separately.

With that said, back to the opening question. Telling doesn't weaken the privileges. Access to data stays exactly where PostgreSQL put it. The riskier party, I'd argue, is the agent that doesn't know its limits: it writes speculative workarounds, reads an empty result as "there is no data," and carries that into its conclusion.

Try it

To see this on your own schema, there are three steps.

Create one least-privilege role. The trick is to deliberately leave one table without SELECT — that's where the interesting part of this design becomes visible.

   CREATE ROLE support_agent NOLOGIN;
   GRANT USAGE ON SCHEMA public TO support_agent;
   GRANT SELECT ON orders, order_items, products TO support_agent;  -- customers withheld
   GRANT INSERT ON orders TO support_agent;                          -- the INSERT grant only

Add two lines of configuration.

   introspection:
     respectPrivileges: true
     role: support_agent

Call describe_table. kozou docs grows a Security section too — though the per-column insertable / updatable only exist in the MCP payload (docs stops at the four verbs per table). Views carry relation-level privileges only: PostgreSQL itself can grant on a view's columns, but Kozou only collects column-level privileges from tables.

With the grants above, orders comes back like this:

"privileges": { "role": "support_agent", "select": true, "insert": true, "update": false, "delete": false },
"columns": [
  { "name": "status", "insertable": true, "updatable": false },
  { "name": "channel", "insertable": true, "updatable": false }
  // …
]

And then, writing this example, my own post tripped me up. This demo's orders has RLS enabled, and the only policy I wrote is for SELECT. In PostgreSQL, inserting into a table with RLS enabled requires an INSERT policy. So actually trying it gives you:

ERROR:  new row violates row-level security policy for table "orders"

The GRANT INSERT is there. The payload says "insert": true. PostgreSQL refuses anyway. The annotation is saying "the privilege exists," not "this will go through." That is the most concrete possible form of what this whole post has been about — and it's why the same payload carries rowSecurity right beside it, warning that a write may be rejected. Neither half alone is enough to hand to an agent.

Privilege mode announces itself in the log, too:

[kozou mcp] privilege-aware context ON: describe tools annotate what role "support_agent" may touch (advisory; enforcement stays in PostgreSQL)

advisory; enforcement stays in PostgreSQL — this post is, in the end, about what that one line means as a design.

Kozou lives at kozou.org and on GitHub (Apache-2.0). The demo schema above ships in the quickstart.

Summary

The same privilege information is hidden from people and annotated for the AI — on the bet that an agent kept in the dark fills the absence by guessing.
RLS travels as booleans only. The policy expressions stay unread, so authorization logic never leaves the database.
Role-dependent facts are opt-in; structural facts are included by default. And the role you describe must be the role that acts.
An annotation never promises the operation will go through. insert: true and an RLS refusal coexist happily.

Enforcement was PostgreSQL's all along. What changes by telling an agent its limits is whether it can do useful work inside them.

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

Write Database Meaning Your AI Agent Can Actually Use — a Practical Guide to COMMENT ON

Takashi Matsuyama — Fri, 24 Jul 2026 08:45:54 +0000

In the Kozou introduction — Kozou being an open-source tool that hands your PostgreSQL database's meaning to an AI agent over MCP — I made a claim: the place to write that meaning already exists in PostgreSQL, in COMMENT ON and view definitions, so write the meaning into the DB first. An AI agent that only sees the raw DDL is good at reading column names and types, but it doesn't know which column is a trap or which view is authoritative. So it's plausibly wrong.

This post is the how. How do you write that meaning so an agent can actually use it? The answer isn't in column names or types; it's in COMMENT ON and view definitions, written to a small set of conventions. The examples come from the demo schema (a small online store) bundled with Kozou's quickstart — the real thing, verbatim. Everything shown here you can do on plain PostgreSQL, before adopting Kozou at all; how the written meaning then reaches the agent is the last section.

Write meaning at the start of a line

Inside COMMENT ON, you write convention tags at the start of a line. Three carry the meaning: @ai / @policy / @example. There's also @widget (for the Admin UI) and @expose (for functions), but neither is about handing meaning to an agent, so this post leaves them aside.

Tag	Purpose	Where it goes	Covered here
`@ai`	Instructions/background for the AI agent (free text)	table / column / view / foreign key / function	◎ central
`@policy`	A business rule, recorded (advisory — not enforced)	same	◎ central
`@example`	An executable example query attached to a view	view	○
`@widget`	Admin UI input control for a column	column	mentioned only
`@expose`	Expose a function as an RPC action	function	mentioned only

There's a bit of craft to it. Dull, but skip it and the tag won't fire.

Write it at the start of a line. A known tag (@ai, @policy, …) placed mid-line is not parsed as a tag; it stays as part of the surrounding prose (Kozou warns about it).
One tag per line for @ai / @policy. If you have several points, stack several @ai: lines. The only note allowed to span multiple lines is an @example block.

One more part of the convention, worth knowing on a multilingual team: the note body can be in any language. The tag name (@ai, …) and the colon after it are ASCII, but the text after the colon is kept as you wrote it — trimmed of surrounding space, but never summarized or paraphrased — so your notes can be in English, Japanese, German, whatever your team reads and the agent understands. One caveat if you write in a language with fullwidth punctuation (Japanese, for instance): the tag's colon must stay ASCII :, not a fullwidth ：. Get it wrong and the line silently falls back to plain prose — no warning, unlike the mid-line case above.

Writing also feeds discoverability. Kozou's search_schema searches not just object names but COMMENT bodies and @ai / @policy notes too. The words you put in a note become the handle an agent uses to find the meaning.

The code fragments below are the real thing from Kozou's quickstart demo schema. Inside a COMMENT string, '' (two single quotes) is an escaped single quote; the @ai: / @policy: notes are kept one per line (per the rule), while the CREATE VIEW SELECT further down is reflowed for readability.

`@ai:` — name the trap, point to the source of truth

@ai is free text for the agent. The trick to making it land is to go past "what this column is" and write what the agent should and shouldn't do — usually in the imperative. Three from the demo schema.

First, the clearest trap: a column you must not use.

COMMENT ON COLUMN orders.amount_total IS 'DEPRECATED denormalized order total.
@ai: Do NOT use this for reporting — it is a stale cache the application stopped maintaining, can disagree with the line items, and includes test orders. Compute revenue from vw_recognized_revenue instead.';

amount_total has a plausible name ("total") and a numeric(12,2) type. Asked for revenue, an agent naturally reaches for SUM. But it's a cache the application stopped maintaining, out of step with the line items, with test orders mixed in. The pattern here: don't stop at "don't use it" — always add the way out, "use vw_recognized_revenue instead." Naming a trap without an exit leaves the agent with nowhere to go next.

Next, an exclusion that always applies.

COMMENT ON COLUMN orders.is_test IS 'Internal QA / load-test order flag.
@ai: ALWAYS exclude is_test = true from revenue, order counts, and dashboards — these are not real customer orders.';

The pattern: use strong words (ALWAYS / NEVER) and spell out the scope. Saying "exclude it from revenue, from counts, and from dashboards" keeps the agent from misjudging which contexts the rule covers.

Third, the nastiest kind — the one that fails silently.

COMMENT ON COLUMN products.list_price IS 'The CURRENT catalog price.
@ai: This price changes over time. NEVER use it to value past orders — each order captured its own price in order_items.unit_price; joining list_price onto historical orders silently misprices revenue.';

Value a past order with list_price (the current catalog price) and the JOIN succeeds, the query throws no error, and only the number is quietly wrong. The price to use is the one captured at order time, order_items.unit_price. For traps that produce no error, just a wrong result, write down why it's wrong — otherwise no one has a thread to pull to catch it.

So how does an @ai you wrote reach the agent? When Kozou reads the schema, an @ai line comes back over MCP (the standard protocol for connecting AI agents to external tools) as aiDescription, sitting right next to the column.

{
  "name": "amount_total",
  "dataType": "numeric(12,2)",
  "aiDescription": "Do NOT use this for reporting — it is a stale cache the application stopped maintaining, can disagree with the line items, and includes test orders. Compute revenue from vw_recognized_revenue instead."
}

The note you wrote arrives beside the column, in the words you wrote it in. Stack several @ai: lines on one column and they're joined with newlines into a single aiDescription.

`@policy:` — advisory, not enforcement

If @ai is "here's how I'd like you to behave," @policy is "record this as a rule that must not be broken." Two from the demo schema.

COMMENT ON TABLE orders IS 'Customer orders.
@ai: An order is recognized revenue only when status = ''paid'' AND is_test = false AND deleted_at IS NULL and its customer is not soft-deleted; value each line at order_items.unit_price (the captured price), not products.list_price.
@ai: The vw_recognized_revenue view already applies every one of these rules — start there for any revenue question.
@policy: ''refunded'' and ''chargeback'' reverse a sale; never count them as revenue.';

COMMENT ON TABLE customers IS 'People who place orders.
@ai: Rows with deleted_at IS NOT NULL are soft-deleted (kept for audit / legal retention); exclude them from customer-facing queries, counts, and metrics.
@policy: Treat email as personal data; do not expose it in aggregate or public reports.';

There's a line here, the same one the introduction drew. @policy is advisory for the agent, not enforcement. Writing "don't expose email in aggregate or public reports" in a @policy does not, by itself, stop access. The actual enforcement stays on the PostgreSQL side — privileges (GRANT) and row-level security (RLS). Keep supplying meaning separate from enforcing permissions — it's Kozou's design stance, and a line worth holding as an author too. If you truly must hide something, stop it with a privilege, not a comment.

@policy arrives separately from @ai (a single newline-joined string) — as an array of rules. "How I'd like you to think" (@ai) and "a rule you must not break" (@policy) reach the agent as different things. A rule of thumb: "I want the agent to think this way" → @ai; "I want this recorded as a rule" → @policy. But never forget that what enforces a rule is a DB privilege, not a comment.

Make a view a named concept

So far we've been adding notes to columns and tables. There's a level above that: define the right way of doing something as a view.

If "the correct way to compute recognized revenue" lives in someone's head, turning it into a view makes it a named, executable concept. The demo's vw_recognized_revenue is exactly that.

CREATE VIEW vw_recognized_revenue AS
  SELECT o.id AS order_id, o.customer_id, o.placed_at, o.channel,
         sum(oi.quantity * oi.unit_price - oi.discount) AS net_revenue
  FROM orders o
  JOIN customers c ON c.id = o.customer_id AND c.deleted_at IS NULL
  JOIN order_items oi ON oi.order_id = o.id
  WHERE o.status = 'paid' AND o.is_test = false AND o.deleted_at IS NULL
  GROUP BY o.id, o.customer_id, o.placed_at, o.channel;

Excluding test orders, excluding soft-deleted orders and customers, counting only 'paid', valuing each line at the captured unit price — all baked into the definition. Rules that were scattered collapse into one executable definition.

Give that view a COMMENT ON too.

COMMENT ON VIEW vw_recognized_revenue IS 'Authoritative recognized revenue, one row per paid order.
@ai: This is the source of truth for revenue — it already excludes test orders, soft-deleted orders and customers, and non-paid statuses, and values each line at the captured unit_price minus discount. Start here for any revenue / sales question; do not re-derive from orders.amount_total or products.list_price.
@example: Revenue by quarter.
  SELECT date_trunc(''quarter'', placed_at) AS quarter,
         sum(net_revenue) AS revenue
  FROM vw_recognized_revenue
  GROUP BY 1
  ORDER BY 1;';

The pattern: in the view's @ai, declare it the source of truth — start here, don't re-derive from the raw tables — and attach a representative use in @example. An @example is a description line followed by indented SQL; it's the one note allowed to span multiple lines. That's why, above, @ai is one line and @example is several.

Concepts stack. Another view can build on this one.

COMMENT ON VIEW vw_customer_lifetime_value IS 'Total recognized revenue per active customer.
@ai: Lifetime value reuses vw_recognized_revenue, so the same recognition rules apply automatically; soft-deleted customers are excluded.';

vw_customer_lifetime_value selects from vw_recognized_revenue, so its rules — excluding test orders and soft deletes — apply automatically; there's no filter to rewrite. What's inherited is the executable definition, not the notes: each view still carries its own @ai, and this one's says, in as many words, that it reuses vw_recognized_revenue. Stack a concept on a concept and the rules you wrote once keep working from underneath — but you still write a note on each concept.

Kozou treats such views as domain concepts. Call get_concept_context on one and the agent gets back the view's @ai notes, a recommended query source, related tables, and the @example queries — together. Instead of reassembling the business rules from raw tables, the agent heads for the view that already encapsulates them.

And when you cross tables: the ON condition itself, a machine can derive from the foreign key. But why this JOIN exists is the meaning a human writes on the FK constraint. Put a COMMENT on the FK constraint and Kozou hands its text over as the JOIN's purpose, alongside the ON. The demo schema doesn't comment its foreign keys, so here's an illustrative example of how to write one.

-- Illustrative (not in the demo schema)
COMMENT ON CONSTRAINT orders_customer_id_fkey ON orders IS 'Each order belongs to exactly one customer.
@ai: Join through this FK to attribute revenue to a customer; do not match on email or name.';

Write "what this relationship is for" plus "how to join it (avoid loose matches)," and you can point an agent — one that might otherwise join on email or name despite the foreign key — at the right way to connect the tables.

Notes go stale — keep them maintained

Written meaning has a shelf life. @ai and @policy are primary assets, but change the schema without updating the notes and the agent will confidently believe a claim that's gone stale. A column you marked "don't use" that has quietly come back into service is a mismatch harder to catch than a raw-DDL one — because the note states the wrong thing with full confidence.

So when a migration changes a column or a rule, fix the matching @ai / @policy in the same change. There's generally no test guarding COMMENT freshness, so the last line of defense is review by eye. When you read a schema diff, get in the habit of reading the comment diff alongside it.

The meaning you wrote reaches the agent as-is

Writing the meaning is itself something you do on plain PostgreSQL. COMMENT ON and view definitions live in the same place as the schema and migrate alongside it — primary assets. The habit pays off even without Kozou: onboarding a new hire, aligning understanding in review, carrying context across a future tool switch. Meaning bundled into the schema means anyone reading it hits the same primary source.

Delivering that written meaning to the agent — without summarizing or paraphrasing — is what Kozou does, over MCP; the introduction covers that side. The one thing worth restating here, because it matters when you're the author: Kozou's MCP is describe-only by default — there's no tool for generating, executing, or writing SQL out of the box. Supplying meaning and operating the database stay clearly apart, so writing rich notes doesn't widen what an agent can do to your data.

Setup, per-client configuration, and the real (English) demo schema are all at kozou.org and on GitHub. I won't restate the steps here — how to do it is what the docs are the source of truth for. (Deriving an Admin UI, REST, docs, and types from the same schema-plus-comments — "one definition, many faithful forms" — is a post of its own.)

In summary

Meaning goes not in column names or types but in COMMENT ON and view definitions. The craft: start-of-line tags, one @ai/@policy per line, stack lines for more points — and the body can be in any language (only the tag name and its : are ASCII).
@ai names the trap and points to the source of truth ("don't use it" + "use the authoritative view instead"). @policy records a rule that must not be broken — but it's advisory; enforcement stays with DB privileges and RLS.
A view can be a named concept. Give the authoritative view an @ai (declaring it the source of truth) and an @example (a representative query); build one view on another and the rules are inherited — though each view still needs its own note. An FK's comment travels as the JOIN's purpose.
Notes aren't write-and-forget. Change the schema and update the notes in the same change — a stale note misleads the agent with full confidence.
Then Kozou delivers what you wrote to the agent, as-is. Write the meaning into the DB first.

The repository is github.com/kozou-dev/kozou (Apache-2.0); the docs are at kozou.org. The demo schema ships with the quickstart. Try adding one @ai: line to your own schema and start there.

The Japanese version of this post is already live.

Your AI Agent Can Read Your Database, But Not What It Means — Introducing Kozou

Takashi Matsuyama — Mon, 20 Jul 2026 15:30:02 +0000

I closed the basou introduction with a promise: that there's a companion project, Kozou, for the side that tells an agent what a database means, and that I'd introduce it separately. This is that post.

In one line, Kozou is an open-source tool that gives an AI agent the meaning of your PostgreSQL database. The README opens with it: "Give your AI agent the meaning of your PostgreSQL database, not just its columns." It reads the meaning sitting in your schema — COMMENT ON text, view definitions, type information — and hands it to the agent over MCP (the standard protocol for connecting AI agents to external tools).

Columns it can read, meaning it can't

Let an AI agent loose on a database and you notice something fast. It's good at reading schema — it lists tables, lines up columns and types, assembles a plausible-looking JOIN. And it still gets the answer wrong. Plausibly wrong.

The demo schema bundled with Kozou's quickstart (a small online store) reproduces this failure well. The orders table has an amount_total numeric(12,2) column. A total. Asked for revenue, an agent reaches for SUM(amount_total) — the natural move. But that column is a stale denormalized cache the application stopped maintaining; it can disagree with the line items, and it mixes in test orders. The status column holds 'paid', 'refunded', and 'chargeback' among others, but only 'paid' counts as a sale — the other two reverse one.

None of that knowledge appears in the column names, the types, or the constraints — in the structure itself. It normally lives in a data dictionary, a team wiki, or someone's head. The agent writes a plausible query from the structure in front of it. What fills the gap between plausible and correct is this "meaning."

The meaning already has a home: the database

Before reaching for anything new, one thing is worth establishing. PostgreSQL has had a native place to write meaning all along.

COMMENT ON. Kozou adds a small set of conventions on top of it. The three that carry meaning are @ai / @policy / @example — there's also @widget for the Admin UI, among others. Here's the real thing from the demo schema (reflowed for readability):

COMMENT ON TABLE orders IS 'Customer orders.
@ai: An order is recognized revenue only when status = ''paid''
  AND is_test = false AND deleted_at IS NULL and its customer is not
  soft-deleted; value each line at order_items.unit_price
  (the captured price), not products.list_price.
@ai: The vw_recognized_revenue view already applies every one of these
  rules — start there for any revenue question.
@policy: ''refunded'' and ''chargeback'' reverse a sale;
  never count them as revenue.';

Then views. If the knowledge of "how to compute revenue correctly" lives in someone's head, defining it as a view turns it into a named, executable concept. The demo's vw_recognized_revenue is the source of truth for recognized revenue: excluding test orders, accounting for soft deletes, valuing each line at the captured unit price — all baked into the definition.

Writing meaning into the database itself is a habit that predates Kozou and pays off on its own. The moment you write it, the meaning lives in the same place as the schema and migrates alongside it — a primary source in its own right.

But writing it isn't the same as delivering it to the agent. Over a raw connection an agent can read COMMENT if it digs through the catalog — but whether it digs is up to the agent. What tells it where things are written, which view is authoritative, which rules are advisory and which are enforced — a bare connection has none of that.

Handing that meaning over — this is Kozou

First, what Kozou doesn't do to your database. It doesn't stand up a new metadata store. It only reads the COMMENT and view definitions already in your DB — it creates no tables of its own and runs no DDL (Kozou is migration-tool-agnostic; it compiles the schema your migrations produce). Remove it, and you're back to plain PostgreSQL.

With that settled: Kozou reads the PostgreSQL schema and hands the COMMENT ON text, view definitions, and type information to the agent over MCP — without summarizing or paraphrasing (the README's word is verbatim), structured by tag. Here's what the agent sees:

list_tables / describe_table — the table list, and the full schema + COMMENT for one table
list_views / describe_view — a view's columns, purpose, underlying tables, and the view definition SQL itself
list_concepts / get_concept_context — treats a view as a domain concept, returning its related tables and recommended query path
describe_functions — lists the exposed RPC actions
search_schema — metadata search across names, labels, COMMENT bodies, @ai/@policy notes, and enum members

For example, sending search_schema the word "revenue" brings back both the view named vw_recognized_revenue and the "do not use this for reporting" COMMENT on amount_total — one hit on a name, one on a body. You find where the meaning relevant to that word lives without enumerating and describe-ing the whole schema.

The default is describe-only — reading. The execution tool, call, appears only when you explicitly enable it in the config file (kozou.config.yaml, under server.mcp.execution) and name the role it runs as. It isn't a CLI flag — a plain kozou mcp is always describe-only; being able to execute is a state the operator opts into through configuration.

Here's a fragment of what describe_table("public.orders") actually returns (real excerpt from the demo schema, abridged to the relevant fields and reflowed for readability):

{
  "name": "amount_total",
  "dataType": "numeric(12,2)",
  "aiDescription": "Do NOT use this for reporting — it is a stale cache
    the application stopped maintaining, can disagree with the line items,
    and includes test orders. Compute revenue from vw_recognized_revenue
    instead."
},
{
  "name": "status",
  "enumValues": ["cart", "pending", "paid", "refunded", "chargeback"],
  "aiDescription": "Only 'paid' is a captured sale; 'cart' and 'pending'
    are not sales yet; 'refunded' and 'chargeback' reverse a prior sale."
}

The trap from earlier arrives right next to the column, as a note to the agent. An @ai: line from the COMMENT ON becomes aiDescription, a @policy: line becomes policy. The meaning you wrote comes back in the words you wrote it in, structured. An agent holding that note can head for the view declared authoritative — vw_recognized_revenue — instead of guessing its way through amount_total.

Relations work the same way. get_concept_context derives JOIN candidates from the real foreign keys among a view's underlying tables, and attaches the COMMENT on the FK constraint as the JOIN's purpose. If you've written a COMMENT on the FK constraint, you get a suggestion like this (this fragment is illustrative — the demo schema doesn't comment its FK constraints, so calling it as-is returns an empty purpose):

"joinSuggestions": [
  {
    "table": "public.customers",
    "on": "orders.customer_id = customers.id",
    "purpose": "the customer who placed the order"
  }
]

A machine can derive the ON condition. But "what is this JOIN for" is the meaning a human wrote in the FK constraint's COMMENT. Kozou hands over both, as one suggestion.

There's a deliberate line here. Kozou hands meaning over; it doesn't enforce it. @policy is advisory for the agent; the actual access control stays on the PostgreSQL side — privileges and row-level security (RLS). Kozou tells the agent whether RLS is on, but never surfaces the policy expression itself. Supplying meaning and enforcing permissions are kept separate.

One definition, many faithful forms

MCP is the biggest differentiator, but it's one outlet among several. From the same read of the schema, Kozou also generates an Admin UI, REST + OpenAPI, Markdown docs, and TypeScript types. From one source — schema plus comments — it derives every form a human or an AI needs; no duplicate definitions, no drift. That "one source, many uses" stance is a post of its own, so I'll save it for another time.

flowchart LR
  S[PostgreSQL schema<br>COMMENT ON / view definitions] --> K[Kozou]
  K --> MCP[MCP context<br>AI agent]
  K --> UI[Admin UI]
  K --> API[REST + OpenAPI]
  K --> DOC[Markdown docs]
  K --> TS[TypeScript types]

Start in ten minutes

git clone https://github.com/kozou-dev/kozou
cd kozou/examples/quickstart
cp .env.example .env
docker compose up

That brings up PostgreSQL seeded with the trap-laden demo schema, plus kozou dev — the Admin UI on http://localhost:3333 and an MCP server on http://localhost:3334/mcp.

To try it over stdio against your own DB, without the Docker stack:

DATABASE_URL=postgres://user:pass@localhost:5432/mydb npx -y kozou mcp --stdio

Or to start it as your own project:

npx -p kozou create-kozou my-project

Per-client MCP setup, the remote-MCP (OAuth) guide, and the reference are all at kozou.org. I won't restate the steps — how to do it is what the docs are the source of truth for.

In summary

An AI agent can read columns and types, but the meaning — which column is a trap, which view is authoritative — isn't in the names and types. That's where plausible, wrong queries come from.
The meaning has a home in PostgreSQL already: COMMENT ON and view definitions. Write the meaning into the DB first — a habit that predates Kozou and works on its own.
Kozou hands that meaning to the agent over MCP without summarizing or paraphrasing — a note beside each column, a purpose on each JOIN, a recommended query path for each concept. And it hands meaning over while leaving enforcement to PostgreSQL.

The repository is github.com/kozou-dev/kozou (Apache-2.0); the docs are at kozou.org. The latest release at the time of writing is v1.15.1. If something trips you up, I'd be grateful for an issue.

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

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

It Owns the Merge, Not the Transport — basou's local-first, zero-network design

I already made the claim. Today is what sits underneath it

Why not send it — not taking custody of other people's data

The responsibility did not vanish. It moved

The main case — it owns the merge, not the transport

Define "another host's trail" as a local path

What it actually looks like

The same screen states its own limit

The rule that came out of it

The same judgment, in two other places

Deferral — fix the schema, don't build the endpoint

Bounded acceptance — one socket

Where it actually writes

How to check any of this

Run it with outbound traffic denied

What this experiment does not show

Back it with a static scan

So what can actually be said

What was given up

In closing

Enforce, Don't Issue: Remote MCP with OAuth Without Becoming an Authorization Server

What landed was a choice of mode

The posture came first

What not running an authorization server buys you

The MCP surface is deliberately stricter

What came after — what used to be implicit became the operator's to declare

Trade-offs, honestly

Try it

In summary

Hide It from People, Tell It to the Agent — What May This Role Touch?

The line already drawn

Decision 1 — hide, or annotate?

Why point them in opposite directions

Decision 2 — read only the booleans

Decision 3 — what gets to be opt-in

Decision 4 — don't let describe and act disagree

The boundary — this is not permission

Try it

Summary

Write Database Meaning Your AI Agent Can Actually Use — a Practical Guide to COMMENT ON

Write meaning at the start of a line

@ai: — name the trap, point to the source of truth

@policy: — advisory, not enforcement

Make a view a named concept

Notes go stale — keep them maintained

The meaning you wrote reaches the agent as-is

In summary

Your AI Agent Can Read Your Database, But Not What It Means — Introducing Kozou

Columns it can read, meaning it can't

The meaning already has a home: the database

Handing that meaning over — this is Kozou

One definition, many faithful forms

Start in ten minutes

In summary

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

`@ai:` — name the trap, point to the source of truth

`@policy:` — advisory, not enforcement

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