From d0fdd3ef2ccac0a1db3b9c44a8ee3dd571fd0072 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stig-=C3=98rjan=20Smelror?= Date: Sat, 16 May 2026 14:54:18 +0200 Subject: [PATCH] =?UTF-8?q?New=20blog=20post=20about=20Zagu=C3=A1n=20Blade?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../blog/2026-05-16-this-is-zaguan-blade.md | 253 ++++++++++++++++++ 1 file changed, 253 insertions(+) create mode 100644 src/content/blog/2026-05-16-this-is-zaguan-blade.md diff --git a/src/content/blog/2026-05-16-this-is-zaguan-blade.md b/src/content/blog/2026-05-16-this-is-zaguan-blade.md new file mode 100644 index 0000000..52d2094 --- /dev/null +++ b/src/content/blog/2026-05-16-this-is-zaguan-blade.md @@ -0,0 +1,253 @@ +--- +title: "This Is Zaguán Blade" +description: "A technical introduction to Zaguán Blade: the open-source, Rust-first AI code editor built around agentic workflows, disk-first changes, backend-authoritative state, and a protocol-driven architecture instead of another VSCode fork." +pubDate: 2026-05-16 +tags: ["zaguan-blade", "ai-coding", "rust", "open-source"] +categories: ["Engineering"] +draft: false +--- + +I did not want to build another VSCode wrapper. + +That is the simplest way to explain Zaguán Blade. + +Most AI coding tools start from the same place: take an existing editor, bolt on a chat panel, wire in a model, and slowly teach the extension how to patch files, run commands, and explain what happened. + +That approach works. It also carries a lot of inherited assumptions. AI coding tools increasingly behave like autonomous collaborators, but most editors still treat them like glorified autocomplete plugins with a sidecar chat UI. + +Zaguán Blade starts from a different assumption: if an AI agent is going to read your project, run commands, modify files, respond to diagnostics, and participate in your Git workflow, then the editor should be designed around that collaboration from the beginning. + +Blade is an open-source, MIT-licensed AI-native code editor built with a Rust backend, a React/Tauri frontend, CodeMirror 6 for editing, and a protocol-driven architecture for agentic development workflows. + +The source is available on GitHub: [github.com/ZaguanLabs/ZaguanBlade](https://github.com/ZaguanLabs/ZaguanBlade). + +## The problem is not chat + +Adding chat to an editor is easy. + +Making an AI collaborator trustworthy inside a real codebase is much harder. + +The hard problems are not the prompt box. They are: + +- what state is authoritative; +- what happens when the model edits a file; +- how streamed text, tool calls, terminal output, and diagnostics stay ordered; +- how a user reviews and rejects AI work; +- how context is selected without wasting money or losing correctness; +- how local tools run without blocking the UI; +- how the system recovers when a stream, command, or file watcher behaves badly. + +Once the assistant can act, race conditions become the product. + +That sentence is the heart of Blade. + +An AI editor is an asynchronous system wearing a developer tool’s clothes. The model streams. Tools run. Files change. Terminals emit output. Diagnostics update. Git state moves. The user may stop generation, queue another task, accept a diff, reject a file, or keep typing while all of this is happening. + +Blade exists because that system needs architecture, not just UI. + +## The design philosophy + +Zaguán Blade is built around a few opinionated ideas. + +**The backend owns truth.** +The frontend renders state and dispatches typed intents. Durable workflow state lives in Rust. + +**The file on disk is truth.** +AI edits are not imaginary preview objects floating in a side panel. They are real file changes, protected by snapshots and surfaced as diffs. + +**Reviewability is not optional.** +If the agent changes code, you should be able to see what changed, accept it, reject it, and understand how it got there. + +**AI workflow is systems work.** +Tool calls, terminal execution, context assembly, streaming, diagnostics, and Git state are part of one workflow. Treating them as separate UI widgets is how bugs leak into the user experience. + +**Rust should do the heavy lifting.** +Indexing, file operations, context assembly, tool execution, Git integration, terminal management, history, and orchestration belong in the backend where they can be fast, explicit, and testable. + +That is the product more than any single feature. + +## Why Rust is not a slogan here + +A lot of projects say “Rust-powered” because it sounds good. In Blade, Rust is where the work happens. + +The backend handles the parts of an AI editor that are easy to underestimate: + +- **tool execution:** file reads, patches, grep, symbol search, multi-file reads, batch calls, and command execution; +- **agent orchestration:** continuation after tool results, loop detection, stop handling, and queued requests; +- **context assembly:** active-file context, open-file context, token budgets, symbol-aware strategies, and project indexing; +- **language intelligence:** tree-sitter parsing, symbol extraction, outlines, diagnostics, and ZLP integration; +- **file safety:** snapshots, uncommitted change tracking, stale-read invalidation, and disk synchronization; +- **Git and terminal workflows:** status, diffs, logs, commit support, terminal sessions, PTY handling, and command completion. + +AI coding agents are I/O hungry. They read files, inspect symbols, run tests, parse command output, generate diffs, and then need to read the changed files again without seeing stale state. + +Putting that work in Rust keeps the UI responsive and makes the system easier to reason about. It also avoids turning every project-wide operation into a JavaScript extension-host problem. + +The frontend still matters. Blade uses React, Tauri, CodeMirror 6, xterm.js, Tailwind, and a semantic theme system. But the UI is not asked to be the source of truth for the agentic workflow. + +## The Blade Change Protocol + +One of the most important parts of Blade is not visible in a screenshot. + +It is the Blade Change Protocol, or BCP. + +BCP is the internal contract between the Rust backend and the frontend shell. It is versioned, typed, and backend-authoritative. The frontend sends intents. The backend acknowledges, mutates state, and emits events. + +The protocol has one canonical dispatch path for frontend-to-backend operations and one canonical `blade-event` stream for backend-to-frontend updates. Events carry causality. Mutating operations can use idempotency keys. The event stream supports single and batched transport. The runtime exposes bootstrap snapshots for hydration and recovery. + +That sounds formal because the workflow is formal. + +When a user sends a message, the assistant may stream text, emit reasoning, request tool calls, run a terminal command, modify files, update diagnostics, trigger Git state changes, and then continue. If those updates travel through ad-hoc event channels, the UI eventually lies. + +BCP is Blade’s answer: make state transitions explicit enough that the frontend can stay small, the backend can stay authoritative, and the user can trust what they are seeing. + +## Disk-first changes and real diffs + +A core Blade idea is that the file on disk is truth. + +Many AI coding tools maintain a complex split between virtual edits, previews, buffers, patches, and final application. Blade’s model is more direct: + +1. Before an AI mutation, Blade creates or reuses a history snapshot. +2. The tool writes the change to disk. +3. Blade tracks an uncommitted change. +4. The editor and file explorer refresh from the actual file state. +5. The user reviews the diff and chooses to accept or reject. + +Accepting means keeping what is already on disk. Rejecting means restoring from the snapshot. + +This sounds almost too simple, but it removes a whole category of “the preview looked right but the file was different” problems. It also aligns with how developers already reason about code: what does Git see, what does the filesystem contain, what does the editor show, and what will my tests run against? + +Blade has also invested in diff performance. Large diffs are not simply abandoned. The editor can switch fidelity levels, using simplified rendering for large changes while preserving the core review loop. That matters because diff review is not decorative in an AI editor. It is the safety rail. + +## The agent can act, but not invisibly + +Blade’s assistant can read files, search the codebase, inspect symbols, edit files, run commands, and work through multi-step tasks. + +But acting is not enough. The action has to be inspectable. + +Recent development has focused heavily on making tool execution less magical and more reliable: + +- read-only tool calls can run in parallel instead of serially; +- batch tools use all-settled semantics so one failed read does not erase the rest of the result; +- large tool outputs are preserved for model context instead of being truncated into useless summaries; +- file mutations invalidate cached reads so the next tool sees the new content; +- successful AI edits are tracked before editor refreshes; +- command execution uses explicit start/exit sentinels instead of guessing from shell behavior. + +For users, the goal is simple: when the AI says it changed something, the editor should show what changed. When it runs something, you should see what ran. When it proposes risky work, there should be approval and review points. + +## Context is both cost and correctness + +Vibe coding can get expensive because context is expensive. + +Sending too much code wastes money and slows everything down. Sending too little code makes the model hallucinate or patch the wrong abstraction. + +Blade treats context assembly as a backend concern, not a prompt-concatenation afterthought. The context layer can reason about active files, open files, symbol definitions, references, imports, related types, and token budgets. + +Project indexing follows the same philosophy: keep useful workspace knowledge available, update it as files change, and avoid wasteful disk churn. ZLP, the Zaguán Language Protocol, extends that with language-aware operations such as structure, diagnostics, symbol search, outlines, graph-style queries, and post-edit validation. + +This matters because AI-generated changes should not be judged only by whether the text looks plausible. They should be checked against the project’s structure, symbols, diagnostics, and actual file state as quickly as possible. + +## Chat is a timeline of work, not just bubbles + +A lot of AI coding UX is still built around message bubbles. But once the assistant can run tools, inspect files, stream reasoning, ask for approvals, and modify the project, a chat transcript becomes a work log. + +Blade’s chat system has been evolving in that direction. + +Recent commits show substantial work on stable chat rows, chat projections, compact work logs, activity deduplication, virtualization, scroll behavior, copy behavior, and tool/text ordering. This is not cosmetic polish for its own sake. It is an attempt to make long-running agent work understandable. + +The important questions in an AI coding session are not only “what did the model say?” They are: + +- what is it doing right now? +- what files did it inspect? +- what commands did it run? +- did those commands pass? +- what changed? +- what can I accept or reject? +- where did the plan become implementation? + +Blade’s chat panel is moving toward answering those questions directly, without forcing the user to reverse-engineer state from raw model text. + +## The expected pieces still matter + +The core differentiators are protocol, authority, reviewability, and workflow semantics. But an editor still needs the expected pieces. + +Blade supports the hosted Zaguán AI backend, but it also supports local and OpenAI-compatible servers such as Ollama, llama.cpp, LocalAI, vLLM, and other `/v1`-compatible runtimes. Local support includes streaming, model discovery, custom prompt files, Ollama support, and model-specific handling such as Gemma 4 reasoning behavior. + +Git is part of the review loop too. Blade includes changed-file views, diffs, staging and unstaging, commit history, push support, AI-assisted commit message generation, and a multi-lane Git graph. It also has explicit safety work around project-local `.zblade` metadata so conversation and project state do not accidentally leak into commits. + +There is a broader Rust-native Git direction here as well. The migration toward `gix` starts where the risk is low and the payoff is high: repository discovery, remote URLs, logs, status snapshots, and commit preflight. Mutating porcelain operations can stay on the Git CLI until replacing them is clearly safer. + +The terminal is similarly integrated. An AI coding assistant that cannot run commands is limited. An assistant that can run commands without good terminal semantics is dangerous. Blade supports persistent terminals, agent-owned sessions, command approvals, blocking and non-blocking commands, explicit completion sentinels, stop controls, and interactive PTY sessions when user input is needed. + +## A product for vibe coders and serious teams + +There is sometimes a false split in AI coding tools: either they are for fast, loose prototyping, or they are for disciplined engineering teams. + +Blade is trying to occupy the useful overlap. + +For vibe coders, Blade offers the fun part: ask for a feature, reference files with `@`, let the assistant explore, let it patch, keep momentum. + +For experienced developers and tech leads, Blade exposes the necessary control points: + +- file diffs; +- history snapshots; +- accept/reject flows; +- terminal approvals; +- Git status; +- diagnostics; +- local model configuration; +- protocol-driven state; +- open-source inspectability. + +The point is not to slow the AI down. The point is to make the AI’s work reviewable enough that you can move quickly without surrendering the project. + +## Built in the open + +Zaguán Blade is open source under the MIT license. That is important for an AI coding editor. + +Developers should be able to inspect how files are changed. Teams should be able to audit how local project metadata is stored. Contributors should be able to trace protocol events, understand tool execution, and improve the editor without waiting for a proprietary vendor roadmap. + +The hosted Zaguán AI backend is a service, but the editor itself is yours to use, modify, build, and distribute under the MIT license. + +You can find it here: [https://github.com/ZaguanLabs/ZaguanBlade](https://github.com/ZaguanLabs/ZaguanBlade) + +## Where Blade is today + +Blade is in active development. The repository history makes that obvious. + +The recent work tells a clear story: + +- composite tools, request queues, terminal reliability, Git graph work, and `.zblade` filtering; +- streaming fixes, tool-call ordering, planning mode, chat virtualization, and reasoning display; +- symbol databases, graph tools, ZLP integration, Go and PHP editor support; +- event flushing, file-state sync, uncommitted change tracking, diagnostics in chat context, and large tool-result preservation; +- CodeMirror ownership, diff performance, chat timeline stability, semantic theming, and UI coherence. + +That kind of changelog is not always glamorous, but it is what real tools are made of. The difference between a demo and a daily driver is usually hidden in fixes like “do not lose queued messages when stop is pressed,” “do not show stale file reads after a patch,” “do not reset the cursor on content sync,” and “do not truncate the tool result the model needs to continue.” + +Blade has a lot of that engineering scar tissue already. + +## What makes it different + +If I had to summarize Blade’s identity, it would be this: + +Zaguán Blade is an AI-native code editor where the agent is not an extension bolted onto the side. The agent, editor, terminal, Git integration, file history, diagnostics, and project context all participate in one workflow. + +It is still a code editor. It still has files, tabs, syntax highlighting, a terminal, a file explorer, Git controls, and settings. But those pieces are arranged around a new center of gravity: AI as an active collaborator that can inspect, act, and be reviewed. + +That requires more than a prompt box. It requires protocols. It requires snapshots. It requires event ordering. It requires fast local indexing. It requires terminal semantics. It requires careful context handling. It requires boring, stubborn correctness work. + +That is what Zaguán Blade is trying to build. + +## Try it, fork it, break it, improve it + +If you are curious about AI coding tools, Rust desktop apps, agentic workflows, local model integration, CodeMirror-based editors, Tauri, or protocol-driven frontend/backend architecture, Blade is worth reading even before you run it. + +And if you do run it, remember what it is: an actively developed, open-source AI editor that is still moving quickly. + +Install it. Build it from source. Point it at a project. Try it with a hosted model or a local OpenAI-compatible server. Watch what it does. Review the diffs. Open the terminal. Inspect the protocol docs. File issues. Send patches. + +Zaguán Blade is not another VSCode fork. + +It is an attempt to build the AI coding workbench from first principles.