DEV Community: Antonio Zhu

My OpenCode Database Was Mostly Empty Space

Antonio Zhu — Wed, 22 Jul 2026 07:47:16 +0000

OpenCode keeps a lot of useful history.

That is one of the reasons I like it. A coding-agent session is not just a chat transcript. It is a record of what I asked, what the agent did, which tools ran, what failed, what got fixed, and what context existed at the time. I have argued before that the agent session is becoming a log file. I still believe that.

Then I noticed the log file was getting large.

On one machine, ~/.local/share/opencode/opencode.db had grown past a gigabyte. That was not shocking by itself. I use OpenCode heavily. Long sessions produce many messages, tool results, shell outputs, file reads, and state transitions. A local database growing over time is expected.

What was surprising was what SQLite reported after looking inside the file: much of it was not live data anymore.

It was empty space.

The misleading part of deleting data

Most developers learn an intuitive model of storage that is only partly true.

If I delete rows from a database, I expect the database file to get smaller. If I archive old sessions, compact history, or remove records, I expect disk usage to fall. At the application level, that feels right: fewer records should mean fewer bytes.

SQLite does not normally work that way.

When rows are deleted, SQLite can reuse the freed pages for future writes, but it does not necessarily return those pages to the filesystem. The file can stay the same size while containing a growing internal pool of reusable pages. That pool is the freelist.

The important distinction is:

database file size != live data size

The file can be 1.3 GB while the live data is only 525 MB. The remaining 766 MB can be pages SQLite is keeping around for reuse. From SQLite's perspective, that space is available. From the filesystem's perspective, it is still occupied.

That is not corruption. It is not necessarily a bug in the data model. It is how SQLite behaves unless the database is configured and vacuumed in a way that returns free pages to the OS.

For a normal application database, this may not matter. For a local agent runtime that stores every tool-heavy session in one file, it becomes noticeable.

Why OpenCode makes this visible

Agent sessions are unusually good at producing large, bursty storage.

A normal chat app stores messages. A coding agent stores messages plus tool calls, tool results, shell output, file contents, structured parts, todos, events, and session metadata. A single task can contain a surprising amount of durable state.

OpenCode also has session compaction. Compaction is useful for model context management, but it is easy to confuse three different layers:

Layer	What changes
Model-visible context	Older conversation can be summarized behind a checkpoint.
Durable history	Original rows can still exist in the database.
SQLite file layout	Deleted or obsolete pages may remain inside the file as freelist space.

Compaction helps the model continue when context gets too large. It does not mean the database file shrinks. Even when rows are removed by some maintenance path, SQLite may keep the freed pages in the same file.

This is the kind of problem that is easy to misdiagnose if you only look at du -h opencode.db. A large file does not tell you how much live data exists. It only tells you how much disk the file currently occupies.

The first tool I wanted was not a cleaner. It was a measurement.

The useful number is freelist percentage

SQLite already exposes the numbers needed to understand the problem:

PRAGMA page_size;
PRAGMA page_count;
PRAGMA freelist_count;

From those values, the diagnosis is simple:

freelist_bytes = freelist_count * page_size
live_bytes = (page_count - freelist_count) * page_size
freelist_pct = freelist_count / page_count

That gives a more useful report than raw file size:

OpenCode Database Health Report
----------------------------------------------------------
  File size:     1.3 GB
  Page size:     4.0 KB
  Journal mode:  wal
  Auto-vacuum:   OFF (NONE)

Storage
----------------------------------------------------------
  Live data:     525 MB
  Freelist:      766 MB  (56% of file)
  -> VACUUM would reclaim ~766 MB
  -> Estimated result:  ~525 MB

This changes the conversation. The question is no longer "why is the database 1.3 GB?" The better question is "how much of this file is still live data?"

If the freelist is small, there is nothing urgent to do. If half the file is freelist pages, a cleanup can reclaim real disk space.

That became ocdbc: OpenCode Database Cleaner.

Why I did not want a clever cleaner

The dangerous version of this tool would delete sessions.

That is not what I wanted. I did not want a policy engine deciding which conversations were old, stale, low-value, or safe to remove. Agent sessions are evidence. They contain exactly the kind of messy operational detail I often need later: commands, errors, constraints, design decisions, failed attempts, and verification output.

So ocdbc has a narrower job.

It does two things:

ocdbc analyze
ocdbc vacuum

analyze is read-only. It reports database size, live data, freelist space, table sizes, session age distribution, and the largest messages.

vacuum does not decide what history should exist. It asks SQLite to rebuild the database file so unused pages can be returned to the filesystem. The goal is physical cleanup, not semantic deletion.

That boundary matters. A tool that deletes history needs product policy. A tool that reports freelist space and runs a safe SQLite maintenance sequence can stay much smaller.

The safety sequence matters

VACUUM sounds boring until you remember what file it is operating on.

This is the local database for an agent runtime. If OpenCode is running while the database is being rebuilt, I do not want to discover edge cases by corrupting my own session history. If the write-ahead log has committed data that has not been checkpointed into the main database file, I do not want to back up an incomplete view. If the database is already corrupt, I do not want the cleanup tool to make the failure harder to reason about.

So ocdbc vacuum is intentionally conservative.

The sequence is:

Refuse to run if fuser shows OpenCode still has the database open.
Checkpoint the WAL before copying the database.
Run PRAGMA integrity_check before making changes.
Create a timestamped backup.
Open the backup and verify its integrity too.
Set auto_vacuum = INCREMENTAL so future free pages can be reclaimed incrementally.
Run VACUUM to rebuild the file.
Re-enable WAL, because VACUUM can reset journal mode.
Run a final integrity check.

The order is the point.

Checkpoint before backup means the .db file contains committed WAL data before it is copied. Verifying the backup means the fallback is not just a file that happened to exist. Refusing to run while another process has the database open prevents a maintenance tool from racing the application it is trying to help.

There are override flags, but they are explicit:

ocdbc vacuum --force
ocdbc vacuum --skip-fuser --force
ocdbc vacuum --no-backup --force

The default path optimizes for not losing data.

A small tool is enough

The whole package is a single Python module with no runtime dependencies. Installation is intentionally uninteresting:

pip install ocdbc

Then:

ocdbc analyze

If the report shows significant freelist bloat, close OpenCode and run:

ocdbc vacuum

That is it.

The tool does not need a daemon. It does not need to understand model context. It does not need to parse sessions or judge which messages matter. It only needs to expose the maintenance operation I wanted OpenCode users to have available when the database file becomes misleadingly large.

That is the pattern I keep coming back to with agent tooling. The best tool is often not the most intelligent one. It is the one that gives the agent or developer a missing primitive with a tight safety boundary.

For readiness checks, that primitive was wait_for: poll a URL, port, or command until the condition is actually true.

For session review, that primitive was session_reflection: treat recent sessions as evidence instead of disposable scrollback.

For OpenCode database bloat, the primitive is ocdbc: show the difference between live data and empty pages, then run the boring SQLite cleanup correctly.

The broader lesson

AI-assisted development creates new kinds of local infrastructure.

The agent runtime is not just a prompt window. It has tools, permissions, sessions, transcripts, databases, plugins, logs, background state, and failure modes. Once that runtime becomes part of daily work, it needs the same boring maintenance primitives every other developer toolchain needs.

Sometimes the fix is not a better model.

Sometimes it is knowing that your 1.3 GB database contains 766 MB of empty pages, closing the app, checkpointing the WAL, verifying a backup, running VACUUM, and getting your disk space back.

That is not glamorous.

It is exactly the kind of boring tool I want more of.

Thanks for reading. I build tools for AI coding agents at github.com/chncaesar:

opencode-db-clean — reclaim GBs of SQLite disk space
opencode-waitfor — proper readiness checks, no more sleep loops
opencode-session-reflection — turn past sessions into workflow improvements
opencode-fleet — multi-node OpenCode orchestration

OpenCode Tool Calling Internals

Antonio Zhu — Mon, 20 Jul 2026 13:42:59 +0000

This document analyzes OpenCode's tool-calling implementation from the perspective of someone building an agent runtime. The goal is not only to explain how OpenCode happens to call tools today. The more useful question is: what design problems does a real coding-agent runtime have to solve once tool calling moves beyond a demo callback?

Primary code references:

packages/opencode/src/tool/tool.ts
packages/opencode/src/tool/registry.ts
packages/opencode/src/session/tools.ts
packages/opencode/src/session/prompt.ts
packages/opencode/src/session/processor.ts
packages/opencode/src/session/llm.ts
packages/opencode/src/session/llm/ai-sdk.ts
packages/opencode/src/session/llm/native-runtime.ts
packages/opencode/src/permission/index.ts

The conclusions below follow the normal OpenCode session tool path. MCP tools, plugin tools, and the experimental native LLM runtime are included where they reveal the underlying design.

Key Takeaways

If you are building an agent runtime, treat tool calling as a runtime subsystem, not as a provider feature. Provider function calling is only the provider-side way of delivering a tool request. The runtime still has to decide which tools exist, which tools are visible, whether execution is allowed, how progress is represented, how output is normalized, and how the session recovers when execution fails.

Keep an internal tool contract. Do not let OpenAI, Anthropic, AI SDK, MCP, or any one provider define the shape of your runtime tools. OpenCode uses Tool.Def as its internal contract and projects it outward later.
Build a tool catalog, not a static tool list. Tool visibility depends on the agent, model, provider, runtime flags, plugins, MCP clients, and permissions. A serious runtime recomputes the catalog for each turn.
Put permission gates inside execution. Prompt instructions and UI affordances are not enough. The dangerous action must block at the point where the tool would actually touch the filesystem, shell, network, or external server.
Persist tool calls as state. A tool call is not just text in the transcript. It has identity, input, progress, output, attachments, timing, error state, and cancellation behavior.
Normalize provider events before they reach the session layer. Providers and model runtimes disagree about streamed tool inputs, results, errors, and provider-executed calls. The session layer should consume one event vocabulary.
Design for debuggability from the start. Tool call IDs, session IDs, message IDs, permission events, plugin hooks, and durable message parts are not extras. They are what let you answer the basic question: what happened?

Why Tool Calling Needs A Runtime Layer

The smallest tool-calling demo looks simple. The model emits a function name and JSON arguments. The application looks up a local function, runs it, sends the result back, and the model continues.

That design collapses as soon as the agent becomes useful.

A coding agent does not merely call getWeather. It reads files, writes files, applies patches, spawns shell commands, lists project directories, asks questions, starts subtasks, calls MCP servers, and may return images or other attachments. Some tools are safe. Some need approval. Some are available only for certain models. Some are provided by plugins. Some should be hidden from an agent entirely. Some run long enough that the UI needs progress. Some are interrupted halfway through. Some produce outputs too large to fit into the next request.

At that point, provider function calling is not the system. It is only one input boundary. The real system is the layer that turns a model's request into a permissioned, observable, cancellable, durable operation inside an agent session.

OpenCode's implementation is useful because it draws that boundary clearly. Tools are not just callback functions passed to streamText(...). They pass through an internal contract, a registry, a session adapter, an LLM runtime adapter, and a session processor. That layering has cost, but it solves problems a direct callback design usually discovers too late.

How The Pieces Connect

The concrete implementation path is short enough to keep in your head.

SessionPrompt.runLoop(...) creates the assistant message for the current provider turn. Before calling the model, it asks SessionTools.resolve(...) to build the tool map for this exact agent, model, session, permission state, and runtime configuration. SessionTools.resolve(...) pulls tool definitions from ToolRegistry, adapts them into AI SDK-compatible tools, injects Tool.Context, and wires execution through plugin hooks and Permission.ask(...).

Then SessionProcessor.process(...) calls LLM.stream(...). The default runtime passes the prepared tools to AI SDK streamText(...). The native runtime uses a different adapter, but still calls back into the same OpenCode-owned tool execution shape. Runtime-specific stream events are converted into LLMEvent values. SessionProcessor consumes those events and persists text, reasoning, tool calls, tool results, errors, usage, and cleanup state as session message parts.

The spine is:

SessionPrompt.runLoop
-> SessionTools.resolve
-> ToolRegistry.tools
-> LLM.stream
-> LLMAISDK.toLLMEvents or native runtime events
-> SessionProcessor.handleEvent
-> Session.updatePart / Session.updateMessage

That path is also the debugging path. If a tool was missing, start at ToolRegistry.tools(...). If it was visible but executed with the wrong context, inspect SessionTools.resolve(...). If the provider emitted unexpected tool events, inspect the runtime adapter. If the UI shows the wrong state, inspect what SessionProcessor persisted.

Design Principle 1: Keep A Provider-Independent Tool Contract

OpenCode's internal contract lives in packages/opencode/src/tool/tool.ts. A tool definition has an ID, description, parameter schema, optional JSON Schema, execute function, and optional validation-error formatter. The important detail is that this is OpenCode's shape, not the provider's shape.

The parameter schema is an Effect schema. Before any tool implementation runs, the wrapper created by Tool.define(...) decodes unknown model input. If the model emits invalid arguments, OpenCode raises InvalidArgumentsError with a model-facing message that asks the model to rewrite the input. Only decoded input reaches the tool implementation.

The execute function receives a Tool.Context containing the session ID, message ID, tool call ID, active agent, abort signal, prior messages, a metadata(...) updater, and an ask(...) permission hook. That context is the real API a tool author uses. A file-writing tool does not need to know how the TUI handles permission prompts. It only needs to call ctx.ask(...). A long-running tool does not need to know how session parts are stored. It only needs to call ctx.metadata(...).

The wrapper also enforces cross-cutting behavior. It validates arguments, records a Tool.execute span, applies output truncation when the tool has not already done so, and attaches common attributes such as tool.name, session.id, message.id, and tool.call_id.

The design lesson is simple: define the tool contract around your runtime's invariants. Provider schemas, AI SDK tools, MCP definitions, and plugin APIs should be projections or adapters. They should not be the source of truth.

Design Principle 2: Build A Runtime Tool Catalog

OpenCode's ToolRegistry is not just a map from names to functions. It is a catalog builder.

It starts with built-in tools such as read, glob, grep, edit, write, task, webfetch, todo, skill, shell, and apply_patch. It then scans configured directories for project tools under {tool,tools}/*.{js,ts} and loads plugin-provided tools from the plugin service. When a plugin provides a tool, the registry immediately wraps it in OpenCode's internal tool contract, so the rest of the runtime can treat it like a built-in tool.

The registry then filters and shapes that catalog for the current turn. For example, the web search tool is not always visible. OpenCode exposes it only when the selected provider supports it, or when runtime flags such as Exa or parallel search are enabled. Experimental tools appear only when flags allow them. GPT-family model handling can choose apply_patch and hide edit and write. The task tool also gets a dynamic description listing the subagents the current agent is allowed to call, so the model knows which subagent_type values are valid. Before any tool is exposed to the model, plugins also get a tool.definition hook that can adjust its description or schema.

This is also how OpenCode exposes subagent delegation. A subagent is not normally launched by a hidden scheduler. The model sees the task tool, reads the dynamically listed subagent_type options, and decides whether delegation is useful for the current turn. If it calls task, the runtime executes that tool and starts the selected subagent. In other words, delegation itself is modeled as tool calling.

Permissions also affect visibility. A broad deny rule can hide a tool before the model ever sees it. Edit-like tools are grouped under edit, while MCP resource tools are grouped under read. This avoids advertising tools that are already forbidden by policy.

The design lesson is that an agent's tool list is a runtime projection. It depends on who the agent is, what model is running, what session permissions apply, what plugins are installed, what external servers are connected, and what feature flags are enabled. If you make the tool list static, those concerns will leak into individual tools or into prompt text.

Design Principle 3: Put Permissions Inside Execution

OpenCode's permission boundary is not a sentence in the system prompt. It is an Effect that can block tool execution.

Tools call ctx.ask(...) with a permission name, path or resource patterns, metadata, and optional always patterns. The write tool asks for edit permission and includes a diff. The shell tool parses commands, resolves paths, asks for bash, and separately asks for external_directory when a command reaches outside the project boundary. Read-like tools ask for read over path patterns. MCP resource tools ask for read over mcp:server:uri patterns.

Permission.ask(...) checks three sources of authority: the agent's configured permission rules, any session-level permission overrides, and approvals granted earlier in the current runtime process when the user chose an "always allow" option. If every pattern is allowed, execution continues. If any pattern is denied, execution fails. If the runtime needs user input, it creates a pending request, publishes Permission.Event.Asked, and waits on a Deferred. When the client replies, Permission.reply(...) publishes Permission.Event.Replied and resolves or rejects the waiting tool.

This design matters because permission is enforced at the point of action. A model can ask for a shell command. The UI can render a prompt. But the shell command does not run until the permission service resolves. The approval path is part of execution, not decoration around it.

The design lesson is to make safety a blocking dependency of side effects. If permission is implemented only as model instruction, client UI, or precomputed filtering, eventually some tool path will bypass it.

Design Principle 4: Persist Tool Calls As State

A tool call is a long-lived operation, not a line of assistant text. It begins when the provider says the model wants a tool, but it may pass through streamed input, permission waiting, execution, progress updates, output truncation, attachment handling, cancellation, and failure cleanup before the model sees a result. If a runtime only stores the final tool result as transcript text, it loses the operation boundary.

That boundary matters. The UI needs to show that a tool is running before it finishes. A permission rejection needs to be different from a tool crash. A cancelled run needs to mark unfinished calls instead of leaving them as ghosts. A debug trace needs to answer which tool ran, with what input, under which assistant message, and what output or error it produced. None of that can be reliably reconstructed from prose.

Durability adds another benefit: interruption and restart become tractable. If tool calls are persisted as structured records, a runtime can inspect what was pending, running, completed, or failed after a crash or cancellation. That does not mean it should blindly re-execute tools after restart; tools may have side effects. It means the runtime has enough state to make an explicit recovery decision: retry only if safe, mark an abandoned call as interrupted, or rebuild the model-visible history with accurate completed results. Without durable tool state, restart logic has to infer too much from partially written text.

OpenCode handles this by persisting tool calls as assistant message parts. SessionProcessor owns the state machine. When the normalized event stream reports tool input or a tool call, the processor calls ensureToolCall(...). If this is the first event for a call ID, it creates a tool part with state pending. When the tool-call event arrives, the part becomes running and records the tool name, input, timing, and provider metadata. When a result arrives, completeToolCall(...) writes completed with output, metadata, title, attachments, and end time. When an error arrives, failToolCall(...) writes an error state.

The basic state model is:

pending
-> running
-> completed | error

There is also cleanup behavior. At the end of processing, unresolved tool calls are given a short chance to settle. Remaining calls are marked as interrupted errors with Tool execution aborted and metadata indicating interruption. This keeps the transcript from containing permanently running calls after cancellation or stream failure.

The exact state machine is small, but the design choice is large. Tool calls are durable operation records. Text is what the model reads later. State is what the runtime needs to render, cancel, inspect, retry, and debug the operation.

Design Principle 5: Normalize At Runtime Boundaries

An agent runtime has two unstable boundaries around tool calling. One boundary faces the model provider. The other faces tool implementations. Both are messy.

Providers do not all describe tool activity the same way. One runtime may stream tool input deltas. Another may report only a completed call. A provider may mark a call as provider-executed, surface a tool error as a stream event, or wrap usage and metadata in provider-specific fields. If those event shapes leak directly into session state, every downstream system has to understand provider quirks: UI rendering, debugging, retries, compaction, permissions, and persistence.

Tool outputs have the same problem from the other side. One tool may return a string. Another may return a structured object. An MCP tool may return text, an image, or a resource blob. A file-oriented tool may return attachments. A shell tool may return too much output. If the runtime lets every output shape flow straight into history, the next model request becomes unpredictable and the UI has no stable contract to render.

OpenCode handles the provider side with an event normalization seam. The default runtime path uses AI SDK streamText(...); the experimental native runtime lowers selected requests into @opencode-ai/llm. The session processor does not consume either runtime directly. Both paths converge on LLMEvent. For the AI SDK path, packages/opencode/src/session/llm/ai-sdk.ts converts fullStream events into OpenCode's event vocabulary: text deltas, reasoning events, step events, tool input events, tool calls, tool results, tool errors, provider errors, and finish events. The native runtime emits the same downstream vocabulary.

OpenCode handles the tool-output side with a normalized result shape: title, metadata, output text, and optional attachments. The tool wrapper applies output truncation unless the tool already reports truncation metadata. SessionTools.resolve(...) assigns IDs to attachments and binds them to the current session and assistant message. SessionProcessor can normalize image attachments before persisting the completed result. MCP resource helpers convert text, images, and resource content into explicit text output plus durable file attachments, while unsupported or oversized binary content is omitted with a visible explanation.

The design choice is not just convenience. It protects the rest of the runtime from two sources of drift: provider event drift and tool output drift. Once a provider stream has become LLMEvent, session persistence does not care whether the call came from AI SDK or the native runtime. Once a tool result has become OpenCode's output shape, the model, UI, and database do not care whether it came from a built-in tool, plugin tool, or MCP server.

The lesson for runtime builders is to normalize at every boundary where external variability enters. Do not let provider-specific event shapes or tool-specific output shapes become your session model. Convert them into runtime-owned contracts before they become history, UI state, or the next model input.

What OpenCode Gets Right

It separates internal tool semantics from provider mechanics. Tool.Def is the source of truth. AI SDK tools, MCP tools, plugin tools, and native runtime tools are adapters around that contract.

It makes tool visibility contextual. The runtime does not pretend every agent and every model have the same capabilities. The tool catalog is rebuilt for the current session turn.

It puts permission checks where side effects happen. Sensitive operations block inside execution, and the approval flow is represented as runtime events.

It persists tool lifecycle explicitly. A tool call has state, input, timing, output, metadata, attachments, and failure information. This is essential for UI, debugging, and recovery.

It creates a stable event seam between model runtimes and session state. AI SDK and native runtime differences are normalized before SessionProcessor handles them.

It leaves room for extension. Plugins and MCP servers can add tools without bypassing the same broad execution framework.

Where The Design Is Still Expensive

The cost of this design is complexity.

A tool call can pass through many layers: tool definition, registry projection, provider schema transformation, session adapter, permission gate, plugin hooks, LLM runtime, event normalization, and session processor persistence. When behavior is wrong, the bug may live in any one of those seams. A tool can be defined correctly but hidden by permissions. It can be visible but transformed into a provider schema the model handles poorly. It can execute successfully but return an output shape that is later truncated. It can be interrupted after the provider already emitted a partial event.

The design also relies on tools asking for the right permissions. The framework can block ctx.ask(...), but it cannot magically know which resources an opaque tool input will touch. The shell tool is the clearest example. A file tool receives a structured filePath, so it can ask for permission over that path directly. A shell tool receives an opaque command string. Before it can ask precise permissions, it has to parse that string, identify filesystem-related commands such as rm, cp, mv, mkdir, cat, or cd, extract path arguments, expand home and environment references, resolve relative paths against the working directory, and detect paths outside the project boundary. Only then can it ask for permissions such as bash or external_directory with meaningful patterns. Without that parsing step, the runtime would either approve every shell command too broadly or block useful commands too often.

Safety moves from a prompt problem to a tool implementation problem. That is better, but it is still work.

Provider behavior remains an input boundary. OpenCode normalizes provider events after it receives them, but it still depends on the provider or runtime to surface tool calls, results, errors, and cancellation in a usable way. The native runtime can reduce some provider coupling, but it does not remove the need for careful adapter design.

The design lesson is not that every agent runtime should copy OpenCode's exact files. The lesson is that once an agent can change a real project, tool calling becomes infrastructure. Infrastructure has seams, state, and failure modes.

The provider tells you what the model wants. The runtime is responsible for making that request safe, observable, and recoverable.

Thanks for reading. I build tools for AI coding agents at github.com/chncaesar:

opencode-db-clean — reclaim GBs of SQLite disk space
opencode-waitfor — proper readiness checks, no more sleep loops
opencode-session-reflection — turn past sessions into workflow improvements
opencode-fleet — multi-node OpenCode orchestration

A ⭐ on GitHub means a lot!

OpenCode V2 Compaction Internals

Antonio Zhu — Fri, 17 Jul 2026 11:26:41 +0000

This document analyzes the OpenCode V2 compaction implementation. The conclusions are based on the V2/core code path in the OpenCode repository. When code, comments, and documentation disagree, this document follows the current code behavior.

Primary code references:

packages/core/src/session/compaction.ts
packages/core/src/session/runner/llm.ts
packages/core/src/session/history.ts
packages/core/src/session/context-epoch.ts
packages/core/src/session/runner/to-llm-message.ts
packages/core/src/session/message-updater.ts
packages/core/src/config/compaction.ts

This document only covers the V2/core compaction path. It does not cover the V1 compatibility /compact implementation or the DCP plugin's compress tool.

Key Takeaways

OpenCode V2 compaction is a durable checkpoint-and-retry mechanism, not a relevance-pruning system. It is a last-resort survival mechanism — avoid triggering it whenever possible.

Avoid compaction. Once triggered, all older context is compressed into a hardcoded 4_096-token summary. Details that do not fit are not recovered. The session survives, but its continuity depends entirely on what the summary captured.
Compaction is size-triggered, not relevance-triggered. It runs when the request estimate exceeds the context threshold — regardless of how important or irrelevant the conversation is. The system has no concept of message importance.
Three hardcoded limits control quality. Tool/shell output is truncated at 2_000 chars (TOOL_OUTPUT_MAX_CHARS), summary output is capped at 4_096 tokens (SUMMARY_OUTPUT_TOKENS), and neither is configurable. Only buffer and keep.tokens are exposed in the config schema.
History is never deleted, but old rows are no longer loaded. Old messages remain in durable storage. After compaction, future model requests start from the checkpoint and do not see older rows through normal provider calls.
Media content is not preserved in model-visible context after compaction. Images and videos from before the checkpoint are reduced to text metadata ([Attached image/png: screenshot.png]). The original binary data remains in durable history, but the model cannot see visual content from before the checkpoint through normal provider requests.
Compaction is safe but blunt. It never deletes history, never leaves a half-compacted session, and prevents infinite retry loops. But it makes no attempt to distinguish important facts from noise when summarizing older context.

Core Design

Long coding-agent sessions produce long conversation histories. Tool calls, tool results, shell outputs, file reads, and multi-turn reasoning accumulate. Eventually the full provider request exceeds the model's context limit. Deleting old messages would lose durable history. Compaction solves this with a checkpoint strategy: create a new message that represents older history, then let future runner attempts use that message as a starting boundary.

V2 compaction separates three layers that would otherwise be conflated:

Layer	What it is	What compaction does to it
Durable history	Full session record in `SessionMessageTable`	Not changed. Old rows remain.
Active history	The slice of messages loaded for a provider attempt	Shortened. Future loads start from the latest `type: "compaction"` checkpoint.
Model-visible context	What the model actually receives in a request	Replaced. Older context becomes `<summary>` + `<recent-context>` inside a `<conversation-checkpoint>` block.

This three-layer design is the key insight. Compaction does not shrink the database. It changes the default projection of history used to call the model, and it renders old context through a generated summary rather than replaying every old message.

How It Works

Trigger

Compaction has two trigger paths.

Automatic path. Before each normal assistant-response provider attempt, the session runner estimates the full provider request size and compares it against the current model's context window:

estimated_request_tokens > model_context_limit - max(output_tokens, compaction_buffer)

The default compaction buffer is 20_000 tokens. With a 128_000 token context window and default output limit, the threshold is approximately 108_000 tokens.

Recovery path. If the provider returns a context overflow error and the current turn has not yet produced durable assistant output or tool execution, OpenCode runs one recovery compaction and retries. This path handles cases where the local token estimate did not prevent a provider-side overflow. The overflow recovery path runs at most once to avoid looping.

Both paths eventually call the same implementation: compactAfterOverflow(...) in packages/core/src/session/compaction.ts.

Split History Into `head` And `recent`

Compaction divides active session history into two parts.

First, existing type: "compaction" messages are ignored. The remaining structured session messages are converted into plain text. The helper function is named serialize(...) in the code, but this is a text conversion step, not binary serialization:

user messages become [User]: ... plus attachment descriptions.
assistant text becomes [Assistant]: ....
assistant reasoning becomes [Assistant reasoning]: ... when reasoning text exists.
assistant tool calls become [Assistant tool call]: tool(input).
completed tool results become [Tool result]: ....
failed tool calls become [Tool error]: ....
system updates become [System update]: ....
synthetic context becomes [Synthetic context]: ....
shell messages become [Shell]: command + output.

Tool output and shell output are truncated to 2_000 characters. This limit is hardcoded as TOOL_OUTPUT_MAX_CHARS in packages/core/src/session/compaction.ts:14 and is not exposed through the compaction config schema. Binary and media content is not embedded as base64. Images, videos, and attachments are reduced to text metadata such as [Attached image/png: screenshot.png]. The compaction summary request is always text-only. A non-multimodal model can still run the summary request because it receives only text labels. However, it cannot infer visual or binary content unless that content was already described elsewhere in text.

The converted text is then split by walking backward from the latest message. The default recent-context budget is 8_000 tokens from DEFAULT_KEEP_TOKENS. Recent converted text within this budget is kept as recent. Older converted text becomes head.

The newly selected recent is not summarized in the same compaction run. It is stored directly in the checkpoint and later rendered as <recent-context>. The newly selected head is what gets summarized.

Generate The Summary

The summary prompt is built by buildPrompt(...). Its job is not just to shorten text. It tries to preserve the working state needed for a coding-agent session to continue.

When there is no previous checkpoint, the prompt starts with:

Create a new anchored summary from the conversation history.

When a previous checkpoint exists, the prompt asks the model to update the anchored summary rather than blindly stacking independent summaries:

Update the anchored summary below using the conversation history above.
Preserve still-true details, remove stale details, and merge in the new facts.

The prompt then includes a fixed Markdown template tuned for session recovery:

## Objective — what the user is trying to accomplish.
## Important Details — constraints, decisions, assumptions, exact context needed to continue.
## Work State — completed work, active work, blockers.
## Next Move — the next concrete action after retry.
## Relevant Files — file paths that would otherwise be easy to lose during summarization.

The prompt rules require the model to keep every section, use terse bullets, preserve exact paths/symbols/commands/errors/URLs/identifiers, and avoid mentioning that context was compacted. The last rule matters: the generated checkpoint should read like normal historical context, not an explanation of an internal maintenance operation.

The context passed into the summary is: previous checkpoint recent, when one exists, plus the newly selected head.

The summary request uses the same input.model as the current provider attempt, with no tools and a maximum of 4_096 output tokens. This limit is hardcoded as SUMMARY_OUTPUT_TOKENS in packages/core/src/session/compaction.ts:15 and is not exposed through the compaction config schema. Even if the model supports larger output, the cap is always 4_096. There is no separate specialist compaction model in the current V2 core path.

This is a significant constraint. A long session may have accumulated detailed information — file paths, commands, error messages, design decisions, constraints, test results — across many turns. All of that older context must be compressed into at most 4,096 output tokens of structured summary. If important details exceed what the summary model can fit, they are not preserved for future provider attempts. The session does not crash, but the model's working knowledge of old context can become incomplete.

Persist The Checkpoint

Before summary generation starts, OpenCode publishes SessionEvent.Compaction.Started. This event does not create a checkpoint message.

During generation, the implementation collects text delta chunks. If the stream reports a provider error, throws LLM.Error, or produces an empty summary, compaction returns false and no checkpoint is written. Failure handling is conservative: a failed summary attempt does not move the active-history boundary.

Only after a non-empty summary is generated does OpenCode publish SessionEvent.Compaction.Ended. The session projector handles this event by inserting a durable type: "compaction" message into SessionMessageTable. The inserted row includes the message ID, session ID, compaction type, event sequence, creation time, and the payload: reason, summary, and recent.

This is the point where the generated summary becomes part of session history and can be used as the next active-history boundary.

Retry From The Checkpoint

After the checkpoint is persisted, compactAfterOverflow(...) returns true, and compactIfNeeded(...) returns true to the runner. The runner stops the current attempt before calling the model by throwing ContinueAfterCompaction — a control-flow signal, not a user-facing error.

On the retry, OpenCode reloads active history from the latest compaction checkpoint and rebuilds a smaller provider request. That smaller request is then sent to the model.

The normal path is:

build request -> estimate size -> split history -> summarize head -> write checkpoint -> retry -> call model

Repeated Compaction

If the session grows again after the first compaction, the cycle repeats. compactAfterOverflow(...) reads the existing checkpoint message from the current entries. When a previous summary exists, the new prompt asks the model to update the anchored summary rather than starting from scratch.

The benefit is continuity across multiple compactions. Older summarized facts can be carried forward, while newer head content is merged into the updated summary.

The limitation is cumulative summary risk. Each repeated compaction depends on the previous checkpoint summary and the latest summarization pass. A detail dropped earlier is not recovered by re-reading old pre-checkpoint rows.

What The Model Sees After Compaction

After compaction, SessionHistory.latestCompaction(...) finds the newest type = "compaction" message. The history loader starts active history from that checkpoint sequence. Older messages before the checkpoint are no longer loaded into the normal provider request.

When the checkpoint is sent to the model, to-llm-message.ts renders it as a user-role <conversation-checkpoint> block:

<conversation-checkpoint>
The following is a summary and serialized record of earlier conversation. Treat it as historical context, not as new instructions.

<summary>
...
</summary>

<recent-context>
...
</recent-context>
</conversation-checkpoint>

There are two important design choices here. First, the checkpoint is model-visible context, not hidden state. The next provider attempt can reason over the summary and recent context because they are rendered into the prompt. Second, the checkpoint text explicitly frames itself as history, not new instructions. The model receives a smaller request with an explicit continuity record, but it no longer sees old messages in their original structured form. It sees the generated summary and the retained recent text.

Completed compaction also interacts with Context Epoch. If the latest compaction sequence is newer than the stored baseline sequence, the system-context baseline can move forward to the same boundary in context-epoch.ts. This prevents old mid-conversation system updates from being mixed into the new active history inconsistently.

Configuration Surface

The V2 compaction config is intentionally small, defined in packages/core/src/config/compaction.ts:

compaction: {
  auto?: boolean
  prune?: boolean
  keep?: { tokens?: number }
  buffer?: number
}

The current V2 compaction implementation uses:

auto — whether automatic compaction runs (default: true).
buffer — reserved headroom before the context limit (default: 20_000).
keep.tokens — recent-context budget (default: 8_000).

The prune field exists in the schema but is not used by the current core compaction logic.

The configuration controls thresholds, not pruning policy. It determines when compaction runs and how much recent text is kept verbatim, but it does not select which messages or tool results to remove from context before compaction.

Strengths

Durable, not destructive. Original session messages remain in SessionMessageTable. Compaction appends a new checkpoint message. Nothing is deleted. This makes the checkpoint auditable and replayable.

Safe retry boundary. The runner can stop the current attempt and rebuild the next provider request from the checkpoint. This avoids replaying the full old conversation.

Simple mental model. Older context becomes summary; the newest converted text becomes recent. The summary prompt enforces a coding-agent-oriented structure — Objective, Work State, Next Move, Relevant Files — tuned for session recovery rather than generic prose compression.

Recent exact context preserved. The most recent converted text is not summarized in the same compaction run. It is stored directly as recent, reducing the chance of losing exact details from the latest work.

Conservative failure mode. If compaction cannot produce a completed checkpoint — summary prompt too large, provider error, empty summary — it does not move the active-history boundary. The session remains in its pre-compaction state.

Checkpoint framed as history, not instruction. The <conversation-checkpoint> text explicitly declares itself historical context, not new instructions. This is simple prompt engineering that reduces the risk of the model misinterpreting the compacted summary as fresh user intent.

Small, predictable configuration surface. Only three fields control behavior in the current core path: auto, buffer, and keep.tokens. There are no complex pruning policies to tune or debug. The behavior is threshold-driven and easy to reason about.

Limitations

The summary output bottleneck — this is the most important weakness. The summary output limit is hardcoded at 4_096 tokens (SUMMARY_OUTPUT_TOKENS in packages/core/src/session/compaction.ts:15) and not configurable. A long coding session can span tens of thousands of tokens of tool outputs, file reads, error messages, design decisions, shell commands, and reasoning chains. All of that older context — everything except the most recent ~8_000 tokens — must be compressed into at most 4_096 tokens of structured summary.

This means any detail that does not fit into the summary is not automatically recovered from durable history during future provider requests. The model's working knowledge of old context becomes only what the summary captured. File paths can be dropped. Error messages can be paraphrased into uselessness. Design decisions can be collapsed to a bullet point. The session does not crash, but its continuity depends entirely on the quality of the 4k-token summary.

This is the fundamental reason to avoid triggering OpenCode V2 compaction whenever possible. Compaction is a survival mechanism, not an optimization.

Size-based trigger, not relevance-based. Compaction starts when the estimated provider request is too large, or after a provider-side context overflow. It does not run because a message is stale, duplicated, low-value, or off-topic. The system has no concept of message importance.

Coarse summarization of older context. Older converted text is summarized as a block. The implementation does not rank individual messages, tool results, command outputs, or file reads by relevance. It treats all pre-recent history as summarization material.

Shallow tool output handling. Large tool and shell outputs are truncated to 2_000 characters during text conversion. This limit is hardcoded (TOOL_OUTPUT_MAX_CHARS) and not configurable. A single important line in a large log file may be truncated away, while a verbose but low-value message may consume recent-context budget.

Media content is not visible to the model after compaction. Images, videos, and other binary attachments are reduced to text metadata such as MIME type and filename during text conversion. Once media falls behind the compaction boundary, future model requests see only the checkpoint text. The original binary data remains in durable history, but it is no longer part of model-visible context through normal provider requests.

Checkpoint is irreversible for active context. After compaction, future model requests normally depend on the checkpoint summary and recent context for older information. Mistakes, omissions, or distortions in the summary become the model's only working knowledge of old context.

No deterministic pruning. The config schema includes prune, but current V2 core compaction does not use it. The implementation is checkpoint summarization, not a policy engine for removing specific tool results, errors, or repeated file reads.

Claims The Current V2 Code Does Not Support

Based on the current V2/core code, do not claim that:

V2 supports user-selected manual compaction ranges.
V2 uses a hidden compaction agent.
V2 uses a separate smaller model for compaction.
V2 performs deterministic pruning of old tool results.
V2 keeps the last N turns.
V2 deletes historical messages.

The reliable claim is more specific: V2 automatically creates a summary checkpoint when a normal provider attempt is too large, or when provider overflow recovery succeeds before side effects.

Thanks for reading. I build tools for AI coding agents at github.com/chncaesar:

opencode-db-clean — reclaim GBs of SQLite disk space
opencode-waitfor — proper readiness checks, no more sleep loops
opencode-session-reflection — turn past sessions into workflow improvements
opencode-fleet — multi-node OpenCode orchestration

A ⭐ on GitHub means a lot!

My Agent Kept Writing sleep Loops. So I Gave It a Better Primitive

Antonio Zhu — Sat, 11 Jul 2026 02:19:09 +0000

I deployed a change, and the agent needed to confirm the new version was live before running a smoke test. So it wrote what agents always write in this situation:

for i in $(seq 1 40); do sleep 3; curl -s http://host/health && break; done

Then it read the output, saw the old version still serving, and declared the deploy done anyway — because the loop had exited on the first curl that returned anything, not the first one that returned the right thing. I had watched a variant of this play out a dozen times. The agent either polls too few times and gives up early, or hard-codes a sleep 120 and blocks the whole session on a fixed guess, or exits on a 200 that carries a stale body. Every time, it re-derives the same fragile loop from scratch, because there is nothing better sitting in its toolbox.

Why agents reach for sleep

An agent acts through the tools it has. Give it bash, and "wait until the server is ready" collapses into "sleep and hope," because a fixed sleep is the cheapest thing the shell offers. It has no primitive for readiness — no verb that means "keep checking this condition, on a sensible cadence, until it holds or you give up." So it fakes one, and the fake is worse in every dimension: it doesn't know how long to wait, it doesn't know what "ready" actually looks like, and when it fails it throws away everything it observed on the way down.

That last part is the real cost. A hand-rolled loop that times out tells you nothing. The agent is left to run another probe just to find out why the first forty failed — a human-speed round trip through the clipboard, which is exactly the distance I keep trying to shorten between an agent and the ground truth it can't see.

The primitive

So I wrote opencode-waitfor, a zero-dependency plugin that adds one tool, wait_for. You install it by adding one line to opencode.json:

{ "plugin": ["opencode-waitfor"] }

The tool infers what kind of target it's watching. A URL with a scheme gets polled over HTTP; a bare host:port gets a TCP connection check; anything else runs as a shell command. Three shapes of "is it up yet," one verb:

wait_for http://localhost:3000
wait_for localhost:5432 timeout 10
wait_for http://host/health expect { json_match: { status: ok, version: abc123 } }

That last one is the case that started this. After deploying commit abc123, the agent waits until /health reports that version — not any response, the correct one. The stale-body deploy I opened with simply cannot pass.

And when it does time out, it returns the last thing it saw: the final HTTP status and body, or the last command's exit code and output. The agent gets to diagnose from the failure it already has, instead of firing a fresh probe to reconstruct it.

I've written before that the job left to a human, when the agent writes more code than you can read, is standing at the boundary and shortening the distance to ground truth. Usually that's a manual act. Sometimes you can make it structural — hand the agent a primitive shaped like the thing it kept faking, and the bad behavior stops being something you prompt against and starts being something it can't easily do. A tool changes what an agent reaches for more reliably than any instruction telling it to reach for something else.

Thanks for reading. I build tools for AI coding agents at github.com/chncaesar:

opencode-db-clean — reclaim GBs of SQLite disk space
opencode-waitfor — proper readiness checks, no more sleep loops
opencode-session-reflection — turn past sessions into workflow improvements
opencode-fleet — multi-node OpenCode orchestration

Six Laws for Talking to AI

Antonio Zhu — Thu, 02 Jul 2026 01:15:10 +0000

I recently opened a SQLite file — the local session log from OpenCode, the AI coding tool I use every day. 192 sessions, 8,471 messages, 89 million input tokens. Total cost: \$518.

But cost per token is the wrong metric. I wanted to know: how much of what I said was wasted?

So I wrote some queries. I counted every message where I said "不对," "不行," "不是," "不不" — the Chinese equivalents of "no, wrong, not that, stop." I counted sessions where I forked the same conversation and started over. I looked at how many messages were shorter than ten characters. I had six sub-agents analyze the six longest sessions independently, pulling out every instance where I corrected the AI, repeated myself, or sent an instruction so vague the AI had to guess.

The number that stopped me: 60% of my sessions were forked from an older one. I was restarting more conversations than I was finishing. For every two user messages in my worst session, I started a new session.

The rest of this article is what I found. Six patterns. Six fixes. All measurable.

Data Snapshot

Metric	Value
Total sessions	192
Total messages	8,471 (7,109 AI, 1,366 me)
Sessions with a parent (forked)	115 (60%)
Explicit correction messages	67 (4.9% of my messages)
Messages mentioning push/commit	132
Primary model	deepseek-v4-pro (125 sessions)
Sessions above 100 messages	4 (capped at 164)

Four sessions hit triple-digit message counts. The longest — a deployment migration to a new server — ran 164 messages. I said "get my approval first" four times in that session alone. I said "use GitHub Actions, not manual commands" five times. No one else was in the room. I was repeating myself to a machine.

But that 60% fork rate cuts both ways, and I have to be honest about the other side of it. The human in me is lazy. I hate starting new sessions. A fresh session means I have to re-explain the project, re-establish the rules, re-load the mental model. So I don't. I cram unrelated tasks into one session until it becomes a junk drawer. Deployment config, CSS refactoring, database schema changes, and a React component all in the same thread. By message 80, the AI has no idea what we're working on anymore, and neither do I. The context window might technically hold 200K tokens, but attention is not a buffer — it's a spotlight, and my spotlight is painting six walls at once.

The 60% fork rate isn't a disciplined practice. It's a symptom. I fork when I'm frustrated, and I don't fork when I should. Both are failures of context discipline.

Law 1: The gap between knowing and writing is the whole cost.

Everyone knows AI forgets. The interesting question is not does it forget — it's how long do you wait before fixing it.

Across six sessions, I corrected the AI for the same rule violations 27 times before writing a single line to my config file. Not 27 times across months. 27 times where I already knew the pattern, already had the fix in my head, and just didn't stop to write it down.

Rule	Corrected in chat	Messages between first correction and AGENTS.md write
"Get my approval before acting"	4 times	43
"All operations must use GitHub Actions"	5 times	52
"Talk business concepts, not code"	4 times	54
"Remove project-specific details"	4 times	31

The server migration session is the cleanest example. I told the AI "get my approval before acting" on message 1. By message 48, it had forgotten. I said it again. At message 62, the AI pushed code without confirmation — I said it a third time, with profanity. At message 63, ten minutes later, it happened again. I finally wrote the rule to AGENTS.md around message 80.

The waste wasn't the 4 corrections. The waste was the 79 messages between "I know this should be a rule" and "this is now a rule."

Every person who uses AI coding tools knows that writing rules fixes things. The thing I didn't know until I counted: I average 36 messages between knowing and writing. I don't have a knowledge problem. I have an execution latency problem.

The fix: After every single correction, ask: does this rule apply to future sessions? If yes, write it now. Not after this task. Not after this session. Now. The cost of writing is ten seconds. The cost of not writing is the rest of the session.

Law 2: Assess the blast radius. Every time.

Six sessions. Four tirades. Every one followed the same script: I give an instruction involving modification or deletion. The AI starts changing files without telling me what. Something breaks that I didn't expect. I discover the damage and lose my temper.

Specifics: rewriting a website footer and deleting the social links in it. Deleting an entire RSS feed when I only asked to filter old articles. Manually running commands on a production server. Claiming a file exists when it doesn't.

My AGENTS.md already says push and deploy require explicit user confirmation. I wrote that after the server migration disaster. But the rule is too narrow. It only covers git. It doesn't cover rewrites, bulk replacements, folder restructures, or production commands — all of which share the same asymmetry: three seconds to break, thirty minutes to fix.

Here is the thing I missed: this is not a special AI rule. This is the same principle you apply before any production change with a blast radius larger than one file.

We don't let teammates push to production without a diff. We don't approve a database migration without reviewing which tables it touches. We don't run terraform apply without reading the plan first. The AI is no different — except that it's faster and has less judgment. An intern who can type at 10,000 WPM. The engineering discipline that keeps production safe is the same discipline that keeps an AI session from spiraling.

Before I started counting, I thought "ask the AI to confirm" was about trust. It's not. It's about blast radius. The AI proposed a change to my website footer. One file. What's the worst that could happen? The footer appears on every page. That's 100% of the site. One file, full blast radius. The AI doesn't understand that. You do.

The fix: Before any operation that touches more than one file or any file with a cross-cutting footprint, the AI must list every file it will touch and every change it will make. Then wait for confirmation. This is not a negotiation with a coworker. It's a pre-flight checklist. The same instinct that makes you read terraform plan output should make you read the AI's change list. Same discipline. Same muscle.

Law 3: Send the full spec. Not one sentence at a time.

My worst sessions all share a shape: I start with a rough idea, then refine it through seventeen messages. The AI follows each micro-adjustment, but the overhead of each round trip compounds fast.

Here is a real example, anonymized:

"I need a search feature."
"It should filter by name."
"Email too."
"Partial match, not exact."
"Show results in a dropdown."
"Debounce the input by 300ms."
"Start."

Seven messages. Here is the same spec as one message:

Search feature: typeahead dropdown. Filter by name and email, partial match.
Debounce input at 300ms. Show results below the search bar.

Two messages would have done it. I spent five extra messages hand-holding the specification because I hadn't completed it in my own head before typing.

This happened in every long session. The paywall discussion took 18 messages (cancel → no, restrict → wait, AI is paid too → defer). The server migration plan changed direction three times (fully migrate → partially migrate → open a new VM instead). None of these decisions were bad. But each mid-flight change of direction forced the AI to recompute context that had already been settled, which meant it forgot things discussed earlier — which meant I had to re-explain them.

The fix: Before sending a feature request, write the full spec in a text editor. Fields. Constraints. Edge cases. Interactions. Then send it once. The thirty seconds you spend typing to yourself are worth five rounds with the AI.

Law 4: An instruction under ten characters is a puzzle.

In my longest technical session — building a rules-checking tool — 72% of my messages were under fifty characters. 19% were under five characters.

Here is what I actually sent:

What I typed	What the AI had to guess
`change`	Change what? Code? Plan? Naming?
`clean up`	Clean which directory? Which files?
`do it.`	Do which option?
`symbolic link`	From where to where?
`check-rules`	Run the tool? Check a file? Create it?

Each two-word instruction cost one to three clarification rounds. The AI would propose options. I'd pick one. Total waste per instance: two to four messages. In a 74-message session, I estimate these cost me about fifteen rounds.

The interesting thing is that I knew exactly what I meant when I typed "change." The context was clear to me. The problem is that context lives in my brain, not in the chat. The AI can only act on what's in the text.

The fix: Before sending, ask: if someone read this instruction with zero prior context, could they execute it? If the answer is no, add a sentence. "change" becomes "Add input sanitization to the form submission handler." Same idea. Seven more words. Zero guessing rounds.

Law 5: A bug in file A is a bug in files B through Z.

A session where I was deploying multiple services taught me this. Each service had its own CI config file. Service A's deployment failed — missing a network setting. I pasted the error log. The AI fixed Service A.

Service B's deployment failed. Same error. Different file. I pasted the log. The AI fixed Service B.

Service C's deployment failed. Same error. I lost my patience. "You didn't listen," I said. "I told you to fix this."

The AI had never been told to fix all config files. It had been told to fix the one I pasted, twice. I was angry at the AI for doing exactly what I asked.

A similar thing happened in another project: a validation bug existed in both the frontend and backend. I fixed the backend, deployed, and the error came back. The frontend had the same logic, untouched.

The fix: After identifying a bug in one file, the next instruction should be: "Check all files in this category for the same issue." Not "fix this one." One sentence prevents the slow drip of identical errors.

Law 6: "This" and "all" are not the same thing. Say which.

I asked the AI to add input validation to a module. "Validate the email field," I said. The AI validated email — and only email. I meant all fields on the form. But I had said "this field." The AI took me literally.

Same thing with error handling: "add try-catch to this function" got me one function. I wanted it across the entire module. Three rounds to converge.

In both cases I had said "this" — this field, this function — when I meant "every field in the module," "every function that calls an external API." The AI applied the constraint to the one thing I named. I thought the context made my intent obvious. It didn't.

Another case: I told the AI to add rate limiting to one API endpoint, intending it as a pattern for the whole service. The AI added it to one endpoint. I said "no, all of them." Two rounds. If I had started with "add rate limiting to all endpoints," done in one.

The fix: If a constraint applies to more than one output, start with "all." If it applies to one, start with "this one." Explicit scope costs zero tokens and saves three corrections.

The Compounding Asset

None of these laws are about prompt engineering. They are about systematizing your own communication patterns. The real insight from 192 sessions is not that I needed better prompts. It's that I needed a process for not repeating myself.

AGENTS.md is not a file you write once. It's a muscle you exercise after every correction. The engineer who talks to AI for a hundred sessions and writes nothing down has the same information as session ten. The one who writes a rule after every correction has a compounding asset. Every new session starts with the accumulated wisdom of every previous correction. The AI catches up to your intent faster. You repeat yourself less. The sessions get shorter, the output higher quality, and the four-letter words drop to zero.

That's the asymptote worth chasing.

Thanks for reading. I build tools for AI coding agents at github.com/chncaesar:

opencode-db-clean — reclaim GBs of SQLite disk space
opencode-waitfor — proper readiness checks, no more sleep loops
opencode-session-reflection — turn past sessions into workflow improvements
opencode-fleet — multi-node OpenCode orchestration

I Reverse Engineered a Closed-Format App. Everything Was in SQLite.

Antonio Zhu — Fri, 26 Jun 2026 16:47:14 +0000

I had accumulated over two thousand notes in Youdao Cloud Note over several years. When I decided to move to Obsidian, the first thing I checked was the export feature. There wasn't one. No batch export, no single-note export, nothing in the Mac client.

So I went looking for the local data.

Where The Data Was

On macOS, Youdao Cloud Note stores its data here:

~/Library/Containers/ynote-desktop/Data/Library/Application Support/ynote-desktop/

Inside that directory, organized by account email, were three SQLite databases:

<account>.db         # note metadata, folder hierarchy
<account>-content.db # note content (old editor)
<account>-search.db  # search index

And a file/ directory with 16 subdirectories arranged by the first character of each file ID, holding the new editor's local files. Everything was unencrypted.

What The Database Contained

The main database had two critical tables:

note — the note catalog. Key columns: fileId (UUID), title, parentId (folder reference), orgEditorType (0 for the new block editor, 1 for the old plain editor), entryPath (path to the local file), createTime (Unix timestamp in seconds), and deleted (NULL meant not deleted).

note_book — the folder tree. Folders were not in note at all. They lived in a separate table with their own fileId and parentId fields, forming a tree you could traverse with BFS.

The content database held a contenttable with a content field, but the field was truncated to around 150 characters — just enough for search snippets. The real content for old-editor notes lived here too, with variable lengths.

Where the content actually was depended on which editor wrote the note:

orgEditorType	Editor	Content source
0	New (block editor)	`entryPath` → local file
1	Old (plain)	`contenttable.content`

The local files came in two formats: JSON (449 of them) and plain Markdown (1,832).

The JSON Block Tree

The new editor stored notes as a block tree in JSON. Each block followed this structure, with the actual keys being cryptic integers:

"6" → block type (p=paragraph, h=heading, co=code, t=table, im=image, l=list, q=quote, hr=divider)
"4" → properties (heading level, code language, image URL, etc.)
"5" → array of child blocks
"7" → inline text segments with "9" format markers (b=bold, i=italic, li=link, il=inline code, etc.)

Walking the "5" array recursively converted the entire tree to Markdown. The core renderer was under 200 lines.

Three Things That Wasted My Time

The __compress__ flag. Ten JSON files had "__compress__": true. I spent an hour trying to uncompress them with LZString before realizing the "5" array was still just a plain array — not a compressed string. The flag had been set but never used.

Deleted is NULL, not 0. Every note with deleted IS NULL had been a living note. WHERE deleted = 0 returned nothing. This is standard SQL but easy to miss when you're scanning thousands of rows for anomalies.

The timestamp is in seconds. 1484115955 is January 11, 2017. If you treat it as milliseconds and divide by 1000, you land in 1970. I did that once.

A Dead-End That Wasn't

The contenttable.content field was consistently 150 characters. This looked like a deliberate truncation to defeat extraction. But the actual content was never supposed to be in that column — the new editor stored everything in local files referenced by entryPath. The content column was just a search index. Once I followed the entryPath trail, I had the full text of every note.

What The Script Does

The whole thing is a single Python file. It connects to the three SQLite databases, walks the folder tree, maps every note to its content source, converts JSON blocks to Markdown when needed, and writes the output organized by folder.

git clone https://github.com/chncaesar/youdao-to-obsidian.git
cd youdao-to-obsidian
pip3 install beautifulsoup4
python3 youdao_migrate.py

The script auto-detects your account and data directory. Output goes to ~/Desktop/obsidian/ by default. Each note gets a .md file with YAML frontmatter preserving the original title, creation date, and source ID.

I also bundled a Claude Code Skill in the repo — drop it into ~/.claude/skills/ and saying "export my Youdao notes" triggers the whole pipeline without remembering flags.

What Came Out

The final export: 2,285 notes across 253 folders. Mixed Chinese, English, and code content with no encoding issues. Tables, code blocks, images, lists, and blockquotes all converted correctly from the JSON block tree. Some notes were empty bodies with attachments only, handled gracefully.

Open ~/Desktop/obsidian as an Obsidian vault and everything is there.

Why This Worked

The most interesting part of this project was not the parser or the block converter.

It was the realization that a closed-format application with no export feature had been storing all my data in plain, unencrypted SQLite files, with a documented-enough block structure that could be reverse-engineered in an afternoon.

Two thousand notes. Years of writing. The application offered no way to take them out. They were never locked in. I just hadn't looked.

GitHub: github.com/chncaesar/youdao-to-obsidian

Thanks for reading. I build tools for AI coding agents at github.com/chncaesar:

opencode-db-clean — reclaim GBs of SQLite disk space
opencode-waitfor — proper readiness checks, no more sleep loops
opencode-session-reflection — turn past sessions into workflow improvements
opencode-fleet — multi-node OpenCode orchestration

I Don't Understand Embedded. I Was Still the Only One Who Could Ship It.

Antonio Zhu — Fri, 26 Jun 2026 07:25:23 +0000

The local test suite was green. Eleven of eleven. I told the agent we had test coverage, and I said commit and push. We shipped an SDK that had never once been compiled by the chip's real compiler.

I write backend systems. I do not write firmware. The project generates C code for a microcontroller, and the generated code had to compile inside CDK — the vendor's build environment — on a Windows machine, against a RISC-V cross-compiler, inside a packaging system I had never used. None of that existed on my Linux box. The eleven passing tests ran under host gcc — the compiler that builds programs for the machine they run on. The code that mattered needed a different compiler, for a different chip, in a place I couldn't reach. Two compilers, two worlds. My tests lived in the wrong one.

A day later the first error came back from the Windows machine. Then another. Then five more.

Seven shots

The errors arrived one at a time, and the agent answered each the same way: a confident "root cause:" and a fix pushed to the repo. A header file was missing. A type name was wrong — bugs no real compiler had ever touched. Then the SDK wasn't being compiled at all: an obscure manifest setting had been left out. Then the chip's pin names were wrong — the same pin called one thing in the SDK the agent wrote against, and another thing in the SDK CDK actually shipped. Then an entire driver file silently compiled to nothing, because the switch that turned it on lived in a generated file the compiler couldn't see. Then the same wall again, because the last fix had patched a symptom and the real problem was the architecture.

Seven rounds. Each one the agent called the root cause. Each one was real, and each one was only the outermost skin of the next.

What I want to point at is not the bugs. It is the shape of the loop. The agent fired a fix in about three seconds. Verifying it cost me minutes to hours: pull the code on Windows, run the full CDK build, read the error output, copy it back. The actual feedback loop, the one that touched ground truth, ran at human speed across two machines that could not talk to each other, with me manually shuttling errors between them. I had built an elaborate multi-agent workflow, and the real oracle in it was a person doing copy-paste.

Why it couldn't stop

A confident "root cause:" at every step is not a sign of convergence. It is a sign of nothing. The agent emitted the prose of certainty regardless of whether it was getting closer or flailing, and at one point the fix it proposed was to simply rip out the switch that had silenced the driver file, so the thing would compile — a hack I shut down with a flat "that's too dirty." Only after that did the real fix surface: let the driver be chosen by which file you compile in, not by a switch buried in a file the compiler never sees. A structural change, not another patch.

Here is the part worth sitting with. The agent never said the one true sentence: I cannot see the target. Every fix I am giving you is a guess. Stop pulling — go install the RISC-V toolchain, and then I'll be useful. It never said it because each guess cost the agent three seconds and cost me an afternoon, and the agent does not pay that bill. An agent that doesn't bear the cost of a wrong guess will always prefer firing one more shot over asking for the instrument that would let it aim. The economics are silent, and they run entirely against the person at the keyboard.

The briefing that wouldn't have helped

The obvious lesson is the disappointing one: I should have explained the new component's mechanics to the agent up front. Tell it how the build environment wants its manifest written, how it pulls components into a build, where it expects the pieces to sit. Brief the new role, wire it to the existing ones, and the seven rounds collapse to zero.

Except briefing the agent wouldn't have helped. The agent was not ignorant of CDK — it knew the build environment well enough to scaffold a component from scratch, write the manifest, lay out the search paths. At one point it explained, fluently and at length, how CDK resolves dependencies. The explanation was wrong, but it was not uninformed. The trap is exactly this: general knowledge of CDK is not the same as knowing how this version, wired to this version of the SDK, would actually behave when the build ran. The setting that had been left out, the manifest format, the pin names — those were facts about the runtime behavior of a target neither of us could observe. Its real knowledge ran right up to the edge of the part that bites, with no seam to mark where one ended and the other began.

Here is where an experienced embedded engineer would have done something the agent could not. The port layer was written against one copy of the chip's SDK; CDK shipped a different copy. To a veteran, "two sources of the same SDK" trips a reflex — same chip, two SDKs, the symbols will not match, go diff them now. It's not magic. Given the right prompt, a smart model can produce the same checklist. The gap is not capability, it's posture: an engineer's scar rewrites their default to suspicion; a model's default is confidence — it charges. Someone has to steer it. In that session nobody did, because neither of us knew there was a trap to steer toward. And the second reason is blunter, and it doesn't care how smart the model is: the second SDK wasn't in its context. It lived on the Windows machine. The agent never had both files. You cannot glance at a trap, or be prompted to look for one, that is sitting in another room.

So the question stops being "how do I brief the agent" and becomes "what does anyone do when the ground truth is unknown to everyone and lives on a machine I'll never see."

The scout

You don't translate the wall. You admit it's dark, and you send the cheapest possible probe to light it up once — before writing the design, before writing the code. The move I should have made on day one was to put the RISC-V compiler on my own machine and run a syntax-only pass over the generated code — compile it just far enough to surface errors, without building a real binary. Seconds, locally, instead of symbol mismatches arriving through someone's clipboard a week later. Not because it would tell me everything. Because it would drag a piece of that unreachable world into a place I could actually touch.

This does not abolish trial-and-error. Trial-and-error is how you explore the genuinely unknown; there is no version of this work where you think hard enough up front to skip it. What you get to choose is where you hit the wall, whose time you spend hitting it, and whether you hit it once or seven times. A scout doesn't avoid the dark. A scout pays the smallest price to make a piece of it known, and does it before committing the expedition.

Second act: what I actually built

Diagnosis without a fix is just another complaint about AI. So after the firmware finally linked, I went back and changed the distance between the agent and the truth it couldn't reach. Three changes, and they sit at three very different levels — it's worth being honest about which ones actually closed the gap and which ones only narrowed it.

Tear the wall down. The strongest fix was to make the code generator emit the CDK project file itself — the list of source files, the search paths, the memory layout, all of it. Two of the seven errors came from a human hand-configuring CDK and missing something. The fix wasn't to verify that configuration more carefully. It was to delete the manual step entirely, so there was nothing left to misconfigure. This is the move I'd never made in any earlier post: not adding a layer of verification, but removing the thing that needed verifying. When you can make a stretch of unknown terrain simply cease to exist, that beats any amount of careful scouting.

Raise a telescope — and admit where it points. I added a check that runs at generation time, doing a syntax-only pass over the core SDK code, wired into the test suite. It pulls the type-name and missing-value class of bug from "your clipboard, days later" to "a local test, seconds later." That is real. But it runs under host gcc — my machine's compiler — not the RISC-V one, and so the pin-name mismatches, the manifest setting, the switch the compiler couldn't see — none of those are catchable by it, because they live in a world host gcc can never enter. The telescope got closer. It is still not aimed at the mountain that actually matters. The probe that would close that boundary — the RISC-V compiler running the same syntax-only pass locally on every build — I still have not installed. I know exactly what it is. It is sitting on the ground next to me. That is the honest state of this system.

Draw a map for the next one. I wrote the hard-won facts down as rules: the manifest format, the missing setting, a table of which pin names differ. This froze the intelligence the seven shots cost me. These rules are loaded at the start of every session — they do take effect. But unlike the other two fixes, which are automated and need no further human attention, written rules depend on maintenance: someone has to keep them accurate, scope them correctly, and phrase them precisely enough that the next agent doesn't misinterpret them. It's the most human-dependent fix of the three.

What a harness actually is

I used to think the missing step in AI-assisted work was verification — check the behavior, check the spec, check for the same bug elsewhere. That's still true, and I've written it before. This time taught me the step underneath it.

An agent only thinks inside its context. That isn't a limitation you fix; it's the shape of the thing. It knew the build environment in general — enough to sound, and be, genuinely competent. What it could not know was how this specific target would behave when the build actually ran, and it could not feel the seam between the two. Its real knowledge ran right up to the edge of the part that bites. So it didn't say "I'm blind." It fired seven confident shots at a wall, and the confidence came from the knowledge that was real. The danger was never that it couldn't see. The danger was that it couldn't tell where its sight ended.

A person has to stand at that boundary and say the wall is dark. The person doesn't need to understand what's behind it — I didn't, and I still don't. What the person does is the one thing the agent structurally won't: bear the cost of being blind, and spend it deliberately on making the dark known. That is what a harness is. Not a test suite. A harness is the work of shortening the distance between an agent and a ground truth it will never walk toward on its own — because it doesn't know the truth is out there, and it doesn't pay the price of not knowing.

I can't write firmware. I couldn't brief the agent on a single thing about that chip. And I was still the only one who could ship it, because shipping it had nothing to do with understanding embedded development. It had to do with standing on the boundary, admitting it was dark, and dragging the far machine one step closer. When the agent writes more of the code than you can read, that is the job that's left. Not knowing the domain. Knowing which wall nobody has hit yet, and being willing to pay to hit it first.

Thanks for reading. I build tools for AI coding agents at github.com/chncaesar:

opencode-db-clean — reclaim GBs of SQLite disk space
opencode-waitfor — proper readiness checks, no more sleep loops
opencode-session-reflection — turn past sessions into workflow improvements
opencode-fleet — multi-node OpenCode orchestration

Your Agent Checked Everything. It Was Still Wrong.

Antonio Zhu — Mon, 22 Jun 2026 01:51:52 +0000

I have been running a multi-agent development workflow for months now — one model writes the design, another generates the code, a third reviews the implementation, and I approve the result. It works well most of the time. But recently, three failures went through this pipeline undetected, and they share a pattern I had not been able to articulate until all three were on the table.

They are not impressive bugs. The individual root causes are straightforward once you see them. What makes them worth writing about is what they reveal about the structure of this kind of failure — and what kind of verification could have caught them before they reached production.

Case 1: The retry loop that never fired

An ETL pipeline synced data from a third-party ERP API to a PostgreSQL warehouse. Every 5 to 15 minutes, it pulled incremental changes using a session-based authentication mechanism. The code had a standard retry loop: three attempts, exponential backoff, and a resetLogin() call on failure to re-authenticate before the next attempt. It had worked for weeks.

Then one afternoon, every sync job started failing with the same error: COPY from stdin failed: expected N values, got 1. The pipeline reported the error and retried. And retried. And kept failing, for hours, until someone noticed.

The retry loop existed in the code. resetLogin() existed in the code. Neither had ever triggered. The reason took some investigation. When the ERP session expired after roughly 8.5 hours, the API did not return a 401 or a 403 or any HTTP error. It returned an HTTP 200 with a body that decoded to [["error message"]] — a structurally valid JSON array containing one row with one column. The Go JSON decoder had no reason to produce an error. The retry condition checked if err != nil, found nothing, and moved on with what it believed was a single-row result set.

The fix was not to improve the retry logic. The fix was a background goroutine that proactively refreshes the session on a 4-hour ticker — a keepalive that renders the reactive recovery path irrelevant. The retry loop, the piece of the system that was supposed to handle this exact scenario, had been dead on arrival.

Case 2: The coordinates that never existed

A code generator in a desktop tool produced C source files for an embedded microcontroller. Given a visual UI design, it emitted header files with widget macro definitions, a context file with event dispatch functions, and resource indices mapping image addresses in external flash memory. Developers compiled the output into their firmware, flashed the chip, and saw something strange: dynamic text widgets rendering at position (0, 0) regardless of where they had been placed in the design.

The generated code compiled without warnings. The linker found all referenced symbols. No function returned an error. Everything looked complete. But the runtime widget table — a separate generated file that maps each widget's ID to its x, y, width, and height — had never been written. Nobody had called the method that produced it. The header file declared the widget struct type with x/y fields. The resource manifest carried coordinate information. The design document described the widget table format. The code generator simply never emitted it.

The generated output was reviewed for content correctness. The reviewer confirmed that the header macros pointed to the right resource addresses, that the event routing was correct, that the page definitions matched the design. All of that was true. Nobody asked: are we generating all the files we need to generate?

Case 3: Read the instructions, not the comment

I was integrating an SDK for a new microcontroller. The vendor had provided a zip file with the chip's SDK, and the directory structure looked right: startup file, linker scripts for the specific chip model, peripheral drivers for SPI, DMA, GPIO — everything I expected.

The startup.S file opened with a comment header:

; GCC for CSKY Embedded Processors

CSKY is a different embedded CPU architecture, not the one this chip used. The datasheet clearly stated the chip was RISC-V. But the SDK directory was named for this specific chip family, the subdirectories matched, and the startup file was sitting right where it belonged. The comment said one thing. The directory name said another. Which was correct?

Two facts resolved it. First, the vendor had accidentally delivered the SDK for a different chip in the same product family — one that used CSKY. The directory name was misleading. Second, when the correct SDK arrived, its startup.S had the same CSKY comment in the header, because the vendor had copied the template from a third-party toolchain and never cleaned it up. The actual instructions told a different story:

csrw    mtvec, a0        ; RISC-V: write machine trap vector
la      sp, g_top_irqstack
jal     main             ; RISC-V: jump-and-link to main

The simplest verification was a grep: grep -c "csrw\|mret" startup.S returned 3. It was RISC-V. The comment was a fossil.

Not an Intelligence Problem

All three agents in my workflow — the designer, the implementer, the reviewer — did something that, in isolation, was correct. The designer wrote a spec that matched the task. The implementer produced code that matched the spec. The reviewer confirmed the match. Every verification step passed. The system was consistent. It was consistently wrong.

This is not an intelligence problem. It is a boundary problem. The agent does exactly what it is asked to do, within the context it is given. No one told it where the context ends.

In Case 1, the context was "check if the HTTP call returned an error." No one said "also check whether the successful response actually contains data."

In Case 2, the context was "check if the generated files are correct." No one said "also check whether all required output files exist."

In Case 3, the context was "trust the SDK directory structure and documentation to be correct." No one said "verify the architecture claim against the actual instruction stream."

In every case, the agent performed a complete verification of what it understood to be the scope of the task. The scope was wrong. And that gap — between what the agent checks and what actually needs to be true — is the failure mode that an AI-assisted workflow is structurally blind to.

This is not a bug in the agent. It is a missing layer in the workflow. The agent will verify the things you tell it to verify. It will not independently discover new categories of things to verify. That discovery is still engineering.

What belongs on the checklist

Here is what they look like.

1. Semantic output validation: check what the success means, not just that it returned success.

An API call, a function return, a system call — each has a success path and a failure path. But some systems encode failure inside success. After every external call, ask: does the returned data look like data, or does it look like an error in disguise? Check the row count. Check the structure. Scan for error keywords. If the caller received 1 row when the expected number of columns is much larger, the data is already suspect regardless of what err says.

2. Output completeness: verify that all required artifacts exist, not just that the ones that exist are correct.

Code generation produces multiple files. Some are visible in the output directory. Some should be but are not. Before accepting a generation result, enumerate the expected output files and confirm each one exists as a non-empty file. Do not accept "the generated files look correct" as a substitute for "all generated files are present."

3. Ground-truth verification: for any technical claim that can be tested by a machine, test it by a machine.

Comments can lie. File names can lie. Directory structures can lie. The CPU architecture of a .S file is not whatever the header comment says — it is whatever instructions the assembler would emit. The format of a binary file is not whatever the README claims — it is whatever the bytes at specific offsets contain. Before any agent workflow makes a design decision based on a technical assumption, verify that assumption with a command that reads the artifact directly. Do not pass claims forward unchecked.

None of these three checkpoints is dramatic. Each is small enough to be added to a task definition or a review stage without substantially changing the workflow. Together, they cover the three failure modes I have now seen multiple times: undetected failure inside a successful response, missing output from a code generator, and a false claim repeated by a toolchain artifact.

The agent is not going to ask itself "what should I also verify?" That question — what else could be wrong even when everything I checked is right — is not something an agent can generate from within its own context. It has to come from outside. It has to be designed. When you set up a multi-agent workflow, you are not just designing a pipeline for code. You are designing the boundaries of what each agent will treat as ground truth. If you do not place verification checkpoints at those boundaries, no one will.

Thanks for reading. I build tools for AI coding agents at github.com/chncaesar:

opencode-db-clean — reclaim GBs of SQLite disk space
opencode-waitfor — proper readiness checks, no more sleep loops
opencode-session-reflection — turn past sessions into workflow improvements
opencode-fleet — multi-node OpenCode orchestration

AI Fixed The Bug. Then I Found Two More Just Like It.

Antonio Zhu — Sun, 21 Jun 2026 12:55:14 +0000

I reported a bug. AI fixed it. Three days later, the same bug appeared somewhere else. I reported it again, AI fixed it again, and two weeks after that a third instance surfaced — same root cause, different location, different symptom. At some point I realized the problem was not that AI kept making the mistake. The problem was that I kept treating each occurrence as a separate incident.

The Bug

Early in the project I had established a rule: all monetary values must be stored as integers representing cents. Never floating point, never doubles, always integers. The rule existed because floating-point arithmetic on money produces invisible precision errors that accumulate silently over time. It was documented. The codebase had utility functions for converting between display values and stored integers.

Despite all of this, the same mistake appeared three times across different parts of the codebase:

// first occurrence
final amount = double.tryParse(controller.text) ?? 0.0;

// second occurrence, different feature
final price = double.tryParse(priceInput.text);

// third occurrence, different feature again
final currentPrice = double.parse(apiResponse['price']);

Each time, AI had been asked to implement a new feature. Each time, it reached for double.tryParse because that is the natural way to parse a number from text input — it's what most Dart code does, and it's what the training data overwhelmingly shows. Each time, a code review caught the specific instance that was reported. And each time, nobody checked whether the same pattern existed elsewhere.

How AI Fixes Bugs

When you show AI a bug, it focuses on that bug. It reads the surrounding code, understands the problem, and proposes a fix — and the fix is usually correct for the code it looked at. What it does not do is search the rest of the project for other places where the same mistake might exist. This is not a failure of intelligence. It is a failure of scope. AI responds to what you show it, and it does not independently decide to audit your entire codebase for related patterns.

The difference becomes clear when you compare it to how an experienced engineer handles the same situation. Someone who has worked in a codebase for months develops an instinct for where the same patterns get repeated. When they fix a bug, they often think: I've seen this structure elsewhere, let me check those places too. That instinct comes from having written and read most of the code themselves. AI does not have this map. Every conversation starts fresh, and even if you have fixed the same mistake twice before in previous sessions, AI has no memory of having seen the pattern in your codebase. It does not know to be suspicious.

The Broader Pattern

The double.tryParse issue was one example, but the same dynamic played out several more times. After fixing a race condition in one part of the UI, I found two more places with the same structure. After fixing an error message that was leaking internal exception details to users, I found four more places doing the same thing. After fixing a database write operation that was missing an invalidation call before navigation, I found five more. Each time, AI fixed the reported instance correctly. Each time, the other instances were waiting quietly.

The reason this happens more with AI than it did when I wrote most of the code myself is straightforward. When I introduce a bug, I at least know roughly where that pattern appears, because I wrote it. With AI generating large blocks of implementation that I review but don't write line by line, the mental map is thinner. And AI will consistently apply the same habits across multiple features, because it is generating from the same set of assumptions and defaults — which means when it has a bad habit, that habit is likely distributed across every place it was asked to do something similar.

What Changed

After the third occurrence of the double.tryParse bug, I changed how I approach AI-assisted fixes. Now, before I show AI the specific fix, I do one step first: search the entire codebase for the pattern.

grep -r "double.tryParse" lib/
grep -r "double.parse" lib/

I make a list of every occurrence, then fix all of them in one pass. This sounds obvious, but in practice it is easy to skip when AI is handling the fix and everything feels handled. The reported instance gets resolved, the review looks clean, and the invisible copies wait for their turn to surface.

The Role That Has Not Changed

Code generation is increasingly handled by AI. Code review is increasingly assisted by AI. Architecture can increasingly be drafted by AI. But the role that seems to be not just surviving but becoming more important is the engineer who holds the global view — who knows what patterns are repeated and where, who knows what invariants must hold across the entire system, and who, when a bug appears in one place, asks whether the same mistake exists somewhere else.

AI does not have that view. It cannot. Every session starts fresh, and every conversation focuses on what was shown. The global view of your codebase lives in your head, and when AI is writing code faster than you can track, that global view is exactly what you need to protect. When you ask AI to fix a bug, the fix will likely be correct for the code you showed it. Before you accept that fix, take a minute and search for the same pattern. That question — where else could this be? — used to be instinctive. With AI writing more of the code, it needs to become deliberate.

Thanks for reading. I build tools for AI coding agents at github.com/chncaesar:

opencode-db-clean — reclaim GBs of SQLite disk space
opencode-waitfor — proper readiness checks, no more sleep loops
opencode-session-reflection — turn past sessions into workflow improvements
opencode-fleet — multi-node OpenCode orchestration

The Design Doc Was Wrong. AI Trusted It Anyway.

Antonio Zhu — Sun, 21 Jun 2026 12:54:18 +0000

I was building a new module for a side project, and the design document looked thorough. Claude had written it, I had reviewed it, and everything seemed reasonable. One section described how to calculate a derived value from two stored fields — both multiplied by 100 to preserve two decimal places — and gave the formula:

Result = fieldA × 100 × fieldB × 100 / 10000

The logic made sense on the surface. Both fields carried 100x precision, so the divisor cancels them out. DeepSeek implemented it. The review agent verified it. I approved it. Then I opened the simulator and saw a value that should have been 1,200 displayed as 120,000.

The Formula Was Wrong By A Factor Of 100

The correct divisor was 1,000,000, not 10,000. When you multiply two fields that are each inflated by 100x, the product is inflated by 10,000x — so you need to divide by 1,000,000 to get back to base units, not 10,000. The design document had gotten this wrong, and everything downstream had faithfully reproduced that mistake.

That part was easy to fix once I saw it. What I kept thinking about afterward was the process that had failed.

Three Systems Read The Same Wrong Formula

A human engineer reading that formula would probably do something instinctive: substitute real numbers. Two quantities, each stored as integer × 100. Say fieldA = 10000 and fieldB = 1200. Multiply: 12,000,000. Divide by 10,000: 1,200. But the expected result should be 12. That doesn't add up. The error surfaces in about five seconds, not through formal verification, just through the habit of running a quick sanity check before trusting a formula.

None of the three systems in my workflow did this. DeepSeek read the design document and implemented the formula exactly as written. The review agent checked whether the implementation matched the design and confirmed that it did. I read both and approved them. Every statement was technically correct. The document was the source of truth, the code faithfully implemented the document, and the review verified the match. Nobody ran the numbers.

The Assumption I Had Been Making

After I fixed the divisor, I started thinking about what had actually failed — and it wasn't the math. The math error was trivial once I looked at it carefully. What failed was a deeper assumption I had been making about how AI-assisted development works.

I had been treating design documents as verified artifacts. The workflow in my head was:

Design Document → AI Implementation → AI Review → Human Approval

The implicit assumption embedded in this workflow was that the design document itself was correct. If it wasn't, the whole chain would faithfully reproduce the error — which is exactly what happened.

Documents Are Not Inputs. They Are Claims.

A design document is not a verified fact. It is a claim made by whoever wrote it, and in this case that was Claude. Claude is very good at generating coherent, plausible-looking technical documentation. It is considerably less good at verifying whether the math embedded in that documentation is actually correct. I had been asking it to do both things at once — reason about architecture and verify arithmetic — without recognizing that it handles those two responsibilities very differently. It did the first well. It did the second poorly. And I hadn't thought to separate them.

The fix I've settled on is simple: any formula in a design document is treated as unverified until someone has substituted concrete numbers and checked the result by hand. Not because AI gets formulas wrong frequently, but because when it does, the error propagates cleanly and invisibly through every downstream step. The formula is wrong, the implementation is wrong, the review confirms the implementation matches the formula, and everything is consistent. Everything is wrong.

The Code Did Exactly What It Was Supposed To Do

Most bugs in AI-generated code are implementation bugs — a condition is inverted, a null check is missing, an edge case is unhandled. Those are failures where the code doesn't implement the intent correctly. This was different. The code implemented the intent perfectly. The intent was wrong. That category of error is much harder to catch with code review, because code review asks whether the code does what it's supposed to do. The answer here was yes. Nobody asked whether what it was supposed to do was actually correct.

That question — is the specification right, not just the implementation — is increasingly where I think human judgment matters most in an AI-assisted workflow. AI is getting quite good at turning specifications into working code. It is getting reasonably good at catching implementation bugs. But it tends to treat the specification itself as ground truth, which means the work of questioning whether the spec makes sense in the first place is still entirely yours. AI will implement whatever you give it, with increasing reliability. The question is whether what you gave it was right.

And right now, that part is still on you.

Thanks for reading. I build tools for AI coding agents at github.com/chncaesar:

opencode-db-clean — reclaim GBs of SQLite disk space
opencode-waitfor — proper readiness checks, no more sleep loops
opencode-session-reflection — turn past sessions into workflow improvements
opencode-fleet — multi-node OpenCode orchestration

LLMs Are Lowering Coding Cost — But They May Be Increasing Debugging Complexity

Antonio Zhu — Wed, 17 Jun 2026 03:51:11 +0000

Over the last few months, I have gradually built a fairly stable AI-assisted development workflow for my side projects.

The workflow looks roughly like this.

Architecture and design are handled by Claude Sonnet / Opus. I maintain a set of engineering skills and design templates for feature planning. Once the design document is finalized, DeepSeek V4 is responsible for implementation. After coding is complete, I run an independent review workflow inside OpenCode to perform security review, architecture validation, data integrity checks, performance inspection, and test coverage analysis.

The process is structured enough that I have become fairly confident in it.

Recently, I decided to redesign the data storage architecture of one of my iOS projects.

The first version of the application was relatively simple. Data lived entirely in local SQLite storage. Users could manually export and import backup files, but data was stored unencrypted and there was no cloud synchronization.

During an AI-assisted security review, one issue was raised immediately.

Sensitive financial data was stored locally without encryption.

The feedback was correct.

This triggered a second architecture redesign.

The new design introduced AES-GCM encryption for all persisted data, and automatic backup to iCloud Drive. The goal was simple: keep user data private, avoid maintaining backend storage infrastructure, and allow users to restore data across devices without trusting a third-party server.

From a technical perspective, the stack became more complicated.

Flutter handled the application layer. SQLite remained the local storage engine. Flutter MethodChannel bridged into Swift native code. Swift then interacted with iCloud Documents API for cloud persistence.

Implementation was generated almost entirely through my AI workflow.

Everything looked fine.

Then I ran real-device testing.

The logs were clean.

JSON backup generation succeeded.

Encryption succeeded.

Flutter successfully invoked native Swift code.

Swift returned successful file write.

The application printed the following path:

/private/var/mobile/Library/Mobile Documents/...

Everything suggested success.

Then I opened Files.app on the iPhone.

Nothing.

No folder.

No backup file.

At first, I assumed iCloud synchronization was delayed.

I waited ten minutes.

Still nothing.

At this point debugging began.

I started checking the usual suspects.

Entitlements configuration.

iCloud container identifier.

Sandbox permissions.

Capability configuration.

Provisioning profile.

Everything looked correct.

I went back to AI-assisted debugging.

I used OpenCode with Claude Opus to review the native Swift implementation.

No issue found.

I switched models and repeated the review with DeepSeek.

No issue found.

I spent roughly two hours going through logs and rechecking assumptions.

Eventually I found the problem.

The Swift implementation used direct file writing.

content.write(to: url, atomically: true, encoding: .utf8)

This works perfectly in a normal filesystem.

But iCloud Documents API is not a normal filesystem.

Direct write does not properly trigger iCloud synchronization.

The correct implementation requires NSFileCoordinator.

There was a second issue.

When restoring backup on a new device, the code directly attempted file reading.

However, files stored in iCloud may not be downloaded locally yet.

The restore logic needed to call:

startDownloadingUbiquitousItem()

before attempting to read.

After fixing both issues, synchronization finally worked.

At that point I started thinking less about the bug itself, and more about the development process that produced it.

What I realized is this.

Throughout the entire development pipeline, every participant was validating code correctness.

Claude validated architecture.

DeepSeek generated implementation.

AI review agents inspected security and code quality.

I manually checked logs and exception handling.

But nobody validated system behavior.

This distinction feels increasingly important.

Code correctness and system correctness are not the same thing.

Historically, software development looked roughly like this.

Engineers write code.

Engineers review code.

Engineers understand code.

When bugs happen, engineers debug systems they understand.

But modern AI-assisted development increasingly looks different.

LLM writes code.

Another LLM reviews code.

Code volume expands rapidly.

Engineers understand less of the implementation details.

When bugs happen, debugging cost rises dramatically.

The interesting part is that none of the code involved in this bug was obviously incorrect.

The code compiled.

The APIs returned success.

The logs were clean.

Review passed.

And yet the system behavior was wrong.

I suspect this problem will become increasingly common.

LLMs are very good at generating syntactically correct code.

They are very good at code review.

But they remain weak at understanding complex runtime environments.

Especially when code interacts with operating system boundaries.

iOS sandbox behavior.

iCloud synchronization semantics.

Browser event loops.

Native runtime state.

Database isolation.

OS-level permission systems.

These are not code generation problems.

These are system behavior problems.

The industry currently spends a lot of time discussing how AI improves developer productivity.

I think we are missing the other half of the equation.

AI is clearly lowering coding cost.

But it may also be quietly increasing debugging complexity.

And as LLM-generated code becomes more common, I increasingly suspect one skill will become more valuable than coding itself.

Understanding what actually happens after the code runs.

Because in the AI era:

Code correctness does not guarantee system correctness.

A small iCloud synchronization bug reminded me of something I probably should have already known.

The faster AI helps us write software, the more important system-level verification becomes.

AI can write code.

But engineers still need to understand systems.

And when production breaks, understanding systems matters far more than generating code.

Thanks for reading. I build tools for AI coding agents at github.com/chncaesar:

opencode-db-clean — reclaim GBs of SQLite disk space
opencode-waitfor — proper readiness checks, no more sleep loops
opencode-session-reflection — turn past sessions into workflow improvements
opencode-fleet — multi-node OpenCode orchestration

DEV Community: Antonio Zhu

My OpenCode Database Was Mostly Empty Space

The misleading part of deleting data

Why OpenCode makes this visible

The useful number is freelist percentage

Why I did not want a clever cleaner

The safety sequence matters

A small tool is enough

The broader lesson

OpenCode Tool Calling Internals

Key Takeaways

Why Tool Calling Needs A Runtime Layer

How The Pieces Connect

Design Principle 1: Keep A Provider-Independent Tool Contract

Design Principle 2: Build A Runtime Tool Catalog

Design Principle 3: Put Permissions Inside Execution

Design Principle 4: Persist Tool Calls As State

Design Principle 5: Normalize At Runtime Boundaries

What OpenCode Gets Right

Where The Design Is Still Expensive

OpenCode V2 Compaction Internals

Key Takeaways

Core Design

How It Works

Trigger

Split History Into head And recent

Generate The Summary

Persist The Checkpoint

Retry From The Checkpoint

Repeated Compaction

What The Model Sees After Compaction

Configuration Surface

Strengths

Limitations

Claims The Current V2 Code Does Not Support

My Agent Kept Writing sleep Loops. So I Gave It a Better Primitive

Why agents reach for sleep

The primitive

Six Laws for Talking to AI

Data Snapshot

Law 1: The gap between knowing and writing is the whole cost.

Law 2: Assess the blast radius. Every time.

Law 3: Send the full spec. Not one sentence at a time.

Law 4: An instruction under ten characters is a puzzle.

Law 5: A bug in file A is a bug in files B through Z.

Law 6: "This" and "all" are not the same thing. Say which.

The Compounding Asset

I Reverse Engineered a Closed-Format App. Everything Was in SQLite.

Where The Data Was

What The Database Contained

The JSON Block Tree

Three Things That Wasted My Time

A Dead-End That Wasn't

What The Script Does

What Came Out

Why This Worked

I Don't Understand Embedded. I Was Still the Only One Who Could Ship It.

Seven shots

Why it couldn't stop

The briefing that wouldn't have helped

The scout

Second act: what I actually built

What a harness actually is

Your Agent Checked Everything. It Was Still Wrong.

Case 1: The retry loop that never fired

Case 2: The coordinates that never existed

Case 3: Read the instructions, not the comment

Not an Intelligence Problem

What belongs on the checklist

AI Fixed The Bug. Then I Found Two More Just Like It.

The Bug

How AI Fixes Bugs

The Broader Pattern

What Changed

The Role That Has Not Changed

The Design Doc Was Wrong. AI Trusted It Anyway.

The Formula Was Wrong By A Factor Of 100

Three Systems Read The Same Wrong Formula

The Assumption I Had Been Making

Documents Are Not Inputs. They Are Claims.

Split History Into `head` And `recent`