Rust | Francis Du

wcode 0.8: I Started Treating the Repository as an Engineering Digital Twin

Sat, 19 Sep 2026 15:33:00 +0800

By the end of 0.7, wcode could already give an agent bounded repository context, edit files with SHA preconditions, run verification, and keep Design State, Software Graph, Evidence, and Reconciliation around the work.

But when I used it myself, one gap was still obvious:

An agent being able to operate a repository does not mean a human can quickly understand the state of that repository.

I still kept going back to an IDE to inspect the tree, callers, tests, and Git changes, then back to wcode for verification and evidence. Each view was useful, but they were not really one engineering model.

That became the main idea behind 0.8.

I did not want another batch of MCP tools. I wanted to pull the existing pieces toward one thing:

an Engineering Digital Twin of the repository that can be inspected, queried, revisited, and explicit about the precision of its evidence.

The current release is v0.8.1. v0.8.0 built the main structure; v0.8.1 tightened the Decision Plane and Jev boundaries immediately afterwards.

A Code Graph is only useful if it admits what it knows#

I have always been a little suspicious of code graphs.

The easy version is to draw every file, symbol, and module as a large connected ball. It looks impressive and becomes difficult to use almost immediately.

The questions I actually care about are more boring:

Where did this relationship come from?
Was it observed by Tree-sitter or confirmed by LSP?
Was it declared in Design State or seen at runtime?
Does it belong to the current graph revision?
Is it related to the current Working Tree change?
Is there proof or a test behind it?

In 0.8, Code Graph became a workbench inside Engineering Architecture rather than another top-level workspace.

Architecture remains the primary model. The graph is a deeper observable layer.

From a symbol, I can now inspect bounded callers, callees, references, dependencies, implementation ownership, tests, requirements, and verification/proof context.

Calls, Impact, and All Evidence modes all have hard depth, node, and edge limits. The UI uses upstream → focus → downstream lanes instead of allowing an unbounded node-ball.

More importantly, every retained relation keeps its provenance and precision.

Declared, syntax, semantic/LSP, runtime, deterministic, and heuristic evidence do not get flattened into a single vague confidence number.

I would rather see “this edge is syntax-derived” than have a clean graph hide uncertainty from me.

Graph History is part of the same view#

The Code Graph can also open a stored Graph History snapshot.

That gives me read-only graph time travel: I can ask whether a caller, dependency, or proof relationship existed in an earlier graph revision without rebuilding the repository or mutating current state.

For an agent this is useful context. For me it is mostly an engineering history tool.

The Observatory is quieter now#

The old Observatory could become noisy because a browser trying to get fresh state could trigger groups of relatively heavy snapshots.

That was technically correct and operationally annoying.

In 0.8, each Workspace allows at most one background Observatory rebuild at a time. Cached responses are revision-stamped and explicitly say whether the state is cached, current, or refreshing.

The browser renders useful cached state first and uses bounded lightweight probes instead of fanning out more heavy snapshot work.

I also reworked the information hierarchy.

Project Pulse and state are first-glance information. Metrics, relationships, and timelines come next. Evidence and inspectors are the third layer.

Stale, Unknown, Inconclusive, Failed, and Unverified are not allowed to look like current passing proof.

That sounds like a UI detail, but for an engineering control plane it is a trust boundary:

the interface should never look more certain than the evidence underneath it.

Why I finally started using the phrase Engineering Digital Twin#

I avoided that phrase for a while.

If all I had was a code index with graph edges, “Digital Twin” would feel inflated.

0.8 is the first version where the name feels closer to what the system is actually doing:

Design State
    ↓
Implementation ownership
    ↓
Syntax / Semantic / Runtime relations
    ↓
Working Tree changes
    ↓
Drift / Risk / Impact
    ↓
Verification / Evidence

This is not a second mutable project database.

Source, Git, Design State, runtime providers, and Evidence remain their own sources of truth. The Digital Twin is a read-only engineering view that composes them without pretending they have the same precision.

That distinction matters. The moment a twin becomes a second mutable project state, I have created a new consistency problem instead of solving one.

The Decision Plane became a real subsystem in 0.8#

The other large piece of 0.8 is the Decision Plane.

Coding agents make many small decisions that do not necessarily require the main reasoning model:

Is the current context sufficient?
Should retrieval continue?
Are semantic relationships necessary evidence before a safe edit?
Should verification become deeper?
Is this state clear enough to act, or should it abstain?

0.8 represents these as provider-neutral structured Probability, Choice, and Score signals.

But the important part is not that I can plug a smaller model into the path.

The important part is that the Decision Plane still does not own the deterministic engineering boundary.

Authorization, Workspace boundaries, SHA preconditions, Evidence, risk-derived verification, and human approval stay deterministic.

A provider can say “retrieve more.” It cannot say:

Confidence is 0.93, so skip the SHA check.

That would defeat most of the work I have done on wcode.

Engineering Fitness stopped using wcode’s own readiness as truth#

A Decision Plane is not useful if it grades itself.

For context sufficiency, 0.8 calibrates against independently authored Engineering Fitness Gold instead of using wcode readiness fields as the answer.

I care about four different things:

Did retrieval find the required identity?
Did the agent receive the complete source body?
Is the SHA fresh?
If the task is actually writable, are all required edit inputs present?

On the 60-case model-free diagnostic used for the 0.8.0 release, the 1K cold and warm runs both reached 100% required identity recall, complete-body recall, and fresh-SHA recall. All 58/58 eligible writable cases received the required edit inputs.

The decision baseline had a Brier score of 0.018846, with zero false stops and zero false continues.

I do not read those numbers as “context engineering is solved.”

They are a baseline I can use when I change retrieval, ranking, budgets, or the Decision Plane. At least I can detect when I have broken a basic property without needing a large reasoning model to judge the result.

Jev got narrower again in 0.8.1#

v0.8.0 already supported comparing a baseline Decision Plane provider with a candidate on the same request.

In v0.8.1, I cleaned up the naming:

the local model-free layer is the Decision Plane;
the external semantic provider is Jev;
the main large model is the Reasoning Model.

More importantly, I rewrote the questions.

A broad question such as:

Would semantic navigation be useful?

is almost always answered “yes” in a coding task. Looking at more relationships is usually useful.

The narrower 0.8.1 boundary is closer to:

Are semantic relationships necessary evidence before a safe edit?

Choice criteria now define positive and negative boundaries, and other_review exists for states that should abstain instead of pretending to be edit-ready.

The current Agent Context Jev question set is wcode.agent_context@3.

Jev is increase-only#

Jev may ask for more retrieval, semantic navigation, deeper verification, or more reasoning.

It may not reduce deterministic work.

A Jev edit_then_verify recommendation is suppressed unless the deterministic baseline already selected the same action. Unknown edit readiness goes to other_review rather than silently becoming edit-ready.

If the Jev advisory block would overflow the Agent Context budget, the advisory is dropped first. Source, SHA preconditions, tests, and deterministic risk evidence keep priority.

That gives me a failure mode I am comfortable with:

if Jev disappears, wcode loses advice; it does not lose safety.

Shadow A/B is more useful to me than replacing the baseline#

I did not make Jev the Decision Plane authority.

The baseline and candidate see the same immutable DecisionRequest, and wcode records shared and missing signals, probability and score deltas, Choice disagreements, shape mismatches, and safety-policy violations.

That is closer to Shadow A/B.

I want to see where a provider disagrees with the deterministic baseline before I give it any authority over runtime behavior.

It is slower than “API connected, enable it by default,” but much easier to reason about.

Repository scanning finally shares Ignore semantics#

This is less visible than the Digital Twin, but it has a large effect on everyday use.

Source scanning, search, indexing, status, and subspace discovery used to have slightly different traversal paths. That creates silly cases where one subsystem ignores target and another walks straight through it.

0.8 moves repository-wide walking onto shared ignore-aware behavior.

By default it respects .gitignore, .ignore, Git info exclude, Git global exclude, and protected paths. Heavy generated trees such as target, node_modules, caches, and common build outputs are pruned before traversal.

Explicit intent still wins. If I directly ask wcode to read or search an ignored path, bounded operations can still access it.

Performance rules should not silently override an explicit user request.

The TUI became more task-first#

I removed some permanent engineering telemetry from the main TUI.

Wide terminals now use a 70/30 layout: Workspace Activity is the main canvas, while engineering and connection state live in a compact control rail.

The rail is reduced to four independent lines:

ARCH
DRIFT
PROOF
MODEL

Medium and narrow terminals drop the permanent Engineering Pulse entirely so task rows keep the space.

The TUI is increasingly about three questions:

What is the agent doing now?
Is it blocked by authorization, verification, or runtime state?
When do I need to intervene?

Detailed architecture and proof still live in the Engineering Console.

0.8.1 also fixed two “looks correct” UI bugs#

These were good examples of why observability has to be part of correctness.

Code Graph requests are parameterized by query, mode, depth, and snapshot. A late response is not safe to render just because it succeeded; all four request semantics must still match the current view.

The Access page has a similar rule. Workspaces, commands, and authorizations are now published atomically. If one response fails shape validation, the group remains Unknown instead of showing a partially truthful state.

The dangerous UI is not the one that crashes.

It is the one that displays a coherent-looking answer made from mismatched state.

The old boundaries are still the boundaries#

wcode has changed a lot between 0.3 and 0.8, but I have not changed the basic rules I started with:

Workspace Root remains a boundary;
edits remain SHA-bound;
Full Access is an explicit operator decision;
the Decision Plane cannot grant authorization;
Jev cannot lower verification;
cancellation is not rollback;
verification evidence belongs to an exact revision.

The Engineering Digital Twin is read-only observability. A graph relationship does not grant permission to mutate anything.

The release was larger than I expected#

From v0.7.6 to v0.8.0, the Git diff touched 135 files, about +7,364 / -775 lines.

I originally thought 0.8 would mostly be “Code Graph plus a better Observatory.”

Instead it pulled on the whole path:

Repository scan
    ↓
Context
    ↓
Graph / Digital Twin
    ↓
Decision Plane
    ↓
Edit boundary
    ↓
Verification
    ↓
Evidence
    ↓
Human observability

That is why I ended up calling the release Engineering Digital Twin rather than Code Graph.

The graph is only one entry point into it.

The current release is 0.8.1#

v0.8.0 was the Engineering Digital Twin release on September 19. Later the same day I shipped v0.8.1, tightening Jev decisions, naming, and WebUI state truthfulness.

The detailed release notes are here:

If I had to reduce 0.8 to one change, it would be this:

wcode used to focus mainly on helping an agent operate a repository safely. In 0.8, I started trying to make the human and the agent look at the same evidence-aware engineering state.

That part is nowhere near finished, but the direction finally feels coherent.

How wcode Grew Past the MCP Bridge I Started With

Sat, 12 Sep 2026 05:41:00 +0800

GitHub ↗Docs ↗

I did not start wcode because I wanted to build another coding agent.

The first idea was simple: use the models already available in web products for coding, while giving them a way to work with the real repository on my machine. The model was in the browser; the code was local. Anything beyond a tiny question meant copying files, uploading an archive, explaining the directory structure, and doing it again as soon as the repository changed.

The first version of wcode was therefore a bridge. It let a browser-based model search local files, read code, make changes, and run checks through tools. MCP later gave that connection a more standard shape, but getting the connection to work was not the part that kept me working on the project.

Once the bridge worked, another problem became much harder to ignore: how was the agent actually reading the codebase?

A lot of code-CLI discovery starts with grep, ripgrep, file listings, and shell-style repository scans. There is nothing wrong with that. I use those tools all the time, and for finding a string, filename, or obvious symbol they are often exactly the right choice.

The problem is what happens next.

A search returns matching text. The model still has to reconstruct which definition matters, whether two same-named symbols are related, who calls what, what a change might affect, which test covers the behavior, and whether a relationship is merely plausible from text or actually resolved by a language-aware tool.

Stronger models can reconstruct more of that from snippets, but the repository-understanding work is still being pushed back into the context window. As the codebase grows, repeated names, cross-module calls, generated code, and incomplete slices make that reconstruction increasingly fragile.

That is where wcode changed direction. I stopped only adding commands and started treating repository reading as its own engineering problem.

Then I started working on how the agent reads the repository#

wcode still uses text search. Cheap localization should stay cheap. If the question is “where is FooConfig?”, starting a semantic pipeline just to look sophisticated would be wasteful.

But once the question becomes “who calls this?”, “what implements it?”, “what does this rename affect?”, or “which test proves this behavior?”, matching text is no longer enough. wcode can use Tree-sitter for stable syntax structure, upgrade to a warm LSP session when cross-file semantic relationships matter, and combine that with the current Git state, Design State, tests, and known graph relationships.

What reaches the model is therefore not only a pile of source snippets. It can be a bounded task context containing relevant symbols and exact ranges, references or calls, associated tests, current changes, project constraints, and the provenance, precision, and revision of those facts.

A rough way to think about the two paths is:

Common text-discovery loop: task → grep/ripgrep / file slices → matching text → model reconstructs the code relationships.
wcode repository-reading path: task → cheap localization → syntax/semantic relationships when needed → task-ready evidence → model reasons over context with explicit provenance and precision.

wcode is not trying to replace grep. Search is often the right tool for exact localization; stronger structure and semantics are added when the task asks about relationships, impact, or proof.

Take a routine change such as adding a status filter to a list endpoint. Searching the endpoint name may find the handler, but that does not guarantee the parameter definition, query construction, callers, and regression tests are all in view. agent_context gathers the implementation, tests, project guidance, and verification entry points that look relevant to the current task. If the task explicitly needs callers, references, implementations, or impact, readiness can then direct the agent to semantic navigation.

That distinction matters to me: not every question should pay for the heaviest analysis, but the agent should know when search has stopped being enough. wcode reports only the precision it actually has. Tree-sitter syntax is not presented as compiler semantics, and an unavailable LSP does not become a fake claim that every caller was found.

Making an edit without losing someone else’s work#

Back to the filter example. The agent reads a file and starts preparing a change. Meanwhile, I might edit the same file.

Writing the agent’s older version back could lose my work. To prevent that, wcode returns a SHA when it reads a file—a fingerprint of the contents. An edit must carry that fingerprint. If the contents have changed, the old edit is rejected and the agent has to read again.

Operations also need an appropriate scope and order. Reading several unrelated files can happen in parallel. Two changes to the same file need coordination. After editing, review_changes examines the diff and verify_project runs the project’s checks.

At the end of a task, I want to know what changed, what was checked, and what remains uncertain.

The documentation calls this an engineering control plane. In everyday use, it means keeping the files, operations, and check results connected. The next task can inspect what happened, even if I switch models or clients.

A passing test belongs to a particular change#

The filter is implemented and its tests pass. Then the parameter parsing changes, but the tests are not run again. The earlier pass describes the earlier code.

wcode associates check results with the code and design revisions they ran against. Its interface distinguishes finding a corresponding test from executing it, getting a pass, and having a result that still applies to the current version.

The checks also need to answer the right question. This blog is built with Hugo. After editing Markdown, I need an actual build to establish that both language pages were generated, their images exist, and the public URLs stayed intact. Reading the text cannot establish those things.

A code project needs its corresponding build, tests, or other project checks. Higher-risk work can use more extensive verification when configured. The diagram shows available lanes; it does not mean every change must run all of them.

The project and verification plan determine which checks are required. An optimistic review cannot replace missing execution results.

Successful work from an earlier task can help locate relevant files next time. Its test results cannot be reused indefinitely. That is one of the details I want wcode to keep track of.

Giving project rules somewhere to live#

Some requirements are invisible when looking at one function or file.

On this blog, Chinese pages stay at the root and English pages live under /en/. The photography Gallery has its own page and scripts. Editing an article should preserve its public address. An assistant unaware of those rules could finish the immediate task while changing something else I wanted to keep.

wcode can record these requirements under .wcode/ in the repository. The documentation calls this Design State: requirements, components, constraints, and acceptance criteria. Later tasks can retrieve them while inspecting the project or assessing a change.

The Engineering Observatory opens on its architecture view. It shows which source belongs to a component, related requirements, and dependencies found by the analysis tools.

These records need maintenance as the project changes. A diagram does not establish that an architecture is correct. It gives me a place to compare information that would otherwise be scattered across files and conversations.

Deciding what the assistant can access#

wcode works within a selected Workspace: the project scope available for this task. File operations check paths, protected locations, and unsafe links. Edits to existing files also check the content fingerprint.

Commands have their own rules. Common development commands with bounded behavior can run directly. Operations requiring additional trust go through local authorization, where the operator can inspect and allow the request. Broader session grants and Full Access also require an explicit operator choice.

Connecting to wcode does not grant permission to run arbitrary commands or access arbitrary files.

A local client can start wcode over stdio. A remote client uses OAuth to connect to a running service. Both reach the same repository tools. File operations happen on the repository’s machine; with a cloud model, code that is read still reaches the corresponding client as a tool result.

These are controls at the repository and tool layer. They are not equivalent to an operating-system sandbox.

What the interface is useful for#

I mainly use the interface to see where the work has got to.

The terminal dashboard shows connections, the selected project, tasks, and authorization requests. W opens the Engineering Observatory; O opens Setup Hub. The Observatory contains architecture, current changes, requirements, project files, and verification records.

When a task slows down, Task activity is useful. It separates time spent waiting in a queue from time spent executing, and shows child processes and resource use. Waiting for capacity and running an expensive command are different problems.

wcode limits concurrency separately for CPU work, file I/O, and child processes. Independent work can overlap while leaving the machine some room. The useful balance still needs to be checked against real tasks; a concurrency number alone says very little.

Trying it on a familiar project#

If you already have an AI coding assistant you like, start with a project you know. A small change makes it easier to judge whether the assistant found the right code and whether the result makes sense.

On macOS or Linux, install a release with:

curl -fsSL https://raw.githubusercontent.com/francis-du/wcode/main/install.sh | sh

Windows installation is covered in Getting Started. Then run this from the project directory:

wcode setup

Choose global or project configuration and reconnect the agent. For local stdio use, the client starts the process. Run wcode when you want the terminal dashboard, web interface, or remote access. Remote clients use the current MCP address displayed by the program and complete OAuth; the integration guide has the steps.

There is no need to configure every feature for the first task. Start with the smallest useful loop:

Have the agent locate one implementation.
Change one behavior.
Run the relevant checks.
Read the diff yourself.

Then add the project rules you find yourself repeating under .wcode/.

The source is on GitHub, with installation and integration details in the project documentation. Your chosen service still provides the model. wcode handles the connection to the repository and the work on that side.

wcode 0.6.2: What 32 Tool Slots Were Hiding

Sat, 12 Sep 2026 05:35:00 +0800

I spent several days watching wcode sit at 32 tool slots with decent peak occupancy while a few real tasks still felt slow.

After tracing the queues underneath that number, I stopped treating slot utilization as a performance signal. A slot only says the request got in. CPU work, file I/O, compilers, Git probes, and language servers can still be waiting somewhere deeper.

0.6.2 grew out of that debugging pass. I changed the resource model, then fixed a few other places where the runtime was reporting something cleaner than the underlying state really was.

Tool slots are not CPU cores#

The outer SLOTS counter only means a tool request has been admitted. It does not tell you whether a CPU worker is executing useful code, a filesystem operation is waiting on storage, or a child process is queued behind another compiler.

0.6.2 makes those layers more explicit:

Tool admission
      ↓
Foreground CPU budget
      ↓
Bounded file-I/O workers
      ↓
Child-process / Git probe queues

Foreground CPU parallelism is bounded by hardware, memory-derived limits, a small runtime ceiling, and request concurrency. Blocking work has its own bounded capacity. Independent file modifications use a shared I/O pool. Fixed, read-oriented Git probes have a separate queue from heavier repository processes.

Starting twenty compilers at once is usually a good way to make one workstation slower, so those inner limits stay deliberately small.

I removed an optimization that benchmarked worse#

One experiment moved more read work onto a wider thread pool. It looked like the kind of change that should increase throughput.

In the local paired workload it was slower, so I reverted it.

I kept the revert. A wider pool is only an optimization if the paired workload actually improves.

I also avoided putting an “X% faster” number on the release. Repository size, storage, dependency shape, language servers, and compiler behavior move the result too much for one number to mean much.

Keep lightweight tools alive under command pressure#

There is another failure mode in agent runtimes: a queue of expensive commands consumes every outer tool slot, then the agent cannot even perform a lightweight read or status query needed to understand the queue.

Execution-class requests in 0.6.2 pass through an additional admission layer before taking the global tool capacity. With the normal 32-slot configuration, command-like work cannot consume all 32 slots; a small amount of capacity remains available for non-execution tools.

This does not guarantee fixed latency under every kind of saturation. It does prevent one very avoidable form of self-starvation.

A compiler location should beat a repository-wide search#

Performance is also about doing less work.

Suppose the model already has this diagnostic:

error[E0308] at src/runtime/harness/context_budget.rs:33:9

Older retrieval paths could still begin with broad repository symbol discovery and only later prioritize the explicit location.

That ordering is backwards.

agent_context now recognizes bounded file-and-line anchors first. It resolves them through the workspace safety boundary, preserves the source text and file SHA needed for safe editing, and can defer unnecessary repository-graph expansion for simple location-driven tasks.

Cross-file callers, impact analysis, architecture questions, and explicit product-scope queries still use the deeper graph and semantic paths.

So a file-and-line diagnostic now wins the first retrieval step. The broader graph only comes in when the task actually needs it.

Multiple agent branches can ask about the same uncached file at nearly the same time.

Without coordination they can all notice the cache miss and independently build the same index.

0.6.2 shares an in-flight index build for the same workspace and file. Different files can still build independently. Invalidation updates the build generation so an old result that finishes late cannot quietly repopulate stale state.

I did not add incremental parsing here. This change only deduplicates the same cold index build.

`symbol_context` now checks that its own pieces agree#

A more serious version of the same problem appears when a symbol index and the source text come from different file revisions.

A response can look perfectly structured while combining an old signature with new source lines.

symbol_context now checks the source identity used by the symbol fact against the content it is about to return. If the index is stale it can refresh once. If the file keeps changing and a stable answer cannot be produced, the operation fails explicitly.

I would rather return “unstable source” than a polished contradiction.

Complete verification plans or no verification plan#

A mixed-language repository can derive a surprisingly large set of checks.

One older path silently limited a plan to the first eight checks. That is dangerous because the executed prefix can still look like a complete verification report to a higher layer.

0.6.2 constructs and sorts the complete plan first, with a bounded maximum of 32 checks. If the plan exceeds that bound, the request fails before dispatch. It does not execute a partial prefix and call it full verification.

Within a request, verification history also shares a source/design revision snapshot instead of repeatedly rescanning the same state for every planned check.

Evidence remains scope-aware: a narrow success cannot erase a broader failure, and missing or truncated evidence is not interpreted as a pass.

Verification can be a durable MCP task#

verify_project now reuses the existing persistent Tasks runtime when the client advertises the MCP Tasks extension.

The server can persist the task and return a taskId before waiting for the full verification workload. The authenticated owner can query that same task later, even after the creating request has ended.

A dropped connection does not cause automatic replay. A restarted runtime does not pretend an interrupted operation completed. Already-started blocking work is not advertised as transactionally rollbackable.

That distinction matters once commands can have side effects. A missing response tells me nothing about whether the command already started or finished.

Configuration needed to become smaller again#

As wcode accumulated resource controls, the advanced CLI became useful for debugging but unfriendly as a default setup surface.

0.6.2 introduces three practical performance profiles:

balanced
fast
light

You can preview before writing configuration:

wcode setup --performance fast --dry-run
wcode --show-config

Advanced overrides still exist, but a normal user no longer needs to understand every internal queue before choosing a sensible starting point.

The release also adds:

wcode help-all
wcode help-all setup
wcode help-all --json

This catalog is generated from the real CLI parser, including advanced options, aliases, defaults, and enumerated values. Normal help stays compact; complete discoverability has a separate entry point.

I cleaned up the Observatory first screen#

The Project Observatory received another structural pass.

The first screen now separates active execution, pending approvals, worktree changes, and verification evidence that is valid for the current revision. Architecture navigation starts from searchable component cards and a detail inspector, while Design / Implementation / Overlay graphs remain available for deeper inspection.

Fast activity refreshes are separated from slower project refreshes. Hidden pages stop polling. Shared process resources are labeled separately from work that belongs to the selected project. An unavailable sample is not rendered as zero.

The main rule for the UI is boring: if wcode did not sample something, it should say unknown instead of drawing a zero.

What I kept from this release#

I now check a few distinctions explicitly when changing the runtime:

slot count is not throughput;
a mapped test is not an executed test;
task completion is not a passing verification result;
a missing response is not proof that nothing happened.

0.6.2 is mostly a pile of fixes around those details. None of them is a headline feature, but they make the runtime easier to trust when a coding session gets long.

The code is at github.com/francis-du/wcode, and the current documentation is at wcode.francis.run.

wcode: How I Connected Web AI to a Local Repository

Sat, 12 Sep 2026 05:33:00 +0800

Documentation ↗GitHub ↗

I use several AI products in the browser. The annoying part starts when I want one of them to work on a repository that is already on my machine: copy files into chat, upload an archive, switch clients, or configure another API key.

wcode started as my way around that friction. It is a Rust runtime that exposes a local workspace through MCP, with OAuth, file boundaries, code indexing, guarded edits, and command policy on the local side.

The first version mostly stopped there. After I started using it for real edits, I spent more time on repository state than on the bridge itself.

The questions I kept hitting were:

What part of the repository does this task belong to?
Which facts are syntax, and which are compiler-grade semantics?
Which files are safe to edit right now?
What changed since the last verification?
Did the test result belong to this exact revision?
Can another model resume the work without rereading the chat?

Most of the current wcode work comes from those questions.

The boundary I keep in wcode#

wcode does not choose your model and it does not need to own the conversation loop.

A simplified path looks like this:

Web AI / Coding Agent
        │
        │ MCP
        ▼
┌───────────────────────────┐
│           wcode           │
│                           │
│ Auth / Workspace Boundary │
│ Task-ready Context        │
│ Tree-sitter + LSP         │
│ Editing + Command Policy  │
│ Verification + Evidence   │
└─────────────┬─────────────┘
              │
              ▼
        Local repository

I change models and clients much more often than I want to change repository permissions or edit safety. Keeping those two layers separate has worked well for me.

For a local coding client, wcode can run over stdio. For a web client, it can expose a remote MCP endpoint with OAuth. Both transports reach the same workspace, tool harness, software intelligence, and verification layers.

A path in a prompt is not authority#

The most important design rule in wcode is that model-visible data does not grant capability.

If repository text says “read ../../.ssh”, that is still outside the workspace. If a tool output contains a shell command, that does not make shell execution legal. If a model says a command is safe, that does not approve it.

File access is bounded by the configured workspace. Writes use revision preconditions. Protected paths, symlink escapes, stale writes, and unsafe command forms are rejected below the model layer.

Commands that are valid but risky can require a precise approval. The approval is tied to the actual operation:

workspace
program
arguments
working directory

Approving one cargo test --locked is not permission to run an arbitrary shell, publish a package, mutate host-wide tooling, or execute a different command later.

I prefer this middle ground to the usual two settings: “ask me about everything” and “full access.”

Cheap syntax first, semantic depth when it matters#

Repository understanding also has layers.

Tree-sitter is excellent for cheap structural work: outlines, definitions, ranges, and syntax-level relationships. It is fast and does not require starting a project semantic environment.

But syntax is not a type system.

For cross-file references, implementations, call hierarchy, and similar relationships, wcode can use first-party Language Server sessions. These results are tagged by provider and precision, and they are tied to source revisions so stale semantic facts do not quietly survive code changes.

That distinction sounds small, but it prevents a common failure mode in agent tooling: presenting a heuristic result as if it were authoritative because it makes the output look smarter.

If wcode only knows something syntactically, it says so.

`agent_context` packages the task I am about to run#

A coding agent does not only need “more context.” It needs the right context in a form that helps it decide what to do next.

agent_context therefore tries to produce a bounded, task-ready package. Depending on the task it can include:

repository guidance;
product or architecture scope;
target source and exact file SHA;
relevant tests and design constraints;
semantic-provider readiness;
active work items;
a minimal-change strategy;
candidate dependency lanes and parallelism guidance.

I use it to avoid the usual first few tool calls where an agent rediscovers the repository layout before touching the actual target.

When an error already points to src/runtime/foo.rs:120, the newest retrieval path starts there instead of paying for a broad repository search first. When the task is genuinely cross-file, the deeper graph and semantic paths remain available.

Verification is attached to a revision#

“Tests passed” is not a durable engineering artifact.

Which tests? On which source revision? Did the design state change between the test and the final edit? Was it a quick check or a full project gate? Was the output truncated? Did another process modify the repository while verification was running?

wcode records verification evidence with provenance and revision identity. Before a result is recorded as current proof, the relevant source and design state are checked again. If the repository changed, the old result is not promoted to the new revision.

The Project Observatory also distinguishes between a test that is mapped to a requirement and a test that was actually executed and passed for the current revision.

I notice this most after a long session, when there have already been enough edits that “tests passed earlier” is no longer useful.

Parallelism is a dependency problem#

Recent versions also changed how I think about performance.

A large concurrency number is not the goal. Useful parallelism comes from independent work.

Reads of unrelated files can overlap. Independent discovery can overlap. A test that depends on a generated file cannot start early just because a slot is free. Two conflicting writes should not race merely to keep a dashboard busy.

wcode’s parallel scheduler is dependency-driven and completion-driven: a task can proceed when its own prerequisites are complete, without waiting for an unrelated slow branch in the same conceptual layer.

The runtime separately accounts for outer tool admission, CPU work, bounded file I/O, and child-process queues. This prevents “32 slots” from being mistaken for “32 useful CPU tasks.”

Why build this as a local native runtime?#

Because the boundary I care about is local.

The repository is local. Uncommitted changes are local. Installed language servers are local. Build tools, credentials, filesystem permissions, and project-specific constraints are local.

A small native runtime can mediate these things without shipping the entire repository to another orchestration service. wcode is written in Rust and ships as a native binary; it does not require a database or a second agent backend just to expose the local workspace.

That also makes the failure boundary easier to reason about. The model proposes; the runtime authorizes and executes.

What I am working on now#

Most of my recent changes are in retrieval, permissions, parallel scheduling, verification, and project state. The model can already write code well enough to expose mistakes in the surrounding runtime, so that is where I keep finding work.

I also avoid broad speed claims unless I have a workload that supports them. wcode is still changing quickly, and I would rather publish the exact behavior than turn every release into a benchmark story.

If that problem is interesting to you, the code is on GitHub and the current documentation is at wcode.francis.run.