Repository tools, task tracking and checks

wcode helps coding assistants read repositories, change code and run checks. It works through MCP with the assistant you already use. You can inspect changes, manage tasks, approve access and see which checks ran against the current code.

The workflow is Understand → Change → Inspect → Verify → Evidence → Accept / Block. The team edition, wteam, adds shared policies, review records and GitHub merge checks. Its complete team workflow still needs a real pilot; individual implemented features do not establish that the whole workflow is ready. See the capability audit and implementation plan.

Checks are tied to the code they ran against. A past passing result does not approve a later change.

Website · Documentation · Getting started · Research paper

The Apache-2.0 Core and complete local product remain independently useful. New commercial composition packages consume OSS public contracts in a separate workspace; see the OSS / Commercial architecture audit and migration boundaries.

The website is the canonical product documentation and includes its own language switcher. The four system SVGs below are living product documentation: when wcode changes its engineering loop, repository model, verification contract, or security boundary, the diagrams are expected to evolve with the product.

Research paper

WCode: Revision-Bound Evidence for Stateful Software Agents — Francis Du, 6 November 2026.

Read online · English PDF · LaTeX source ZIP

The preprint specifies an evidence-admission contract and evaluates the runtime with 60 synthetic scenarios, 2,520 measured calls, and 22 selected counterexamples replayed on the same retained executable. Its findings are scoped to the tested runtime contracts and synthetic fixtures.

Get started

Install on macOS or Linux:

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

Windows PowerShell:

irm https://raw.githubusercontent.com/francis-du/wcode/main/install.ps1 | iex

From the repository you want to expose:

wcode setup

Choose Global (recommended) or Current project, reconnect the coding agent, and let the host launch wcode mcp-stdio. The host working directory becomes the default Workspace.

Run the operator runtime when you also want the TUI, Project Status, Setup Hub, or remote MCP access:

wcode

Press W for the Project Status and O for Setup Hub. Remote clients use the public /mcp endpoint shown by the runtime and complete OAuth.

The current workspace, revision and snapshot state stay visible across all seven pages. This image uses labeled fixture data. See the interface review and page gallery for desktop, phone and terminal states.

Update and reconnect

For an existing installation, run wcode --version, then wcode update, and check the version again after the updater finishes. The updater fetches the latest stable release; use the fixed GitHub release downloads and their SHA256SUMS when you need a specific version.

Reconnect your MCP Host to start a new stdio process. Replacing the binary does not upgrade an already running session or restart a standalone service. On Windows, replacement begins after the update process exits; the helper's preparation message is not completion.

The documentation source index is also readable directly in this repository. When the documentation website is unavailable, browse the release-note source directory for the bilingual upgrade steps, Jobs operating guide, troubleshooting and verification records.

The engineering loop

wcode keeps the model replaceable while repository state, policy, proof, and observability remain durable.

The loop is intentionally conservative:

• Understand — build task-ready context from Design State, syntax, semantics, graph relationships, conventions, and current work.
• Change — mutate only inside the selected Workspace with bounded writes and SHA-guarded edits.
• Inspect — explain changed files and symbols, impacted components and requirements, precision, risk and missing coverage.
• Verify — execute required deterministic checks and language-native providers; keep mapped, skipped, failed and unavailable distinct.
• Evidence — retain execution provenance and exact revisions; verified repository experience depends on proof.
• Accept / Block — enforce existing Verification and Reconciliation gates. The unified commercial Acceptance Record and external merge gate remain in development.

Repository intelligence

wcode does not treat repository understanding as a large prompt dump. It builds a layered model from desired state, actual source, syntax, semantic providers, Git changes, and verification evidence.

Tree-sitter provides syntax navigation across the supported languages. Cross-file references, callers, implementations, and hover use a live LSP when available. Provider, precision, freshness, and revision stay explicit instead of being silently promoted to stronger semantics.

agent_context is the normal starting point for coding work. It returns bounded source, edit targets, current SHAs, checks, readiness, risks, and parallel work guidance instead of forcing every client to reconstruct the repository from scratch.

Verification is revision-bound

Verification depth follows change risk, not model confidence.

A deterministic failure cannot be erased by a model verdict. Required advanced stages, independent reviewers, human approval, target coverage, and stale-revision blockers remain visible until they are actually satisfied.

A normal workflow is:

1. Call agent_context for the task.
2. Read only missing source with read_files, symbol_context, or semantic_navigation.
3. Apply SHA-guarded edits, batching independent work and serializing true conflicts.
4. Run review_changes and verify_project.
5. Inspect drift, impact, risk, verification state, or evidence when the task requires deeper proof.

Security boundaries

Remote reachability, model requests, command trust, and filesystem authority are separate decisions.

Key boundaries:

• Configured Workspaces and discovered subspaces define the filesystem scope.
• Model-facing file operations block protected paths, traversal, symlink escapes and unsafe hard links.
• Existing-file edits use SHA-256 preconditions and atomic commits.
• Commands use an executable plus an argument array, with no implicit shell parsing. The OS sandbox is opt-in per call (sandbox: true); when no backend is available, a requested sandboxed call falls back to direct execution rather than being refused.
• Ordinary enabled command execution needs no second command grant. Explicit executable revocations still require reauthorization, and --no-exec disables ordinary execution.
• --read-only disables the file-modification tools, --no-exec disables command execution and --no-semantic disables language-server discovery. Each is an explicit operator choice and is honoured, including against a session-wide command grant.
• An explicit current-runtime all-command grant authorizes otherwise-unrestricted commands; --no-exec still overrides it. Environment scrubbing, cwd containment, process ownership, timeout, cancellation and output/resource bounds remain active in both lanes.
• TUI, protected WebUI and stdio elicitation expose the same authorization state. Revoking a session grant restores the base policy and prior explicit revocations.
• Non-command providers and verification executors keep their own profiles and trust checks. Command grants and Full Access cannot authorize a separate HumanApproval decision or replace merge/deployment acceptance.
• OAuth protects network transports; a tunnel provides reachability, not authorization.

See the Security Model for the bounded direct lane, syntax-only shell checks, platform sandbox support and independent authorization boundaries.

MCP transports

Client location	Transport	Entry point
Same machine	stdio	wcode mcp-stdio
Remote, preferred	Streamable HTTP	https://host/mcp with OAuth
Older remote client	SSE compatibility	GET /sse + POST /message?sessionId=... with OAuth

Every transport reaches the same Harness, Workspace policy, authorization system, software intelligence, and verification state.

Operator surfaces

The TUI shows runtime health, MCP state, Workspace activity, slots, throughput, verification signals, and pending authorization. The Project Status exposes the current product views: Overview, Engineering architecture, Task activity, Verification evidence, Current changes, Requirements, and Project files, plus Access management and Setup Hub.

Current screenshots and UI walkthroughs live on the website product tour so the README does not duplicate stale interface documentation.

Useful commands

wcode                    # start runtime + TUI
wcode setup              # configure supported coding agents
wcode update             # update an installed binary
wcode --show-config      # inspect resolved runtime settings
wcode intelligence       # inspect repository intelligence
wcode intelligence --check --json
wcode verification
wcode help-all

Documentation

Use the wcode website as the canonical documentation entry point. It contains getting started, integrations, security, language quality, agent workflow, CLI/MCP reference, screenshots, and language switching without requiring separate README variants or version-specific documentation links.