WebCodex

English | 简体中文

WebCodex lets ChatGPT, Claude, and other MCP clients work with repositories and development tools on your own machines. The Runner executes file, Git, command, and test operations where the repository lives; WebCodex exposes those capabilities to the chat client without requiring the repository itself to move.

Try it with one repository

Platform note: webcodex share starts a local WebCodex Server and is supported on Linux and macOS. Windows builds support the CLI + Runner against a remote Linux Server; on Windows use webcodex connect <server-url>. If you do not already have a Server, deploy one on Linux first.

For the default temporary public share, install cloudflared and make sure it is on PATH. Then:

npm install -g @yyjeqhc/webcodex
cd /path/to/your/repository
webcodex share

share is self-contained: it configures the current Git project, starts a local WebCodex Server + Runner, creates a temporary Connector credential, and opens a Cloudflare Quick Tunnel. You do not need to run setup, doctor, or run first.

When the command reports WebCodex ready, keep that terminal open and use the values it prints:

1. In ChatGPT, enable Developer Mode and create a custom app using MCP.
2. Paste the printed MCP URL.
3. Choose Access token / API key or the equivalent Bearer-token option.
4. Paste the printed temporary Credential.
5. Run Scan Tools.
6. Start with a read-only prompt such as:

Inspect this repository and summarize its structure. Do not make changes.

ChatGPT UI labels can vary by workspace and rollout. Developer Mode, custom MCP apps, and write/modify actions are controlled by the ChatGPT plan, workspace, and admin settings; WebCodex cannot widen client-side app permissions. The CLI output is the source of truth for the WebCodex URL, authentication type, and credential for that run.

A default share URL and credential are temporary and stop working when the command exits. webcodex share --tunnel none is available for local-only MCP debugging and does not require cloudflared.

What happens after the first connection

WebCodex can read/search files, prepare guarded edits, run commands and focused validation, inspect Git, and keep long-running Jobs observable. Coding results remain subject to the product's existing authority boundaries. Open /console to inspect project readiness and the work queue; the Console can guide, cancel, Accept, or Reject work where those actions are available. It deliberately does not reveal credentials.

Existing Server and long-lived deployments

If you already have a WebCodex Server URL, connect the current repository to it instead:

cd /path/to/your/repository
webcodex connect https://webcodex.example

connect creates a reusable local profile, starts the Runner, waits for the project to become visible through that Server, and prints the MCP setup values. This is the long-lived hosted path; it is not the prerequisite for trying WebCodex locally.

webcodex login and managed OAuth are advanced identity paths for deployments that need separate users, revocation, audit, or organization-level controls. Self-hosting is an operator workflow; see Deployment.

How it works

ChatGPT / Claude / MCP client
            |
            | MCP / HTTPS
            v
      WebCodex Server
            |
            | authenticated Runner connection
            v
     webcodex-runner
            |
      repository / Git / toolchains

The Server authenticates callers and routes requests. The Runner performs the actual work on the machine that owns the repository. Only requested tool inputs and results cross the connection.

CLI

The common commands are intentionally small:

webcodex share                     # fastest temporary ChatGPT/MCP connection
webcodex connect <server-url>      # connect to an existing Server
webcodex status                    # concise project readiness
webcodex doctor                    # deeper local diagnostics
webcodex setup                     # manual/local project setup
webcodex run                       # manual local Server + Runner runtime
webcodex task list                 # review local tasks

The Runner is the execution component. For compatibility, Runner service management still uses the historical webcodex agent ... CLI namespace. See CLI for operator commands and credential reference.

Documentation

• Quick Start — first ChatGPT/MCP connection
• MCP — ChatGPT, Claude, authentication, then protocol reference
• AI-assisted setup — instructions for an AI helping a user configure WebCodex
• CLI — commands, compatibility notes, and credentials
• Deployment — self-hosting and production operations
• Authentication — credential and authority model
• Runner — Runner operation
• Coding Workflow — task workflow, validation, and closeout
• Troubleshooting
• Documentation index
• Security

Security

WebCodex can modify files and execute commands. Register only project roots the assistant should access, keep credentials out of prompts/logs/Git, and prefer an ordinary OS user for the Runner. The simplified onboarding does not collapse the underlying credential or authority boundaries. Read SECURITY.md for the complete model.

Build from source

cargo build --release --workspace --bins
export PATH="$PWD/target/release:$PATH"

Acknowledgements

Thanks to the LINUX DO community for its welcoming space for technical discussion and support for open-source sharing.

License

Licensed under the Apache License, Version 2.0. See LICENSE.