Free Coding Agent

Give frontier AI models real hands on a real developer workstation.

Free Coding Agent is an open-source, provider-neutral MCP execution layer that turns a capable model from a chat box into a hands-on software engineer. The model supplies the intelligence; Free Coding Agent supplies controlled access to files, terminals, Git, language servers, browsers, Windows UI, jobs, checkpoints, tests, and diagnostics.

LM Arena describes Code Arena as a place to build and compare with frontier AI models. Free Coding Agent is designed to be a compatible execution layer for any host that supports MCP or equivalent remote tools. It is independent software and is not an LM Arena product.

Core principle: no shared project infrastructure

Free Coding Agent does not require a relay, domain, account, API key, tunnel, or backend operated by this project.

Every installation is independent:

• its own local configuration;
• its own workspace allowlist;
• its own MCP bearer token;
• its own HTTP server;
• its own HTTPS hostname/tunnel when remote access is enabled;
• its own third-party account, if the user chooses a tunneling provider.

There is no common Free Coding Agent relay and no common remote credential.

What it can do

• transactional filesystem reads/writes;
• atomic multi-file patches and rollback checkpoints;
• optimistic SHA-256 concurrency protection;
• shell commands and long-running processes;
• real PTY / ConPTY for REPLs, debuggers, SSH and TUIs;
• Git status, diff, history and repository operations;
• headless LSP diagnostics, definitions, references, hover and symbols;
• project inspection and project-local memory;
• Playwright browser automation;
• optional real-Chrome companion extension;
• optional VS Code companion extension;
• Windows UI automation;
• FFmpeg/media workflows;
• resource admission to avoid CPU/RAM stampedes;
• MCP batching and capability discovery;
• local stdio MCP;
• authenticated local HTTP MCP;
• optional personal public HTTPS MCP.

Durable Agent Mode

Free Coding Agent includes a provider-neutral task kernel for autonomous and multi-agent coding. It does not call or hardcode a model vendor: any MCP-capable model can act as a worker.

The durable loop is:

task_submit
    ↓
task_next / task_claim
    ↓
worker edits + targeted checks
    ↓
task_ready
    ↓
task_verify
   ↙       ↘
repairing  succeeded
   ↓
task_claim → repair → task_ready → task_verify

Important guarantees:

• append-only task journal with fsync;
• idempotency keys prevent duplicate submissions;
• dependencies form explicit task DAGs;
• exclusive leaseKey ownership prevents two workers from editing the same worktree at once;
• cross-process journal locking prevents two MCP processes from racing the same task;
• lease expiry and dead-owner recovery fail to interrupted, never fake success;
• task_next atomically assigns the highest-priority runnable work;
• verification commands are executed as real processes in the task workspace;
• tasks can require an independent logical verifier identity distinct from every implementation worker;
• failed gates create an evidence-backed repair loop;
• configurable maximum repair rounds prevent infinite retry loops;
• only task_verify can transition verified work to succeeded;
• task events provide a durable audit trail.

Core tools:

task_submit
task_next
task_claim
task_heartbeat
task_ready
task_verify
task_update
task_reconcile
task_contract
task_status
task_list
task_events
task_stats
task_cancel

This is the portable agent-control layer: the model may come from OpenCode, an MCP desktop host, an IDE, a self-hosted model, or another compatible client. The task kernel only coordinates ownership, state, evidence and verification.

Worker/verifier IDs are logical identities supplied by the MCP host for coordination and audit; they are not authentication credentials.

Install on Windows

The normal installation flow is:

Download ZIP
→ extract
→ double-click install.cmd
→ choose the folder the agent may access
→ optionally configure YOUR personal HTTPS endpoint
→ Ready

The installer:

1. verifies Node.js 20+;
2. can install Node.js LTS when Windows Package Manager is available;
3. installs free-coding-agent globally;
4. configures the user's own workspace;
5. runs free-coding-agent doctor;
6. optionally guides the user through personal HTTPS setup.

The extracted installer folder can be deleted afterwards.

Local mode — no domain, no internet tunnel

For an MCP client running on the same machine, nothing public is needed:

{
  "mcpServers": {
    "free-coding-agent": {
      "command": "free-coding-agent",
      "args": ["stdio"]
    }
  }
}

No domain. No TLS. No exposed port. No external service.

For HTTP clients, Free Coding Agent uses the current MCP Streamable HTTP transport at POST /mcp. Deprecated legacy HTTP+SSE endpoints are intentionally not exposed in v3.

Personal HTTPS mode

When the model host is remote/cloud-based, it needs a public HTTPS URL that reaches the user's machine.

Free Coding Agent's official remote model is personal self-configuration, not a shared relay.

Recommended: Tailscale Funnel

Run:

free-coding-agent remote setup

The setup uses the current user's own Tailscale account.

Tailscale Funnel gives that machine its own stable HTTPS hostname under the user's tailnet:

https://<device>.<tailnet>.ts.net/mcp

Free Coding Agent then:

• generates a strong MCP bearer token locally;
• keeps the HTTP origin bound to 127.0.0.1;
• exposes it only through that user's Funnel;
• stores the URL/token only in that user's application-data directory;
• adds a current-user startup entry for the local HTTP server;
• prints the exact MCP configuration.

Example output shape:

{
  "mcpServers": {
    "free-coding-agent": {
      "url": "https://YOUR-PERSONAL-HOST.ts.net/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_LOCAL_TOKEN"
      }
    }
  }
}

Tailscale documents Funnel hostnames as predictable/stable, automatically TLS-protected, and publicly reachable while the user's machine is online.

Alternative: personal Cloudflare Tunnel

Users who own a domain on Cloudflare can use a locally managed named Cloudflare Tunnel instead.

The ownership model remains the same:

their Cloudflare account
+ their domain
+ their tunnel
+ their DNS record
+ their local MCP token

Cloudflare's documented flow is:

cloudflared tunnel login
cloudflared tunnel create <name>
cloudflared tunnel route dns <name-or-id> <hostname>
cloudflared tunnel run <name-or-id>

A named tunnel can also be installed as an OS service. Free Coding Agent does not own or operate it.

Why personal HTTPS instead of a project relay?

Because the open-source project should keep working independently of its author.

With personal endpoints:

• no project-operated server can go offline and break everybody;
• no project operator sees MCP traffic;
• no shared credential exists;
• no shared customer/device database exists;
• no central billing requirement exists;
• users can replace Tailscale/Cloudflare with another provider;
• users can self-host everything indefinitely.

CLI

free-coding-agent
free-coding-agent stdio
free-coding-agent setup
free-coding-agent remote setup
free-coding-agent remote start
free-coding-agent remote status
free-coding-agent remote off
free-coding-agent doctor
free-coding-agent print-config

npm

The package is structured for public npm installation:

npm install -g free-coding-agent
free-coding-agent setup

The npm package must exist in the registry before those commands can be used from npm directly.

Security model

The agent can modify files and execute code, so remote exposure must fail closed.

The personal HTTPS setup enforces:

• a random local MCP_API_KEY;
• bearer authentication for every remote MCP request;
• loopback-only local HTTP binding;
• filesystem allowlisting via FCA_ALLOWED_ROOTS;
• no anonymous proxy access;
• no secret committed to Git;
• no project-wide tunnel or account;
• no remote credentials shared between users.

A remote URL without the user's bearer token cannot use the agent.

User configuration

Normal users should use the CLI instead of editing config manually.

Important variables:

Configuration and runtime state live in standard per-user application-data directories, outside the repository.

OpenCode

OpenCode supports both local and remote MCP servers. A personal Free Coding Agent HTTPS endpoint can be configured as a remote MCP server with bearer authentication.

Conceptually:

{
  "type": "remote",
  "url": "https://YOUR-PERSONAL-HOST/mcp",
  "oauth": false,
  "headers": {
    "Authorization": "Bearer YOUR_LOCAL_TOKEN"
  }
}

Use OpenCode's current configuration schema/documentation for the surrounding config structure.

LM Arena / frontier models

Arena's public documentation describes Agent Mode and Code Arena as environments for agentic coding and frontier-model comparison.

Free Coding Agent does not scrape or automate Arena's private UI/API. If Arena exposes a supported MCP or compatible remote-tool integration, the user's personal HTTPS MCP endpoint is ready for it.

This distinction is intentional: the open-source agent remains standards-based and does not depend on undocumented consumer-site behavior.

References:

• https://help.arena.ai/articles/5432423882-how-to-use-agent-mode
• https://help.arena.ai/articles/5701270322-lmarena-how-to-code-arena
• https://opencode.ai/v2/docs/mcp-servers
• https://tailscale.com/docs/features/tailscale-funnel
• https://developers.cloudflare.com/tunnel/features/locally-managed-tunnels/create-local-tunnel/

Chrome companion extension

The optional extension gives the local MCP server controlled access to the user's real Chrome.

1. Load chrome-extension as an unpacked extension.
2. Configure a local CHROME_BRIDGE_TOKEN.
3. Enter the same token in the extension popup.
4. Optionally pin the assigned extension ID.

No fixed extension identity key is stored in this repository.

VS Code companion extension

The optional extension exposes loopback-only editor state:

• diagnostics;
• references;
• definitions;
• open files;
• debugger state.

Configuration key:

freeCodingAgent.port

Default port: 3005.

Development

npm install
npm run check
npm run privacy
npm run preflight
npm test

Privacy / publication hygiene

The public source tree intentionally excludes:

• local .env files;
• API keys;
• tunnel credentials;
• machine-specific paths;
• user names and email addresses;
• conversation archives;
• browser profiles;
• screenshots and clips;
• logs, checkpoints and job state;
• local memory;
• fixed Chrome extension identity keys;
• provider-account-specific orchestration.

npm run privacy fails if common secrets, email addresses, absolute Windows paths, or user-home paths appear in publishable source.

License

ISC. See LICENSE.