One ecosystem, three distinct jobs
SpecWeave keeps project intent and evidence in your repository. vskill and Skill Studio help you install and evaluate skills. SpecWithCode is the interface on top: projects with a coordinator and workers on any harness, across your machines. See harnesses, models and the interface. Start with the SpecWithCode overview for what it does; this page covers how the pieces connect.
SpecWithCode
The workspace
Projects with a coordinator and workers, each on the provider and model you pick, running on your own machines with approvals you can see.
See SpecWithCodeSpecWeave CLI
The record
The spec, task claims, test evidence and handoff live in your repository, so any agent or account can continue. Open source.
Start the open-source workflowVerified Skill
The skill registry
Agent skills, each with its source, security scan and evaluation shown. The vskill CLI installs them into every agent.
Explore skills and evaluations
SpecWithCode is not the app launched by npx vskill studio. That command opens Skill Studio, the skill development and evaluation workspace.
The architecture
Sign in to SpecWithCode Connect to reach your machines from anywhere. You can also pair over your local network or let the desktop app open an SSH tunnel.
Model provider boundary. Native agents contact their configured providers. Private remote access does not make cloud inference local.
| Layer | Responsibility | Boundary |
|---|---|---|
| Browser | Display sessions, output and approvals | Browser connection state does not grant execution authority |
| Network route | SpecWithCode Connect, the hosted relay, between machines and devices; also the local network, an SSH tunnel or an optional Tailscale route | Reaching a host is not permission; SpecWithCode still requires pairing on every route |
| SpecWithCode runtime | Track host-local threads, accounts, admission and recovery; the harness owns its native session | Pair each host separately; do not copy credentials between accounts |
| Harness | Run the agent loop, execute tools and keep the native session, on its selected model and account | Harness availability and approval rules still apply |
| Repository | Code, specs, task ledger and verification evidence | Git transports project changes; it is not a shared live session database |
| vskill | Inspect/install skills and run evaluations | Source trust and evaluation results require independent assessment |
Connecting other machines
Machines that run workers for your coordinators join through SpecWithCode Connect. On the new machine, sign in to Connect and link it (the main machine does not need Connect), then make an invitation line under Settings > Connections > Your private machines > Invite this machine (or specwithcode fleet invite). Paste it on the main machine under Add a machine and allow workers on its card. A Linux server or VPS on x64 or arm64 joins the same way. Tailscale is an optional direct route between machines. Step by step: Add a machine and Linux worker.
SpecWithCode Connect, the hosted relay, is the default way to reach your machines from anywhere and from your phone. It is off until you sign in to it and includes 3 machines (pricing).
A browser or phone opening a SpecWithCode host can use one of several routes, and a host can keep more than one, using the first that answers:
| Route | When to use it | What you need |
|---|---|---|
| SpecWithCode Connect | Default, from anywhere or from your phone | Sign in on both devices with the same account |
| Local network | The devices share a home or office network | Turn on network access on the host and pair with a one-time link |
| SSH | You can already SSH to the machine | The desktop app opens the tunnel and can start SpecWithCode on the remote host |
| Tailscale HTTPS (optional) | You already use Tailscale and want a direct route | Both devices in the same tailnet; Tailscale Serve, never Funnel |
If you use the optional Tailscale route, note that Tailscale Serve exposes a local service inside the private tailnet. Funnel is a different feature for public exposure; it is not SpecWithCode's remote-access design. See the official Tailscale Serve documentation.
Harnesses and switching
SpecWithCode runs no agent loop of its own. It drives each vendor's own harness with the sign-ins already on that machine: Claude Code (Agent SDK), Codex (app-server), Cursor (SDK), OpenCode (HTTP API), Pi (RPC) and Muse Code (Muse SDK); Grok Build and Antigravity connect over ACP, and Gemini CLI, GitHub Copilot and other agents through the ACP Registry. Cursor is the exception: you sign in once inside SpecWithCode, or set CURSOR_API_KEY, and it runs as a local agent in the selected workspace through Cursor's SDK. SpecWithCode never starts Cursor cloud agents. Each thread picks its harness, model and effort. You can change harness inside a thread: SpecWithCode passes a budgeted selection of the conversation to the new agent, which continues in the same checkout. When a provider hits its usage limit, the project’s rule decides: switch to the fallback provider on its own (the default), offer the fallback, or wait for the reset.
Optional components
CLIProxyAPI is optional. SpecWithCode can read the usage of Codex accounts in a CLIProxyAPI hub you already run and show it under Usage → Limits. It skips Claude accounts in a hub, because Anthropic does not let other apps use or relay Claude.ai sign-ins. Native Claude Code and Codex turns never pass through it. Routing personal subscription sign-ins through a shared proxy can conflict with a provider's terms, so check them before pooling accounts. AnyModel is likewise optional and only matters for API or local-model compatibility work.
Security boundaries
- Reachability is not authorization. SpecWithCode stays bound to loopback and ignores Tailscale identity headers. Every origin needs its own pairing, even for a device already on the tailnet.
- Restrict the tailnet if you use one. The default tailnet policy lets every device reach Serve ports. Limit SpecWithCode's ports to your own devices with a grant, and do not share a SpecWithCode host to other tailnets.
- Serve names are public. With the optional Tailscale route, certificates for
*.ts.netnames appear in public Certificate Transparency logs. Choose machine names that do not identify you and keep them out of public repositories. - A usage hub key unlocks every pooled account. An optional CLIProxyAPI hub's management key can make requests with any pooled account's token. Keep the hub on loopback with remote management off. SpecWithCode stores the key server-side, sends it only over https, loopback or a Tailscale address, and drops it when the hub URL moves.
- Subscriptions follow provider terms. SpecWithCode's native path runs the official Codex and Claude Code clients with their own sign-in. Routing subscription tokens through a proxy or pooling accounts to avoid limits can breach a provider's terms and risk suspension.
Where data goes
Local-first describes where project files and runtime state live. It does not mean every request stays on the machine. Native coding agents and Skill Studio evaluations can contact their configured cloud model providers. Review those providers, account policies and any tools your skills invoke before using sensitive material.
Keep live worktrees, session databases and credential stores on their owning hosts. Use git and explicit handoff for portable code and task state. Private network access and SpecWithCode pairing are complementary controls, not interchangeable credentials.
Inside a SpecWithCode host
The client sends authenticated, typed commands to the runtime on the machine that owns the session. A database transaction records events, projections, receipts and pending side effects in an outbox. Workers perform native-provider and Git operations and record their outcomes. An accepted command is not the same as a completed side effect.
Session state belongs to the native runtime; SpecWeave remains responsible for project intent, task ownership and acceptance evidence. An account pin and the session's host affinity remain meaningful even when several machines share a subscription. Adding hosts does not create extra provider quota: machines signed in to the same account share its limits, which is why we recommend one machine per subscription.
The optional Jev / Decisions integration handles bounded classifications in SpecWeave. Its model output is advisory: it does not grant permissions or prove a task passed verification.
What is verified
The accepted 8 October 2026, 4:14 PM EDT private fleet run completed three native Codex marker-reading turns, one per host, sequentially. The delivery record binds that bounded result to source 5d25f9ab and its packaged artifact. This is a dated observation, not a promise that every account currently has capacity.
That demonstrates bounded native routing in the tested fleet. It does not establish concurrent enterprise load, generalized task success rates, measured productivity gains, compliance certification, a public installer or a service-level agreement. New UI and fleet work continue separately; a source commit alone is not installed-runtime proof.
Watch agents work in SpecWithCode
Ask for an outcome in the chat. The agent manages the spec, task claims, tests and evidence through SpecWeave as it works. SpecWithCode lets you inspect the tool calls, changed files, results and pending approvals in the browser. The walkthrough replays a genuine completed disposable run; the switching scene previews the new confirmation UI without starting another provider turn.
Model changes can rebuild prompt caches. A provider change also uses a portable context handoff: native runtime state and provider caches do not transfer. Check the warning and destination before sending the next message.
Under the hood: optional CLI deep dive
The following tutorial explains the commands an agent calls. Manual spec editing and task entry are not required steps in the SpecWithCode browser walkthrough.
- Install the CLI with
npm install -g specweave, then follow the quick start. - Ask your coding agent for one small outcome with a clear way to verify it. The agent records the spec, files, acceptance criteria and test.
- The agent claims the task, implements it, runs its test and records the real evidence. Inspect those records when you need the detail.
- When you choose to transfer, ask the agent to hand off. It calls
specweave handoff; the receiving agent callsspecweave pickupafter checking ownership and branch state. - Explore Skill Studio if a repeated task would benefit from a tested skill.
Since SpecWeave 3.0.11, specweave auto-handoff on gives one heads-up at 95% of a usage window and keeps working (suggest mode); a turn that really hits the limit hands off by itself, and silent local checkpoints are saved between turns. Inside a SpecWithCode thread the hooks never steer the model, because the app switches provider itself. See checkpoint and handoff rules.
Walkthrough: remote SpecWithCode
Install SpecWithCode on each machine that runs work, then connect them:
- Link each worker machine to SpecWithCode Connect, and add each worker machine with Invite this machine on it and Add a machine on the main one.
- To open a host from a browser or phone, pair that browser with the host. Reaching it is not enough.
- Confirm the connection, project, native provider and account before submitting a small test request.
- Inspect the actual output and any pending approval. A balance or usage percentage alone is not permission to run.
- Reconnect and verify the same session on the same host. Keep project transfer explicit when moving work between tools or machines.
SpecWithCode is free for every developer and team, with no markup, no token resale and no seat fee to run agents on your own machines (pricing). It is in early access for macOS on Apple silicon, Windows 10 and 11 (x64), and Linux (x64). Download it from the SpecWithCode page or from GitHub releases.
For a team evaluation
Begin with one repository, your team and a written success criterion. Measure accepted tasks, recovery effort, failed runs and review time. Keep tests, pilot activity and collected revenue distinct from adoption or ROI claims.
SpecWeave's task ledger is append-only by CLI behavior and workflow convention. It is an ordinary file and can be edited outside the CLI. Use your repository's review, access and retention controls when an auditable history matters. No cryptographic immutability or compliance certification is implied.