CodeScope

CodeScope helps you use a regular ChatGPT conversation or ChatGPT Project to understand code that stays on your own computer. Install it once, choose the repositories you want to make available, and ask questions in plain language about files, Git history, structure, and design. The intended workflow is to use the quota of that regular ChatGPT conversation for the analysis, rather than ChatGPT Work or Codex. CodeScope only supplies bounded, read-only context from the repositories you select.

Whether you are joining an unfamiliar codebase, tracing a bug, reviewing a change, or deciding what to work on next, CodeScope gives the conversation a safe window into the repositories you selected instead of asking you to upload them or grant write access.

Under the hood, CodeScope is a local, read-only Model Context Protocol (MCP) bridge for explicitly configured repositories. It gives an agent bounded filesystem and Git reads without accepting arbitrary paths, repository roots, or write operations from the conversation.

Read this in Spanish · User guide · Guía de usuario

Development note

CodeScope was primarily developed with assistance from ChatGPT 5.6 Luna Max.

Related MCP server: token-context-mcp

What it does

• maps short repository aliases to local absolute roots;

• reads UTF-8 files and bounded directory listings through an allowlist;

• reads Git status, history, references, and bounded diffs with helper execution disabled;

• keeps repository selection and session access explicit when that mode is enabled;

• exposes versioned advisory design guidance;

• can add Codebase Memory or Context Mode only when a repository-specific, read-only binding has been configured and validated;

• runs over local stdio. Local mode is the only supported transport in this release.

The bridge does not provide a general filesystem server, a Git write API, an arbitrary MCP proxy, or a public HTTP listener by default.

Requirements

• Node.js 24.19 or newer;

• Git available as git or configured with an absolute executable path;

• a local configuration file containing one or more read-only repository entries.

Quick start

Choose one of the two installation routes below. Each command is in its own code block so it can be copied independently.

Option A: global install

Use this route when you want the codescope command to work from any folder:

npm install --global @ellugia/codescope

Then run the guided setup:

codescope setup

Option B: local install with npx

Use this route when you do not want a global npm installation:

npm install @ellugia/codescope

Then run the setup through the local package:

npx codescope setup

Do not use both routes for the same installation. Both routes create the same per-user configuration.

setup creates the user configuration, opens the terminal UI so you can add repositories and optional integrations, and offers to register CodeScope in Codex. It keeps the configuration in the platform configuration directory: %APPDATA%\CodeScope on Windows, ~/Library/Application Support/CodeScope on macOS, or $XDG_CONFIG_HOME/codescope (usually ~/.config/codescope) on Linux. Use --config ./config.json or CODESCOPE_CONFIG only when you explicitly want another location.

To configure the ChatGPT project that will use the MCP, copy the contents of chatgpt/project-instructions.md into its Instructions field. The file gives the agent the recommended repository-selection and safety workflow.

The bridge still enforces access on its own, so these instructions improve the interaction but are not the security boundary.

If you use init for template-only setup, edit the configuration file it prints and replace the example root with an absolute path on the local machine. Every repository must keep read_only set to true:

{
  "git_binary": "git",
  "default_repository": "main",
  "repositories": {
    "main": {
      "root": "C:/path/to/repository",
      "read_only": true
    }
  },
  "optional_backends": {
    "auto_discover": false,
    "bindings": {}
  }
}

The terminal UI can mark a configured repository with enabled: false without deleting it. Disabled entries stay in the local file but are not exposed by the bridge. The UI also preserves and toggles configured read-only Codebase Memory and Context Mode bindings; it does not invent a backend path.

Start the local stdio server:

node node_modules/@ellugia/codescope/bin/codescope.mjs serve

The process reads requests from stdio and writes protocol responses to stdout. Operational logs go to stderr. Local mode does not start a tunnel, open a network listener, or require an OpenAI API key.

npm command

The package includes a small Node CLI. From a checkout:

npm install .

Then run the local CLI with npx:

npx codescope setup

setup creates the user configuration when needed and opens the guided TUI. init remains available for scripted/template-only setup, and serve starts the same stdio bridge as node src/server.mjs. Pass --config ./config.json to keep the configuration beside the current project instead.

For interactive local configuration and diagnostics, run node node_modules/@ellugia/codescope/bin/codescope.mjs ui. The UI manages local setup; serve remains the MCP stdio bridge. The UI can also run serve in the foreground for a local smoke check; press Ctrl+C to stop it. An MCP host normally starts serve itself.

The npm package deliberately excludes deps/, managed profiles, caches, test evidence, Windows launchers, and real repository content.

codex-repositories is an import helper for the local setup flow:

node node_modules/@ellugia/codescope/bin/codescope.mjs codex-repositories

It reads only CODEX_HOME/config.toml. When CODEX_HOME is not set, it checks ~/.codex/config.toml on Linux and macOS, and the equivalent user-home .codex/config.toml on Windows. It extracts [projects.'...'] and [projects."..."] entries as candidates. The user must still choose which candidates to copy into CodeScope's own configuration; a Codex project entry never grants repository access by itself.

Repository and session access

Repository paths never come from an MCP call. The call supplies an alias such as main; the configuration resolves that alias to the approved root. When session_access.mode is session_select, the client must first show the available aliases with bridge_access_status and then explicitly select the alias with bridge_access_select. A session can release one alias or reset all selections.

The model-facing instructions in chatgpt/ are written in English so they are portable between hosts. They explicitly require the agent to keep the user-facing conversation in the user’s language.

Available tools

The base catalog contains read-only filesystem and Git tools plus design_guidance. The exact catalog is returned by MCP tools/list for the active configuration. Optional tools are advertised only after their repository binding has passed validation.

All results are bounded by byte, entry, line, match, depth, timeout, and concurrency limits. Large reads and diffs use signed continuation cursors. Unknown tools, hidden write tools, resources, prompts, sampling, and elicitation are rejected.

Optional integrations

Codebase Memory and Context Mode are optional. Autodiscovery only checks known local installation paths; it does not start a process, index a repository, read credentials, or create a binding. To expose an optional backend, configure it for a specific repository alias, set it to read-only, and restrict its project, root, corpus, and storage paths to that repository. If the binding is not ready, the optional tool stays unavailable while the base filesystem and Git tools continue to work.

Ponytail instructions are also optional and are advertised only after the local installation passes its marker checks. Design guidance remains available without Ponytail.

Security boundary

• repository roots are absolute, configured locally, and checked again before access;

• traversal, alternate root syntaxes, symlinks, reparse points, hard-linked files, and protected paths are rejected;

• .git, environment files, credentials, private keys, certificates, and matching secret content are denied or redacted;

• Git runs without a shell, terminal prompts, external diff helpers, or text converters, and scopes safe.directory to the selected canonical root;

• no repository write operation is exposed;

• the bridge makes no network connection in local mode; repository access comes only from its local configuration.

These controls are enforced by the bridge. MCP annotations such as readOnlyHint are descriptive metadata and are not used as an authorization mechanism.

Checks

node scripts/self-check.mjs
node scripts/doctor.mjs

scripts/self-check.mjs creates and removes disposable test data and verifies filesystem, Git, cursor, limit, secret, and MCP-surface invariants. scripts/doctor.mjs checks the configured repositories without starting another service. Tests that exercise a separately launched bridge require BRIDGE_COMMAND and BRIDGE_ARGS_JSON; an unset harness is reported as blocked rather than silently passing.

Local command surface

The Node CLI and terminal UI are the supported local command surface on Windows, Linux, and macOS. With the normal local install, use node node_modules/@ellugia/codescope/bin/codescope.mjs <command> for manual setup, serving, diagnostics, and Codex repository discovery. The shorter codescope <command> form is equivalent when the package bin is already on your PATH. PowerShell launchers, tunnel scripts, and remote authentication are outside this release.

Project status

The release scope is local-only. Before publishing, run npm pack --dry-run and complete a local stdio canary on the supported operating systems. No tunnel or remote authentication is part of this release.

License

CodeScope is released under the MIT License. You may use, modify, and redistribute it while retaining the copyright and license notice.