Skip to main content
Glama
claude-tools-gateway
by huaqing0

Claude Tools Native Gateway

In one sentence: Make web ChatGPT the sole brain, driving real local Claude Code native Sessions to perform controlled reads, modifications, verification, and recovery.

The public repository contains only source code and tests; it does not include local keys, Tunnel configuration, or state/ session state.

Architecture

The Gateway now has only one execution engine: Native V2.

当前 ChatGPT Chat(唯一主脑)
  ↔ Claude Tools Native MCP(六个 Session 控制工具)
      ↔ 本地模型回合桥(127.0.0.1)
          ↔ 隔离的 Claude Code 原生 Session
              → 原生 Agent loop
              → 网关自有的受控工具 Executor

The Gateway itself handles MCP initialization, tool inventory, and call dispatch; it no longer starts or proxies V1's claude mcp serve tool server. A Claude Code process dedicated to a Session is started only after the Native Session is created.

The original V1 Agent Session, top-level Read/Edit/Write/Bash, local task tools, legacy DeepSeek delegation, and ChatGPT Bridge have been removed from the runtime entry points and the code tree. What remains are the shared low-level facilities V2 still needs: atomic state writes, credential path protection, process identity verification, and macOS sandbox rules. Old V1 state files are not automatically deleted, but the Native Gateway will not read or execute them.

Related MCP server: claude-code-bridge-mcp

MCP Control Plane

The web version sees only six tools:

  • native_session_start

  • native_session_continue

  • native_session_recover

  • native_session_reply_and_wait

  • native_session_status

  • native_session_stop

Any V1 tool name, top-level file tool, Bash, legacy DeepSeek tool, or other MCP method is rejected server-side, rather than merely hidden from the tool list.

Claude Code Session Capabilities

Sessions have three distinct tiers; after creation, they cannot be upgraded, downgraded, or have their root directory changed:

  • read_only: Read, FindFiles, SearchText, and read-only RunCommand; the read scope is the entire computer, except for protected state/credential paths and macOS permissions.

  • direct_write: adds Edit, Write, and NotebookEdit on top of full-computer read capability, modifying only the real directory the user explicitly selected. This tier should only be chosen when the user explicitly asks to modify real files.

  • worktree_write: the tool set is the same as direct_write, but modifications go to a separate Git worktree created and retained by the Gateway; the source checkout remains unchanged.

These are logical tools the model can call in Claude Code's native Agent loop, but the executors belong to the Gateway. Unregulated Claude Code built-in file tools and Bash remain disabled, to avoid bypassing action authorization, hashing, recovery, and the audit ledger.

  • Read can read any unprotected plain UTF-8 file on the computer, no longer restricted to the write directory.

  • FindFiles performs bounded file enumeration from any absolute directory.

  • SearchText does UTF-8 literal matching only; it does not accept regex or glob.

  • Searches do not follow symbolic links and skip .git, protected paths, and external hard links.

  • Both a single search result and a full action receipt are limited to 64 KiB.

  • All tiers can inspect different disks and directories; working_directory is only the default search location, the command CWD, and the write boundary for write tiers. macOS TCC/file permissions may still deny Desktop, Documents, or other system-protected locations.

File and Notebook Modification

  • Under direct_write, Edit, Write, and NotebookEdit modify the real directory bound to the Session; under worktree_write, they modify only the managed worktree.

  • Write can create missing parent directories on demand within the authorized root, then atomically create the target file; it cannot use this to escape the root, symbolic links, .git, or protected paths.

  • NotebookEdit supports replacing, inserting, and deleting cells by cell ID, but does not execute the Notebook.

  • Every write action saves pre-write and post-write SHA-256 and uses prepare, CAS, atomic persistence, and a durable receipt.

  • After a process crash, the real file state is verified; if it cannot be determined, recovery stops rather than blindly repeating the write.

  • direct_write has no file deletion tool and does not write files because of read-only check commands; it may still overwrite or modify target files per explicit user instructions.

  • In worktree_write, the source checkout's files, HEAD, tree, index, and working tree state remain unchanged; the Git common dir registers a retained worktree.

Verification Commands

RunCommand accepts installed system commands and executables inside the Session directory; it no longer maintains a static command whitelist that could easily break normal development tools. Arguments are still passed as exact argv, never assembled into a shell string by the Gateway:

  • The Session root filesystem is read-only from the command's perspective;

  • Network, process signals, Keychain/XPC, and model CLIs are blocked by the macOS Seatbelt;

  • Entry points such as sudo, direct delete/move, system control, find -delete/-exec, rg --pre, and model CLIs remain explicitly rejected;

  • Symbolic links, hard links, or file counts in ordinary projects no longer cause the command to be rejected for the entire repository before startup; actual access is constrained by Seatbelt, protected paths, and macOS permissions;

  • Output, runtime, and subprocess group reclamation all have bounds;

  • Results first enter the same action ledger, then are handed to the next GPT turn.

It is intended for trusted repository verification, not as a container against malicious processes running under the same macOS account. Do not concurrently modify the managed worktree with other editors or processes while the Session is running.

Main Model, Web Search, and DeepSeek

The main route is fixed to chatgpt-main and does not accept model, provider, endpoint, API key, or fallback parameters. When the current ChatGPT turn stops, Claude Code pauses at waiting_for_gpt; it will not switch to Claude, DeepSeek, or Codex on its own to continue thinking.

Web search continues to be handled by web ChatGPT. Claude Code's WebSearch/WebFetch are not enabled, so there is no risk of GPT search conflicting with Claude's own search or of sources getting out of control.

By default, subagent_policy: "none" means no DeepSeek is created. Only after worktree_write explicitly selects deepseek_explicit can GPT use it in the main loop:

  • deepseek_subagent_start

  • deepseek_subagent_get

  • deepseek_subagent_stop

Delegation must first enter the main Session's persistent action ledger before the isolated sub-Session is allowed through. While a subtask is running, the main Session cannot concurrently Edit, Write, NotebookEdit, RunCommand, or start a second subtask. The route is fixed as Sonnet/Opus → Flash, Fable → Pro; failures do not fall back to Claude, Codex, OpenAI, or another DeepSeek tier.

Skill Context

native_session_start can accept up to eight skill_contexts explicitly selected by ChatGPT. They are not Claude Code's native Skill runtime:

  • Only the validated instruction body is extracted and frozen;

  • Scripts, resources, plugins, Hooks, Slash Commands, and extra tools are not loaded;

  • Each allowed item pins both the skill ID and the SHA-256 of the normalized full SKILL.md;

  • The first start and subsequent resume use the same persistent snapshot;

  • The full body appears only in 0600 private state and in the model context the current GPT turn requires.

Example allowlist:

CLAUDE_TOOLS_NATIVE_SKILL_ALLOWLIST_JSON='[{"skill_id":"personal:review","content_sha256":"<64位小写SHA-256>"}]' \
npm start

The hash is computed over the full text after removing the UTF-8 BOM and normalizing CRLF/CR to LF.

Isolation and Recovery

  • Each Session uses an independent HOME, Claude config directory, runtime directory, and process group.

  • Claude Code runs with --bare, empty setting sources, strict MCP configuration, and a precise tool set.

  • The main Claude process can only reach the exact local Broker/Executor loopback port.

  • Credential directories, Gateway state, .git, symbolic links, and external hard links all fail closed; access to ordinary system/user paths is determined jointly by the Session root, macOS TCC, and file permissions.

  • ChatGPT replies and each approved action are atomically persisted before being released to the running process.

  • Lease expiry stops the Runner and leaves an inspectable state.

  • A Gateway restart does not kill a Runner that still belongs to a Session; native_session_recover verifies ownership, rotates the lease, and continues the same Claude Code Session.

  • When the Runner no longer exists, recovery is not faked, and completed actions are not repeated.

Claude Code 2.1.247 has no verified standalone switch to "enable only Hooks while continuing to disable keychain, plugins, and automatic memory," so native Hooks, native Skill/Slash, Agent, Workflow, Web, and third-party MCP not governed by the action ledger remain disabled.

Running

npm start

The Native Gateway no longer needs the CLAUDE_TOOLS_NATIVE_V2 or CLAUDE_TOOLS_NATIVE_V2_ONLY switches; Native-only is the only runtime mode.

State is saved in state/ by default and can be changed via the absolute-path environment variable CLAUDE_TOOLS_STATE_DIR. The default Claude Code path is $HOME/.npm-global/bin/claude and can be overridden with CLAUDE_BIN.

Long-running Tunnel/Connector instances need to be restarted after source updates. ChatGPT may cache the connected tool schema; if a new session does not see the six native_session_* tools, refresh or reconnect the Claude Tools Connector.

Verification

npm test
npm run test:native:installed
npm run test:native:installed:write
npm run test:native:installed:direct-write
npm run test:native:installed:deepseek
npm run test:native:installed:skills

Automated tests cover:

  • Native-only MCP direct initialization, the exact six tools, and rejection of V1 tools and unknown methods;

  • Turn and action ledger, reply idempotency, leases, process ownership, stop and recovery;

  • Read/FindFiles/SearchText full-computer reads, protected paths, size, ordering, literal matching, and race boundaries;

  • Edit/Write/NotebookEdit direct real-directory writes, worktree isolation, CAS, hashing, and crash recovery;

  • RunCommand permissive development command entry points, Session-local executables, read-only filesystem, zero network, sensitive service blocking, and timeout reclamation;

  • Skill ID/body hash pinning, start/resume consistency, and private state boundaries;

  • DeepSeek explicit delegation startup barrier, single-task write lock, route verification, Gateway restart recovery, and stop;

  • Public MCP/Session/history does not leak authorization IDs, Runner tokens, PIDs, internal paths, or model credentials.

Installed tests use the local Claude Code 2.1.247 and a localhost scripted GPT, without connecting to real models:

  • test:native:installed: executes FindFiles → literal SearchText → Read → final with / as the read-only root, and recovers the same Runner/Claude Session after the Gateway disconnects.

  • test:native:installed:write: Read → Edit → Write → NotebookEdit → RunCommand → resume → Read.

  • test:native:installed:direct-write: the same set of real Claude Code turns directly modifies a real directory in the test fixture, then resumes and verifies the persisted results.

  • test:native:installed:deepseek: uses a local fake DeepSeek CLI to verify explicit delegation, result verification, active write lock, restart recovery, and stop.

  • test:native:installed:skills: verifies that two hash-pinned, instruction-only Skills use the same snapshot across start/resume.

These local scripted tests do not consume real ChatGPT, Claude, or DeepSeek model quota. A real DeepSeek minimal smoke test still requires separate user authorization.

Available Tools

6 tools
native_session_continueA
Idempotent

Continue the same durable native Claude Code session without changing its immutable capability profile or filesystem root. ChatGPT remains the sole main model. A direct_write Session continues to address the same real directory; a worktree_write Session continues in its retained managed worktree. A Session created with deepseek_explicit may inspect or stop its explicitly started DeepSeek subagent; the subagent never takes over the main loop.

Inputs: prompt (required), lease_id (required), idempotency_key (required), native_session_id (required), +1 more. Returns: Durable public state for the ChatGPT-owned native Claude Code Session.

native_session_recoverB
Idempotent

Reconnect ChatGPT to a durable native Claude Code session and rotate its lease. ChatGPT remains the sole main model. Any DeepSeek access remains limited to the Session's original explicit subagent policy; a write session is accepted only after its original direct directory or retained managed worktree binding is verified.

Inputs: recovery_id (required), recovery_token (required), native_session_id (required), wait_seconds. Returns: Durable public state for the ChatGPT-owned native Claude Code Session.

native_session_reply_and_waitA
DestructiveIdempotent

Submit ChatGPT's response for one exact pending native turn. ChatGPT is always the sole main model. Every profile permits bounded whole-computer Read, FindFiles, literal SearchText, and a network-blocked, filesystem-read-only RunCommand except on protected credential/state paths. direct_write permits gateway-authorized Edit, Write, and NotebookEdit only inside the selected real write root. worktree_write permits the same mutations only inside its retained managed worktree. A Session created with deepseek_explicit may additionally start, inspect, or stop one explicit DeepSeek subagent; start must be the only call in that response.

Inputs: turn_id (required), lease_id (required), reply_id (required), native_session_id (required), +2 more. Returns: Durable public state for the ChatGPT-owned native Claude Code Session.

native_session_startA
Idempotent

Start an isolated native Claude Code session with the current ChatGPT conversation as the sole main model. subagent_policy defaults to none. All profiles may use Read, FindFiles, literal SearchText, and a network-blocked, filesystem-read-only RunCommand across the computer except protected credential/state paths. working_directory remains the command CWD and, for write profiles, the only write root. read_only never writes. When the user explicitly asks to modify the actual files in working_directory, choose direct_write; it works for Git and non-Git directories. Choose worktree_write only for an isolated copy of a clean Git repository. deepseek_explicit remains available only with worktree_write; DeepSeek never becomes the main model.

Inputs: prompt (required), idempotency_key (required), working_directory (required), wait_seconds, +4 more. Returns: Durable public state for the ChatGPT-owned native Claude Code Session.

native_session_statusA
Read-onlyIdempotent

Read native-session state without advancing it or invoking a model. ChatGPT remains the sole main model. Safe summaries of any explicitly enabled DeepSeek subagent and the retained managed-worktree location are returned when present.

Inputs: lease_id (required), native_session_id (required), wait_seconds. Returns: Durable public state for the ChatGPT-owned native Claude Code Session.

native_session_stopA
DestructiveIdempotent

Stop the isolated native-session process and preserve durable state and any managed worktree for inspection. ChatGPT remains the sole main model. Any active Session-owned DeepSeek subagent must be safely stopped and durably observed before the Session can finalize.

Inputs: lease_id (required), request_id (required), native_session_id (required), reason. Returns: Durable public state for the ChatGPT-owned native Claude Code Session.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 6 tools

    Disambiguation4/5

    Each tool maps to a distinct lifecycle action such as start, continue, recover, reply, status, or stop. The only mild ambiguity is between continue and recover, since both involve reconnecting to an existing session, though the descriptions differentiate them by lease rotation and capability immutability.

    Naming Consistency5/5

    All tool names follow the same native_session_ prefix with an imperative verb or verb phrase. The naming pattern is uniform and predictable, making the tool set easy to navigate.

    Tool Count5/5

    Six tools is well-scoped for a session gateway: creation, continuation, recovery, interaction, status inspection, and shutdown. Each tool has a clear role without redundancy.

    Completeness5/5

    The tool set covers the full lifecycle of a native session: start it, continue or recover it, send replies, check status, and stop it. Stop preserves durable state rather than losing it, so the workflows do not end in a dead end.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Provides comprehensive session management for Claude Code with automatic initialization/cleanup, quality checkpoints, and local conversation memory with semantic search for capturing learnings across coding sessions.
      6
      338 PyPI
      4
      BSD 3-Clause
    • A
      license
      Not graded
      quality
      D
      maintenance
      Bridges Claude Code terminal sessions with Claude Chat by exposing session logs as tools, enabling seamless context transfer and two-way communication via a cooperative inbox and optional Google Drive sync.
      127 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      A secure, local-first MCP coding and computer-use harness for ChatGPT and Codex, enabling guarded file operations, durable terminals, Git review, local skills, and macOS computer control.
      142 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables voice assistants to start, monitor, message, and approve local Claude Code sessions on your computer, including sessions already open in a terminal. It exposes session management, recaps, approvals, and history search as MCP tools.
      7
      GPL 3.0