MCP | Francis Du

How wcode Grew Past the MCP Bridge I Started With

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

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