KMJ CodeBridge

Connect CodeBridge to your AI

Already use an AI coding assistant? Start with the existing GitHub-hosted plugin marketplace—no CodeBridge payment or API key required for installation. You must still complete OAuth and authorize your own device/project before the AI can inspect anything. This is a developer preview, not a claim of curated marketplace approval or one-click device enrollment completion.

Claude Code:

claude plugin marketplace add kmjtechno/kmj-codebridge
claude plugin install kmj-codebridge@kmj-techno

GitHub Copilot CLI:

copilot plugin marketplace add kmjtechno/kmj-codebridge
copilot plugin install kmj-codebridge@kmj-techno

One-click editor setup: Add CodeBridge to Cursor or copy the VS Code install URI. Both configure only the remote endpoint; user OAuth/device approval is still mandatory. Installation/link behavior is not independently verified across all editor versions.

OpenAI Codex CLI:

codex mcp add kmj-codebridge --url https://kmjtechno.com/mcp

ChatGPT and other supported Streamable HTTP MCP clients: add https://kmjtechno.com/mcp as a remote MCP connector, then complete the client-supported OAuth consent flow. Do not use the MCP URL as a Git marketplace source. AI tools are scoped to approved devices/projects; no blanket remote shell access.

Already enrolled on Windows P720? Double-click scripts/windows/CONNECT-P720-CODEBRIDGE.cmd for a scoped, SHA-pinned reconnect without changing the dirty development checkout. One-click device connection and first-time pairing requirements →. This is a user-session reconnect, not an unattended Windows service.

Full setup, safety checks, and reusable AI-assistant prompt →

Related MCP server: Remote Coding Runtime

Why CodeBridge?

AI coding gets powerful when it can inspect the real project, make a precise edit and prove the result with a real quality gate. It also gets dangerous when the only answer is “give the model a shell”.

CodeBridge takes a narrower approach:

• One bridge for multiple MCP clients — ChatGPT, Claude and compatible clients can share the same tool contract.

• Outbound-only device agents — your VPS does not need a public inbound CodeBridge port.

• Explicit project scope — the agent works only inside administrator-approved project roots.

• Guarded writes — hash/precondition checks reduce blind overwrite risk.

• Fixed quality gates — run administrator-approved checks instead of exposing arbitrary shell execution.

• Tenant + permission enforcement — authorization is checked at the gateway and device layer.

• Open-source core — Apache-2.0 source you can inspect, self-host and contribute to.

Local LLM first

Use installed, on-device models for bounded coding and reasoning drafts before choosing any separately authorized cloud workflow. CodeBridge's built-in local-model tools contact only loopback Ollama on the authorized device. They never auto-download a model, send a prompt to an outside AI API, or silently fall back to paid inference when a local model is offline.

The workflow is deliberately simple:

1. Discover: Connect an authorized ChatGPT, Claude or other MCP client, select the approved device/project and call local_model_status. This reads available local models; it does not start Ollama.

2. Choose by task and available resources: Prefer a smaller, installed Qwen3 model for short bounded responses; try Qwen2.5-Coder 7B when the task warrants a coding-oriented model and the workstation has capacity. Measure accuracy and latency on your own prompts—there is no claimed automatic best-model router.

3. Approve local inference: Call local_model_generate with localProcessingApproved: true, a chosen installed model, a bounded prompt and a token budget. The resulting text is untrusted until reviewed.

4. Review and verify: Use approved project-scoped edits, configured run_quality_gate checks, secret scanning and exact-head CI before any PR merge. Local inference does not grant filesystem, GitHub or deployment privileges.

5. Autopilot drafts: For a server-leased task, use autopilot_local_draft with a genuine lease and explicit local-processing approval. It records a review-only proposal; it does not apply patches, run arbitrary shell commands or deploy on its own.

These are single P720 readiness measurements (48 evaluation tokens per model), not sustained coding throughput, cold/warm gains, model rankings, or promises for other hardware. The tested agents reported GPU-offload counters, but these alone do not identify the physical GPU.

Privacy and cost boundary: CodeBridge's local inference has no paid/cloud provider fallback; that does not mean the ChatGPT or Claude client itself runs locally. Using those hosted clients may involve their normal provider processing and subscription terms. On-device inference consumes local CPU, GPU, memory, disk and electricity.

Resource safeguards: The current local generator allows an explicit prompt of 1–4,096 characters, 16–512 predicted tokens, a 5–90 second timeout, one generation at a time, and installed models on approved loopback ports. It requests keep_alive: 0 by default for low idle VRAM use; only a device owner can opt into bounded 0–60 second warm retention. Qwen3 short responses request non-thinking mode to avoid spending the output budget entirely on hidden reasoning. A missing/busy/timed-out local model reports a failure—it does not invoke a cloud API.

Read the practical Local LLM-first setup, Claude workflow and production acceptance guide before using these tools. A published MCP tools/list entry is not proof that a previously connected client has refreshed its tool capture or can execute the call.

Architecture

CodeBridge separates the AI client, control plane, and device execution boundary instead of treating them as one unrestricted environment.

┌─────────────────────────────┐
│ AI client                   │
│ ChatGPT · Claude · MCP app  │
└──────────────┬──────────────┘
               │ MCP request
               ▼
┌─────────────────────────────┐
│ CodeBridge gateway          │
│ auth · policy · job state   │
└──────────────┬──────────────┘
               │ authorized work item
               ▼
┌─────────────────────────────┐
│ Outbound device agent       │
│ approved device + projects  │
└──────────────┬──────────────┘
               │
               ▼
      inspect → edit → test
               │
               ▼
        bounded result

Trust boundaries

• The AI client does not receive a generic shell.

• The gateway cannot independently browse the device filesystem.

• The device agent initiates outbound connectivity.

• Project roots are explicitly configured by an administrator.

• Writes and quality gates are constrained by policy and preconditions.

• Results returned to the AI are bounded and may be redacted.

The device agent must be online, authorized for the tenant, and configured for the requested project before work can execute.

What CodeBridge is — and is not

What you can do

Built-in GitHub integration: With an administrator-configured gateway github allowlist and a server-held GitHub credential (or explicitly public read-only mode), CodeBridge provides native GitHub PR queues, exact-head CI evidence, issue conversations, safe feature-branch commits and reviewable PR operations. See GitHub Control Center for credentials, limitations and feature coverage. Source merge does not automatically enable the live VPS gateway or install a new P720 agent.

No generic “run any shell command” MCP tool is exposed.

Native progress and logo diagnostics

Use project_progress for a single bounded status call: existing project jobs, persisted autopilot task percentages and next-ready task, with no raw logs or unverified whole-product completion estimate. Release acceptance remains an independent gate decision.

For logo diagnosis, run node scripts/audit-brand-assets.js: it verifies the existing canonical KMJ CodeBridge icon, cross-package bytes and manifest references without replacing the approved brand artwork. A PASS proves repository metadata only; the live ChatGPT app listing must be checked and refreshed separately if stale. See Native progress and brand audit.

One CodeBridge: Desktop Commander-class development operations

CodeBridge is the primary KMJ project gateway. It implements Commander-style operations natively through the existing outbound agent and the same tenant, device, project and license policy—no separate Desktop Commander service, MCP connector or unrestricted remote shell is required for these tools.

More than parity: project_integrity_manifest computes a deterministic, bounded set of SHA-256 fingerprints for approved UTF-8 files without returning their bodies. Oversized/binary files get an explicit too_large or non_text status, never a fabricated hash. truncated: true / coverage: partial means there are unscanned entries; a manifest digest is not an attestation of an entire repository, its Git commit, or passing tests.

Still planned or deliberately restricted: privileged operations require a Main Platform-backed approval, checkpoint restore is planning-only, GUI/video screen streaming and native desktop UX are not implemented, and arbitrary machine-wide process lists/kills or caller-supplied shell commands are not supported. This avoids silently weakening project isolation to imitate a general-purpose administrator tool.

See the Commander convergence status and safety matrix. Actual availability depends on both the deployed gateway and each enrolled device agent version; a GitHub merge alone does not update remote devices.

For the already-approved Windows P720 CineCore worker, use the staged, idle-only START-P720-CINECORE-SAFE-REFRESH.cmd after its CI is verified. It requires a clean CodeBridge main checkout, runs local checks before switching, preserves the existing device enrollment and can restart the previous runtime if the new authenticated heartbeat fails. It must not run during active development jobs or physical motion operations. See P720 CineCore instructions.

Check connections without reconnecting

For a new or offline device, ask ChatGPT or Claude: "KMJ CodeBridge, check my connections and tell me what to fix."

The read-only connection_overview tool shows whether the problem is in the account grant, gateway registration, project scope or agent heartbeat. It does not touch existing projects or require repeated OAuth sign-in. For an offline Main Platform testing VM, use the single-command Connection Doctor to inspect its identity and gateway acceptance without restarting the agent.

Quick start

Use a disposable or non-production project first. Start read-only, verify the boundary, then enable writes only where you explicitly intend to.

1. Prerequisites

• Node.js 24+

• npm

• Git

2. Clone and verify

git clone https://github.com/kmjtechno/kmj-codebridge.git
cd kmj-codebridge

npm ci --ignore-scripts
npm run check
npm test
npm run scan:secrets

3. Create private configuration outside the repository

npm run init -- /absolute/private-codebridge-config /absolute/development-project

Do not place generated credentials or private configuration inside the Git repository.

4. Start the gateway

npm run gateway -- /absolute/private-codebridge-config/gateway.json

5. Start the device agent

In another terminal:

npm run agent -- /absolute/private-codebridge-config/agent.json

6. Connect an MCP client

Start with read-only tools such as project inspection, directory listing, code search, and Git status. Enable writes only after you have confirmed the intended project scope and device identity.

See AI client setup for ChatGPT, Claude Code, Claude Desktop, Claude.ai and generic MCP clients. For privacy-conscious, free/on-device drafting start with the Local LLM-first guide; Ollama is an optional local runtime and is never auto-installed by CodeBridge.

One-command VPS enrollment

The target production flow is:

curl -fsSL https://kmjtechno.com/install | sudo bash

The installer is designed to detect architecture, stage the runtime, enroll the device, install a hardened systemd service and verify gateway connectivity without installing a GitHub self-hosted runner. The Main Platform bootstrap now pins the CodeBridge setup helper to an immutable 40-hex revision, downloads it over HTTPS/TLS, verifies its exact SHA-256 before execution, preserves an existing enrollment, and uses a read-only repository deploy key. It does not pass an agent token on the command line.

Already-enrolled Main Platform agents can be refreshed through a fixed Supervisor operation that accepts no repository, path, service name, command, or credential input and refuses to create a new enrollment.

Current production gate: deterministic bootstrap/repair and existing-enrollment refresh behavior are verified in CI and the live account currently reports both authorized projects READY. A recorded end-to-end run on a disposable fresh device is still required before claiming fresh-device production proof. See enrollment contract and current status.

Free forever + ultra-low-cost launch plans

The open-source Community tier stays useful. Hosted convenience and higher commercial limits are paid entitlements through KMJ Main Platform.

Planned launch trial (not active): eligible new accounts may receive 30 days of Pro after Main Platform's trial-entitlement and payment gates are verified. There is no automatic paid conversion without an explicit subscription choice.

Third-party AI subscriptions/API usage are separate. Taxes and final checkout terms are controlled by KMJ Main Platform.

See the full plan and premium feature matrix.

Our published comparison of scope and actual activation gates is in Competitive plans & payment readiness. Merchant account approval is not a live CodeBridge subscription.

Interested in a Pro/Team pilot? Contact KMJ CodeBridge support to request a private, opt-in developer-preview onboarding discussion. A request is not a checkout, invoice, active subscription or an entitlement. Paid access can be fulfilled only through verified KMJ Main Platform commercial orders and the applicable terms.

Premium capability categories

Paid plans are designed around capabilities that create ongoing hosted value rather than artificially crippling the open-source core:

• hosted account linking and managed onboarding;

• higher device, project and concurrency limits;

• signed commercial entitlements and renewable access;

• extended job history;

• shared team policies and administration;

• audit export and enterprise identity controls;

• priority support, procurement and optional SLA terms.

Paid-only features must be enforced by server-side policy and signed entitlements—not just hidden in a dashboard.

Security boundaries

CodeBridge is intentionally not a remote shell product.

• Agents poll outbound.

• Gateway and agent both enforce authorization.

• Projects are explicitly configured.

• Reads/search/logs are bounded.

• Recognized secrets are redacted before results are returned.

• Writes use preconditions and atomic replacement patterns.

• Quality gates are fixed by administrators.

• Commercial entitlements are cryptographically verifiable.

A quality gate still executes real project code. Run untrusted code in a properly isolated environment.

Read SECURITY.md before production use.

Configuration reference

CodeBridge uses JSON configuration as the primary interface. Local/developer mode does not require a large environment-variable surface.

Environment variables

CODEBRIDGE_GATEWAY_CONFIG contains the complete hosted gateway configuration and must be treated as sensitive. Hosted startup fails closed when it is missing or invalid. PORT controls the hosted HTTP listen port; the hosted entry point binds to 0.0.0.0.

Local/developer mode does not require these environment variables; it normally uses private gateway.json and agent.json files created outside the project. Do not commit CODEBRIDGE_GATEWAY_CONFIG, paste it into issues/chat, or put secrets in command-line URLs.

Gateway JSON

Local-model gateway timeout: For local_model_generate and autopilot_local_draft, the gateway holds the device round trip for the explicit requested timeoutSeconds plus up to 15 seconds of delivery headroom, capped at 120,000 ms and never below deviceTimeoutMs. Ordinary file/Git tools retain the configured device timeout. This does not bypass OAuth, model-specific limits, or the local-only no-paid-fallback policy.

Agent JSON

Copy-paste configuration examples

These examples are intentionally conservative: loopback/local where possible, read-only project access, and no real credentials committed to the repository.

Safe local setup

Create a private directory outside the project:

mkdir -p /tmp/kmj-codebridge-private
chmod 700 /tmp/kmj-codebridge-private

Create gateway.json:

{
  "host": "127.0.0.1",
  "port": 8787,
  "users": [
    {
      "id": "owner",
      "tenant": "kmj",
      "tokenHash": "<SHA256_OF_PRIVATE_CLIENT_TOKEN>",
      "devices": {
        "device1": ["project1"]
      },
      "permissions": ["read"]
    }
  ],
  "agents": [
    {
      "id": "device1",
      "tenant": "kmj",
      "tokenHash": "<SHA256_OF_PRIVATE_AGENT_TOKEN>"
    }
  ]
}

Create agent.json:

{
  "gateway": "http://127.0.0.1:8787",
  "token": "<PRIVATE_AGENT_TOKEN_MIN_32_CHARS>",
  "id": "device1",
  "tenant": "kmj",
  "stateDir": "/tmp/kmj-codebridge-private/state",
  "pollMs": 250,
  "projects": [
    {
      "id": "project1",
      "root": "/absolute/path/to/project",
      "writable": false,
      "gates": {}
    }
  ],
  "license": {
    "mode": "free"
  }
}

Start both processes:

npm run gateway -- /tmp/kmj-codebridge-private/gateway.json
npm run agent -- /tmp/kmj-codebridge-private/agent.json

For a real local setup, prefer npm run init -- /private/config-dir /absolute/project because it generates independent random credentials and stores only token hashes in the gateway config.

Safe hosted setup

Store the complete gateway JSON in your hosting provider's private secret/config store, not in the repository.

Example shell environment:

export PORT=10000
export CODEBRIDGE_GATEWAY_CONFIG='{"oauth":{"issuer":"https://auth.example.com","resource":"https://codebridge.example.com/mcp","jwksUri":"https://auth.example.com/.well-known/jwks.json"},"allowedHosts":["codebridge.example.com"],"allowedOrigins":[],"users":[{"id":"owner","tenant":"kmj","subject":"user-123","devices":{"device1":["project1"]},"permissions":["read"]}],"agents":[{"id":"device1","tenant":"kmj","tokenHash":"<SHA256_OF_PRIVATE_AGENT_TOKEN>"}]}'
npm start

Replace auth.example.com, codebridge.example.com, subjects, device/project IDs, and token hashes with your real approved values.

For production, prefer the hosting platform's secret manager over exporting sensitive JSON in an interactive shell. Keep allowedHosts exact, avoid wildcard origins, and do not enable write/execute permissions until they are required.

Minimal local example

npm run init creates private gateway.json, agent.json, and client-token.txt outside the project and starts projects read-only.

{
  "gateway": "http://127.0.0.1:8787",
  "id": "device1",
  "tenant": "kmj",
  "stateDir": "/private/codebridge/state",
  "pollMs": 250,
  "projects": [
    {
      "id": "project1",
      "root": "/absolute/path/to/project",
      "writable": false,
      "gates": {}
    }
  ],
  "license": { "mode": "free" }
}

The real generated agent file also contains a random private token; it is intentionally omitted from this public example.

For deployment-specific details, see docs/DEPLOYMENT.md and docs/OAUTH.md.

Troubleshooting

Use the least-invasive check first. Avoid deleting configuration, regenerating credentials, or changing production permissions until you have identified the failing boundary.

Useful diagnostic commands

Run these from the CodeBridge repository unless the relevant command documents another location:

node --version
npm --version
git status
npm run check
npm test
npm run scan:secrets

For configuration-specific diagnosis, use the built-in CodeBridge diagnostic tooling where available, such as connection_doctor, rather than exposing extra shell access.

Safe recovery order

1. capture the first reproducible error;

2. verify runtime versions and configuration paths;

3. confirm gateway, device, tenant, and project scope;

4. retry the smallest affected operation;

5. rerun the relevant quality gate;

6. rotate credentials only when there is evidence they are invalid or compromised;

7. if the problem persists, open a minimal reproducible issue without including secrets.

Never paste private keys, tokens, enrollment secrets, production credentials, or full private configuration into a public GitHub issue.

FAQ

Do I need to expose SSH or another inbound port?

No. The CodeBridge device agent is designed to initiate outbound connectivity. You still control which device and project roots are authorized.

Can CodeBridge work with a VPS as well as a local computer?

Yes. The agent model is intended for authorized laptops, workstations, and VPS environments, subject to the configured project scope and platform support documented in this repository.

Does CodeBridge give the AI a full shell?

No. CodeBridge intentionally does not expose a generic unrestricted shell tool. Execution is limited to defined tools and administrator-configured quality gates.

Can the AI edit files?

Yes, when write-capable tools are enabled for an authorized project. Writes use preconditions and guarded replacement patterns to reduce blind or stale overwrites.

Can I start read-only?

Yes, and that is the recommended first step. Verify device identity, project scope, and read-only tools before enabling writes.

Which AI clients can use CodeBridge?

The repository includes integration paths for ChatGPT, Claude Code, Claude Desktop, Claude.ai where supported, and other compatible MCP clients. Client capabilities can differ, so use docs/CLIENTS.md as the current integration reference.

Does CodeBridge make untrusted code safe to run?

No. A configured quality gate can execute real project code. Treat untrusted repositories and build scripts as untrusted code and use appropriate isolation.

Are secrets automatically safe?

No security control is absolute. CodeBridge includes bounded output and recognized-secret redaction, but you should still keep credentials and private configuration outside repositories, avoid exposing unnecessary files, and never commit production secrets.

Is hosted production onboarding fully ready?

Not yet. Local/source workflows are usable, while fresh zero-touch production enrollment still depends on the matching KMJ Main Platform enrollment and approval APIs. See docs/STATUS.md and docs/ENROLLMENT.md.

Supported clients

Client capabilities and hosted availability can differ. See docs/CLIENTS.md.

Open core, commercial service

The source in this repository is licensed under Apache License 2.0. You may use, modify and distribute it subject to that license.

KMJ TECHNO’s trademarks, hosted infrastructure, billing/account systems, commercial support and any service-side code not published under an open-source license are separate from the Apache-2.0 grant.

See:

• Launch plans & premium features

• Premium delivery roadmap

• Launch & community playbook

• Commercial Terms

• Licensing & entitlement contract

• Privacy notice

• Security

Current status

CodeBridge is under active development. The repository contains a working Streamable HTTP MCP gateway, outbound device agent, scoped file tools, guarded writes, configured quality gates, durable jobs, entitlement verification and real test coverage.

Production readiness is tracked explicitly; unsupported features are not presented as shipped. See docs/STATUS.md and the local-first production acceptance matrix. Passing source CI, a successful local draft and a public MCP catalog are independent checks—not proof of an autonomous code-to-PR-to-deployment release.

Contributing

Good contributions make CodeBridge safer, more portable, or easier to verify.

Before opening a pull request:

1. keep the change focused;

2. describe the security boundary affected by the change;

3. add or update deterministic tests where behavior changes;

4. run npm run check, npm test, and npm run scan:secrets;

5. do not include credentials, private infrastructure details, or production secrets;

6. avoid weakening authorization, redaction, write preconditions, or quality-gate restrictions merely to make a test pass;

7. include reproducible evidence for compatibility or environment-specific claims.

Useful contributions include:

• MCP client interoperability improvements;

• device-agent compatibility fixes;

• safer file-editing primitives;

• better diagnostics and bounded error reporting;

• security tests;

• documentation and onboarding improvements;

• reproducible platform compatibility results.

Found a bug? Open a minimal reproduction. Need a new tool? Describe the required capability and the intended safety boundary.

Start with CONTRIBUTING.md and SECURITY.md.

If CodeBridge solves a real problem for you, ⭐ star the repository.

A star helps other developers discover the project. A reproducible issue, integration note, test case, or focused pull request helps even more.

License

Copyright 2026 KMJ TECHNO.

KMJ CodeBridge source is licensed under the Apache License 2.0. The Apache License does not grant permission to use KMJ TECHNO trade names, trademarks, service marks or product names except as permitted by applicable law and the license.

About KMJ TECHNO

KMJ CodeBridge is developed by KMJ TECHNO, founded and led by Narendra Singh Kushwah. The company builds AI-native software, secure developer infrastructure, autonomous engineering systems, remote-access technologies, and enterprise digital products.

Learn more at https://kmjtechno.com.

Explore the KMJ open-source ecosystem

If you discovered this project through one KMJ tool, the rest of the stack may be useful too:

• KMJ CodeBridge — secure AI-to-project connectivity for authorized development environments.

• KMJ OmniDesk — direct-first remote access engineered for speed, resilience, and measurable trust.

• KMJ Desktop Commander — policy-controlled desktop and remote engineering operations.

• KMJ Forge — evidence-driven software engineering workflows for humans and AI.

KMJ TECHNO · Innovate · Build · Scale — https://kmjtechno.com