CodeLocal MCP server

CodeLocal

One Project Brain. Any AI client. Your machine.

CodeLocal is a universal MCP layer for AI coding. It connects ChatGPT, Codex, Claude and other MCP-compatible clients to one durable Project Brain plus controlled access to the project folders you explicitly authorize on your own machine.

The model reasons. CodeLocal remembers, routes and executes.

Why CodeLocal

Most AI coding tools treat each chat, client or machine as a fresh start. CodeLocal is designed around the opposite idea: your project intelligence should survive the interface you happen to use today.

• One Project Brain — preserve verified decisions, project context, rules, Experience and reusable skills.
• Any compatible AI client — use ChatGPT, Codex, Claude or another MCP-capable agent against the same project intelligence.
• Controlled local execution — files, Git, terminal and optional automation run against workspaces you explicitly authorize.
• Multi-workspace by design — one local runtime can keep many projects available and activate them lazily.
• Local-first source access — repository source and local indexes stay on your machine by default; Cloud is used for identity, routing and sanitized durable continuity.

We are not trying to rebuild Codex, Claude Desktop, DeepSeek Harness, Cursor or another AI coding client. AI clients are interfaces. CodeLocal is the shared intelligence and execution layer behind them.

How it works

You
  ↓
MCP-compatible AI clients    ChatGPT · Codex · Claude · other agents
  ↕ MCP over HTTPS + OAuth
CodeLocal Project Brain      durable rules · decisions · Experience · skills
  ↓
CodeLocal Cloud              identity · routing · auth · sanitized continuity
  ↓ authenticated runtime channel
CodeLocal native runtime     controlled execution on your computer
  ↓
Authorized workspaces        files · Git · terminal · local MCP extensions
  ↓
Verification                 evidence → verified Experience → safer reuse

The AI client/model reasons; CodeLocal provides the shared MCP layer, preserves project intelligence and controls execution.

Quick start

Requires Node.js 20+ and npm.

Install the current stable release:

npm i -g codelocal@latest

Verify the installed version:

codelocal --version

Authorize one or more projects:

cd /path/to/project-a
codelocal .

cd /path/to/project-b
codelocal .

Start one machine runtime:

codelocal

A single runtime can keep many workspaces authorized. You do not need one CodeLocal daemon per project or per AI client.

Useful commands:

codelocal --version
codelocal setup
codelocal status
codelocal workspaces
codelocal grant <path>
codelocal ungrant <path-or-id>
codelocal doctor <path>
codelocal stop
codelocal reset --all
codelocal uninstall --all
codelocal approvals list
codelocal mcp list

Connect an MCP-compatible AI client

The current hosted MCP endpoint is:

https://codelocal.cloud/mcp

For ChatGPT and Codex, use the CodeLocal Plugin from the OpenAI directory when available; reviewer/developer flows can use the endpoint directly. Other MCP-compatible clients can add the same remote endpoint when they support authenticated remote MCP.

OAuth signs the AI client into your CodeLocal account. Pairing signs your local machine into the same account. A connected client can only route tools to devices and workspaces belonging to that account.

Typical first request:

@CodeLocal inspect project_info first, understand this project,
then make the requested change and run the relevant checks.

Core capabilities

Project Brain

• durable single-user project knowledge;
• verified Experience promotion and reuse;
• reusable learned skills;
• project rules, decisions and constraints;
• continuity across compatible clients and paired machines when Cloud continuity is available.

See Project Brain Evidence.

Files and code intelligence

• workspace boundary enforcement and symlink escape protection;
• .gitignore-aware listing and search;
• sensitive-path blocking independent of .gitignore;
• UTF-8/binary detection and ranged reads;
• SHA-256 stale-write protection;
• exact edits, patches and transactional structured edits;
• project/language/framework mapping;
• symbols, definitions, references, diagnostics and structural call/import context;
• dependency inspection for Node, Go, Rust and Python.

The native structural engine works without requiring a language server. Dedicated LSP integrations add depth where available.

Terminal and Git

• guarded host command execution;
• concurrent process management and PTY support where available;
• incremental stdout/stderr, stdin, resize, signals and cancellation;
• deterministic command risk classification;
• approval gates for sensitive operations;
• local redacted terminal/audit history;
• non-force Git stage, commit and push controls;
• idempotency protection for side-effecting tool calls.

Local MCP hub

CodeLocal can connect other MCP servers installed on the user's machine while keeping their configuration local.

codelocal mcp add <name> -- <command> [args...]
codelocal mcp add <name> --url <https://server/mcp>
codelocal mcp list
codelocal mcp search <query>

Secrets should be referenced from environment variables instead of being copied into CodeLocal Cloud.

Optional automation

On first start, CodeLocal can enable two optional capabilities separately:

• Browser Automation — isolated Chromium sessions for opening, inspecting, clicking, typing and screenshots.
• Computer Use — native desktop control through operating-system accessibility/screen permissions.

Run codelocal setup to change these choices later and codelocal doctor to inspect readiness.

Security model

.gitignore is a retrieval rule, not a security boundary. Sensitive locations such as private keys, credential stores and .env secrets are handled separately.

Terminal commands execute on the user's host after CodeLocal policy and approval checks. CodeLocal does not claim that command policy alone is an OS sandbox. Browser Automation and Computer Use are optional and should be enabled only where that trust model is acceptable.

Raw repository source, local indexes, secrets and machine bindings remain local by default. The supported remote MCP flow, account/device routing and cross-device Project Brain continuity currently depend on CodeLocal Cloud.

Read the full Security & Privacy, Security Policy and Implementation Status.

Build it with us

“It takes a village to raise a child. Open source is no different.”

CodeLocal is still growing. If you find a bug, disagree with a design decision, have an idea, or can make any part of the project better, contribute code and share feedback in the CodeLocal Forums.

codelocal.cloud is the CodeLocal team's current reference deployment. The source is open for you to study, fork, modify and experiment with. Experimental self-hosting is welcome, but a self-hosted public gateway is not yet an officially supported deployment target.

Do not wait for CodeLocal to become “finished” before participating. Review the code, open issues, propose safer designs, send pull requests, challenge assumptions and tell us what does not work. Help us grow CodeLocal together.

See Contributing.

Public edition and Enterprise

The public edition is intentionally optimized for one person: one user's Project Brain, reusable skills, project context and controlled execution across compatible AI clients.

The private Enterprise edition serves organizations that need AI inside security-sensitive business environments and can include organization-wide controls, private integrations, customer-specific deployment assumptions and proprietary infrastructure coupling.

The public repository is not a copy of the Enterprise codebase with private files removed. We do not move the Enterprise source code into this repository. Instead, the Enterprise edition acts as a proven product and operational reference: each capability is designed and implemented again for the public edition.

Why? The Enterprise edition contains organization-specific integrations, deployment assumptions, access controls, security hardening and infrastructure that are tightly coupled to private business environments. Copying that code directly into the public repository would make the open-source edition harder to understand, audit, fork and run independently. Rebuilding each public capability separately lets us keep the useful ideas and behavior while producing a cleaner, standalone implementation for the community.

This rewrite is being performed manually, feature by feature. During the transition, the public repository may not yet contain every capability available in Enterprise, and reviewers may still encounter historical names, compatibility files or Enterprise-era metadata that are not part of the shipped public npm runtime.

Target completion date for the current public-repository separation and cleanup: October 19, 2026.

Until then, use STATUS.md, the release builder and canonical architecture documentation as the source of truth for what actually ships in the public edition.

Repository map

Path	Ownership
cmd/, internal/	Canonical Go backend, CLI and local runtime
web/	Next.js browser product
deploy/	Dockerfiles, Railway configs and deployment assets
tools/, scripts/	Build, release and developer tooling
docs/	Architecture, guides, operations and plans
legacy/typescript-runtime/	Quarantined compatibility/history code; not the shipped runtime

The canonical backend, Cloud gateway, CLI and local runtime are implemented in Go. The browser product uses Next.js + TypeScript. See Product Stack.

Development

Requires Go 1.25+.

go test ./...
go vet ./...
go build ./cmd/...

Validate and build the npm CLI staging package without publishing:

npm run release:npm:prepare

For the full repository gate, use:

npm run release:prepare

Publishing and release details live in the npm release operations runbook. Keep release mechanics there rather than duplicating fast-changing implementation details in this README.

Update

Stable:

npm i -g codelocal@latest

Beta:

npm i -g codelocal@beta

A normal npm update keeps existing pairing credentials and authorized workspaces. If an already-open MCP client reports a tool/schema mismatch after an update, refresh or reconnect CodeLocal in that client so it scans the current tool surface.

Documentation

• Start here
• User Guide
• How CodeLocal Works
• Security & Privacy
• Project Brain Evidence
• Product Stack
• Implementation Status
• Security Policy
• Contributing
• Beta Channel
• OpenAI Plugin Submission Pack

Website: https://codelocal.cloud

License

CodeLocal is licensed under the Apache License 2.0. Unless a file or directory states otherwise, source code in this repository may be used, modified and distributed under the terms of that license. Third-party components retain their respective licenses.