WebCodex

English | 简体中文

Connect ChatGPT to private code that stays on your machine.

WebCodex runs a small server and an agent next to your repo. ChatGPT can inspect files, request scoped edits, and run validation through WebCodex while your repository stays where it is.

• Choose exactly which project directories are available.
• Keep test and shell execution on the agent machine.
• Review changed files, validation output, and task summaries before accepting work.
• Start locally, then put the server behind HTTPS when using hosted ChatGPT clients.

Install

For the current Linux x64 release:

npm install -g @yyjeqhc/webcodex

Or build from source:

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

See docs/BUILD_INSTALL.md for platform support and install details.

Quick Start

For the localhost example, start with two terminals on the same machine: one for the server, one from the repo you want WebCodex to work on. The commands below assume the npm-installed binaries are on your PATH. If you built from source, export PATH="$PWD/target/release:$PATH" first.

Server terminal - create the server config and start WebCodex:

export WEBCODEX_ENV="$HOME/.config/webcodex/webcodex.env"

webcodex-cli server up \
  --env-file "$WEBCODEX_ENV" \
  --listen 127.0.0.1:8080 \
  --public-url http://127.0.0.1:8080

WEBCODEX_ENV_FILE="$WEBCODEX_ENV" webcodex

server up creates $WEBCODEX_ENV if it does not exist, including the parent directory. That file stores server settings and a server admin key. It is not the key you paste into MCP or GPT Actions.

Repo terminal - from the repo you want WebCodex to work on, create a key, register the repo, and start the agent:

export WEBCODEX_KEY="$(openssl rand -base64 32)"
printf 'Copy this key into MCP/GPT Actions auth: %s\n' "$WEBCODEX_KEY"

webcodex-cli connect http://127.0.0.1:8080 \
  --key "$WEBCODEX_KEY" \
  --root "$PWD" \
  --client-id local-dev \
  --overwrite

webcodex-agent --config "$HOME/.config/webcodex/clients/local-dev/agent.toml"

Keep the printed key for this setup. Paste that same value when you verify with curl and when you configure MCP or GPT Actions auth. You do not need to add this key to the server config.

Verify

In a client terminal, paste the same key printed above:

export WEBCODEX_KEY="<same evaluation key>"

curl -sS \
  -H "Authorization: Bearer $WEBCODEX_KEY" \
  -H 'Content-Type: application/json' \
  http://127.0.0.1:8080/api/tools/call \
  -d '{"tool":"runtime_status","summary_only":true}'

curl -sS \
  -H "Authorization: Bearer $WEBCODEX_KEY" \
  -H 'Content-Type: application/json' \
  http://127.0.0.1:8080/api/tools/call \
  -d '{"tool":"list_projects"}'

Use the returned agent:<client_id>:<project_id> value in MCP or GPT Actions prompts.

For the full walkthrough, see docs/QUICK_START.md.

Client Access

• Local clients can use http://127.0.0.1:8080.
• ChatGPT-hosted clients need a public HTTPS URL. Put WebCodex behind Nginx, Caddy, or a tunnel, start the server with --public-url https://your-domain.example, then use https://your-domain.example/openapi.json or https://your-domain.example/mcp.
• MCP clients use /mcp; GPT Actions use /openapi.json. For the first run, use the key printed in the repo terminal as the Bearer/API-key value.

How It Fits Together

ChatGPT / MCP clients / Custom GPTs
        |
        | MCP / GPT Actions
        v
WebCodex Server
        |
        | authenticated agent bridge
        v
WebCodex Agent
        |
        v
Private Codebase / Git / Tests / Shell

What ChatGPT Can Do

Once a project is registered, an MCP or GPT Actions client can:

• read files, inspect directories, and search the repo;
• make scoped source edits through structured edit or patch tools;
• run focused validation with built-in helpers or bounded shell/job tools;
• inspect changed files, diff hunks, and workspace hygiene;
• finish with a compact task summary that is easy to paste into an issue, PR, or handoff note.

Why WebCodex?

Online models cannot directly access your local files, Git state, test runner, or shell. The usual workaround is to paste snippets into chat, expose ad hoc scripts, or hand a repository to a hosted coding agent.

WebCodex gives the model a useful but narrower interface:

• The server exposes authenticated runtime tools, not raw filesystem access.
• The agent registers project directories from the machine that owns the code.
• Project ids are explicit, for example agent:<client_id>:<project_id>.
• Edits go through structured file and patch tools when possible.
• Validation tools and finish summaries create evidence before handoff.
• Diff and hygiene tools show what changed before you accept, revert, or continue the work.

Where It Fits

Use WebCodex when you need a server/agent boundary, explicit project registration, MCP and GPT Actions support, deployable auth paths, session records, validation evidence, and a path from quick local testing to a private hosted runtime.

It is still not a hosted SaaS or a full browser IDE. The current workflow is tool-first: ChatGPT calls WebCodex tools, the agent operates on the repo, and you review the resulting diff and validation evidence in your normal development process.

The first success criteria are simple: runtime_status works, list_projects shows an agent:<client_id>:<project_id> project, the client can read README.md, and a small edit can be inspected and reverted.

For a walkthrough of the expected tool flow, see docs/DEMO.md.

Normal Coding Loop

WebCodex is designed around a conservative coding loop:

1. start_coding_task - create an explicit session and collect bounded startup context.
2. Inspect - use list_project_files, search_project_text, read_file, optional read-only LSP intelligence (lsp_status, document_symbols, workspace_symbols, goto_definition, find_references, hover), and Git status tools.
3. Edit - prefer apply_text_edits for precise local edits; apply_patch_checked for multi-file patches; write_project_file only for create or intentional full rewrite. Line/pattern tools remain available as compatibility paths.
4. Validate - run validate_patch, cargo_fmt, cargo_check, or cargo_test where appropriate.
5. Inspect validation evidence - use validation_summary to query the existing session ledger without rerunning tests.
6. Inspect outcome - use show_changes, git_diff_hunks, and workspace_hygiene_check.
7. Finish - use finish_coding_task or session_handoff_summary for a compact closeout.

start_coding_task always returns a compact semantic_navigation summary so the coding loop can decide whether to prefer the seven Rust LSP tools. Its bounded status-only probe inspects Rust workspace detection, rust-analyzer availability, and an existing supervisor slot without starting rust-analyzer, running Cargo, or injecting symbol, definition, or reference data. The capability is read-only and workspace-only; dependency navigation remains limited by cargo.noDeps=true. Open Rust documents are refreshed from validated workspace files with bounded full-text didChange notifications; editor-style incremental synchronization is not supported. An unavailable, crashed, legacy, disconnected, or timed-out LSP path does not block coding-task startup or change its startup verdict.

For Rust projects, the recommended semantic feedback loop is:

start_coding_task
→ document_symbols / workspace_symbols
→ goto_definition / find_references / hover
→ read_file
→ edit
→ document_diagnostics
→ cargo_check / cargo_test

document_diagnostics is quick, bounded rust-analyzer feedback. The constrained profile can return no diagnostics or time out waiting for a fresh publication, and it never replaces final Cargo validation.

Validation Intelligence MVP

Validation parser v3 (structured_validation_parser, version 3) deterministically extracts structured evidence from bounded, sanitized metadata already recorded for validation-like tools. A failing cargo_check can expose up to 20 sorted diagnostics with safe project-relative locations and messages of at most 240 Unicode scalars. A failing cargo_test can expose up to 20 failed_test_details entries with conservative assertion / panic / unknown classification without panic bodies, assertion values, or backtraces.

The parser never retains or returns complete stdout/stderr, never executes diagnostic text, and does not infer root causes. Incomplete excerpts are represented with truncated, diagnostics_truncated, omitted locations, and unknown classifications rather than guesses. validation.status remains the ledger history (mixed is preserved), while latest_status and historical_failures distinguish the final run from earlier failures. Resolved failures remain visible as audit evidence but do not lower an otherwise passing final task outcome; zero-test runs do not resolve earlier cargo_test failures.

validation_summary(project, session_id, limit?) is a read-only query over existing session evidence. It does not run Cargo, shell, an agent request, or file reads, and it is not a replacement for finish_coding_task, which still owns overall closeout. Recommended loop:

edit
→ document_diagnostics
→ cargo_check / cargo_test
→ validation_summary
→ targeted fix
→ cargo_check / cargo_test
→ finish_coding_task

run_shell and run_job exist for bounded escape hatches. They are powerful and should not be the default editing or validation path.

Safety Model

WebCodex does not make an online model a trusted local user. The model can only call exposed tools, those tools run through server policy and agent project boundaries, and shell/job tools remain explicit high-risk operations.

Projects live on the agent machine. The agent registers allowed directories with the server. The server does not scan your filesystem.

Do not expose secrets in prompts, examples, tool output, docs, or committed config files. For the full boundary model, read SECURITY.md and docs/CONCEPTS.md.

Current Capabilities

• Remote MCP endpoint and GPT Actions OpenAPI surface backed by one ToolRuntime.
• Agent-registered project model with agent:<client_id>:<project_id> ids.
• Structured source editing tools for scoped changes.
• Patch validation, Cargo validation helpers, Git diff/status tools, and bounded shell/job execution.
• Coding-task sessions with validation parser v3 evidence, read-only validation_summary, handoff, finish verdicts, diff evidence, and hygiene summaries.
• Authentication paths for quick shared-key evaluation and production deployments.
• Documentation for first setup, concepts, MCP, GPT Actions, security, release notes, and roadmap.

Known Limitations

• WebCodex is self-hosted infrastructure, not a hosted SaaS.
• Setup is still technical and assumes comfort with a terminal, server URL, and agent process.
• Read-only Rust LSP intelligence is available through seven tools (lsp_status, document_symbols, goto_definition, find_references, document_diagnostics, hover, workspace_symbols) via agent-side rust-analyzer with a constrained profile (cargo.noDeps=true, no build scripts/proc macros/checkOnSave). Paths are project-relative; columns are 1-based Unicode scalars; external/dependency results are omitted. Open documents refresh from bounded workspace file content using full-text sync only. Diagnostics are bounded publishDiagnostics feedback with explicit freshness/timeout state, not a replacement for Cargo validation. Editor-style incremental sync, multi-language support, dependency navigation, and LSP write operations are not first-class.
• The browser console is read-only and minimal; MCP, GPT Actions, and CLI workflows are the primary paths.
• WebCodex does not provide a full UI approval/review queue yet. Review means inspecting diff, validation, hygiene, and session evidence before accepting the work in Git.
• Shell and job tools require operator trust, bounded configuration, and normal code review discipline.

Docs Map

• First setup: docs/QUICK_START.md
• Demo workflow: docs/DEMO.md
• Concepts: docs/CONCEPTS.md
• Architecture: docs/ARCHITECTURE.md
• MCP: docs/MCP.md
• GPT Actions: docs/GPT_ACTIONS.md
• Security: SECURITY.md
• Auth model: docs/AUTH_MODEL.md
• Deployment: docs/DEPLOYMENT.md
• Release notes: docs/RELEASE_NOTES_v0.2.0.md
• Roadmap: docs/ROADMAP.md
• Full index: docs/INDEX.md

License

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