ReadOnly Observer

简体中文

Give an MCP client an evidence-based, read-only view of the local projects and individual Codex sessions you explicitly approve.

0.1.0 · Alpha / experimental. Public versioning starts at 0.1.0. Real Codex-session acceptance and support on other platforms remain unverified.

Features

• Understand a codebase. Browse and search approved source, follow implementations across files, and cite paths, lines and source hashes.

• Review a Codex session. Read public context and execution results from one registered JSONL file, including paginated long output. No history-wide discovery.

• Compare evidence. Relate session records to current source and bounded Git status, diffs and HEAD history, without treating “finished” as proof of correctness.

Example questions to ask after connecting (not recorded results):

• “In app, trace startup through registration across files. Cite paths and lines.”

• “In the approved task session, what execution results are recorded, and what remains unknown?”

• “Compare this session's evidence with the current source. Distinguish recorded claims from verified observations.”

Read-only by design: a new instance has no sources. Only the local operator can approve a project or exact session file. MCP cannot register sources, execute project commands or tests, control sessions, or read hidden reasoning. Mentioning a path in chat grants no access.

Approved UTF-8 source can include safe ignored/untracked files. Sensitive paths, symlinks and hardlinks are rejected; redaction cannot detect every secret. Git uses sealed snapshots with a 100 MB (100,000,000 bytes) combined budget for metadata, objects and selected worktree content. Local/remote refs and ordinary packs are supported. Paths narrow worktree copying and Git queries; history and staged diffs need no worktree. Unsupported layouts or exhausted budgets return a failure, never a clean result. This is a single-operator service, not a per-user authorization system. See security boundaries.

Related MCP server: codex-with-claude

Quick start

1. Install from source

You need macOS, Python 3.14 with venv/pip, and a local MCP client that supports stdio. Git is optional for source reads, required for Git and joint evidence. The recorded test target is macOS 14.7.8 / Apple Silicon / CPython 3.14.3; other Macs and Linux are unverified, and Windows is unsupported. Linux has no bundled Keychain adapter.

Download and extract the source archive from v0.1.0 Release, or clone the source repository. There is no public PyPI installation. In the source directory containing pyproject.toml, run:

python3.14 -m venv .venv
.venv/bin/python -m pip install .
OBSERVER="$PWD/.venv/bin/observer"
"$OBSERVER" --version

Dependencies come from your configured package index, so this normally requires network access. Keep the environment at its installed path. This source installation does not bundle Python, Git or the optional Secure MCP Tunnel client.

2. Create an empty instance

"$OBSERVER" init --non-interactive

This creates private instance files, not a service or source grant. On macOS the default home is ~/Library/Application Support/ReadOnlyObserver. For a custom home, place --home /absolute/private/instance before every subcommand, including the client's serve argument. Keep it outside your observed project and installation, at a short private path without symlink ancestors. See instance configuration.

3. Approve one project locally

Replace the path with a project you are authorized to expose:

"$OBSERVER" project add /absolute/path/to/project --alias app
"$OBSERVER" project list
"$OBSERVER" config validate --check-sources
"$OBSERVER" doctor --level local --probe

Review the displayed scope and type approve in your terminal. project list should show app; validation should report service_can_start=true. A successful probe reports local_protocol_verified, not remote ChatGPT readiness.

4. Connect your local MCP client

Configure a stdio server with the absolute executable path printed by printf '%s\n' "$OBSERVER" and the argument serve. For clients using an mcpServers configuration, the entry looks like:

{
  "mcpServers": {
    "observer": {
      "command": "/absolute/path/to/source/.venv/bin/observer",
      "args": ["serve"]
    }
  }
}

Replace the example path; shell variables and ~ are not guaranteed to expand in client settings. Adapt the surrounding configuration to your client's documentation. The client starts and stops this process; observer start is not needed for serve. Managed start/connect is an alternative covered in the manual.

5. Confirm your first read

In that client, request these MCP calls:

observer_info({})
workspace_read({"alias":"app","path":"README.md"})

These are tool-call examples, not shell commands. If your project has no README.md, first call workspace_list({"alias":"app"}) and select an existing, harmless UTF-8 file.

Check that observer_info returns ok=true, the installed version, and app in workspaces. The read should return that file's redacted content, physical line locations and source version. Follow any next_cursor until selection_complete=true and next_cursor=null; a preview is not a complete read. If a step fails, see troubleshooting.

Optional: approve a Codex session

Session reading is implemented, but requires a separately approved, persisted JSONL file selected by you:

"$OBSERVER" session add /absolute/path/to/chosen.jsonl --alias task
"$OBSERVER" session list

Review the file and metadata-ID scope locally, then reconnect the MCP client. Only this file is approved, not its directory or other sessions. Exact IDs and explicitly mapped links are supported; unmapped cloud links and non-persisted sessions cannot be recovered. See session registration and references.

Any source-registration change (adding, removing or mapping a source) requires new MCP processes: reconnect direct serve clients, or stop/start the managed instance and reconnect its clients. Old processes retain their approved snapshot until stopped.

Connect ChatGPT

Ordinary remote ChatGPT needs both account/workspace support for a custom MCP connection and a separately protected transport. The local stdio quick start does not supply either prerequisite, and Observer does not expose an HTTP server.

An optional adapter supports an independently installed official Secure MCP Tunnel client and an existing tunnel. It does not create tunnels, install the client, create credentials or grant account access. Adapter support does not imply availability for every ChatGPT account.

Follow the Tunnel setup and verification guide and the current OpenAI connection guide for your account. Never put a key in chat, command arguments or configuration. Verify observer_info and a harmless file from the actual ChatGPT connection; doctor never establishes remote readiness.

Documentation

• User manual — sessions, transports, evidence and pagination (Chinese).

• CLI and configuration reference — commands, instance layout and all 13 MCP tools (Chinese).

• Troubleshooting — refusals and incomplete reads (Chinese).

• Upgrade, rollback and uninstall — preserve the original instance and approvals (Chinese).

• Architecture · Security · Distribution scope.

Development / contributing

Use the development guide for isolated synthetic tests, SDK checks, builds, clean exports and contribution requirements. Tests do not require your real sessions, credentials or ChatGPT connection. Submit ordinary bug reports through Issues and proposed changes through pull requests. Keep private data out of patches and follow SECURITY.md for security reporting.

License

ReadOnly Observer is licensed under the MIT License, copyright 2026 liuhuijiayou. Dependencies retain their own terms; see third-party notices and the distribution scope.