ReadOnly Observer
Provides read-only inspection of approved Git repositories, including bounded status, staged diffs, HEAD history, and sealed snapshots for evidence comparison.
Enables read-only review of registered Codex session JSONL files, including public context and execution results with pagination, and supports optional ChatGPT connection via Secure MCP Tunnel.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
ReadOnly Observer
简体中文 · Linux / multi-node deployment · systemd 219
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. The same code supports macOS and independent Linux nodes. Linux installation and upgrades use the interactive terminal wizard below; current verification is recorded in the wizard audit. Use a reviewed revision containing these scripts; this wizard change awaits human review and has not been published by the assistant.
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
tasksession, 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
Linux: recommended installation and upgrade
Prepare root/sudo, Bash, Python 3.14+ with venv/ensurepip, /usr/bin/git 2.28+, active systemd 219+, 1 GiB free space, and an already installed/verified official Tunnel Client. The wizard checks these prerequisites and does not upgrade the OS/systemd or download a Tunnel executable.
git clone https://github.com/liuhuijiayou/readonly-observer.git
cd readonly-observer
sudo bash scripts/install_linux_node.shThe terminal collects Node Name, Installation Directory, independent Instance Home, project path/alias, optional exact JSONL/alias, Tunnel Display Name, an explicitly entered Tunnel ID, confirmed/detected Client path, hidden Runtime API Key, proxy choice/hidden URL, unit name and startup choice. No script, JSON or environment editing is required. Every source grant requires approve; keys are entered only through Observer's existing hidden-TTY CLI. No Platform resources or ChatGPT connections are created automatically.
sudo bash scripts/install_linux_node.sh --dry-run
sudo bash scripts/install_linux_node.sh --no-start
sudo bash scripts/upgrade_linux_node.sh --home /var/lib/readonly-observer/linux2 --ref REVIEWED_COMMIT_OR_TAGFlags can prefill non-secret metadata; real installation still requires a human TTY. Existing homes/units are refused. Interrupted owned installs use --resume --install-dir ...; upgrades retain the old release/venv and provide explicit rollback. See the installation, upgrade and recovery SOP. Manual steps below remain useful for macOS and Linux recovery.
Manual quick start
1. Install from source
You need macOS or Linux, Python 3.14+ with venv/pip, and a local MCP client that supports stdio. Git 2.28+ is required for Git and joint evidence, optional for ordinary reads. Linux Tunnel deployment supports systemd 219+ (checked tmpfs staging before 247, native LoadCredential from 247); see the complete deployment guide. Existing macOS Keychain, v1 configuration and lifecycle behavior are retained; no action is required on an existing stable Mac. Windows is unsupported. Native Mac verification and actual remote acceptance for the current revision remain pending; see the audit.
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" --versionDependencies 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-interactiveThis 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 --probeReview 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 listReview 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).
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.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Read-only MCP access to authorized Vocci sessions, notes, files, and memory search.
Read-only release evidence for coding agents: findings, deliveries, source and runtime data.
Review connected software projects, submit local findings and read reports with explicit approval.
Permission-aware onboarding MCP server: answers about a codebase, filtered by the caller's role.
Related MCP Servers
- AlicenseAqualityBmaintenanceProvides a read-only interface to audit and continue coding agent sessions by extracting plans, intents, and edit authorship from history across multiple agents (Claude, Codex, OpenCode, Antigravity, Pi) via MCP, CLI, and Python SDK.1825 PyPI3MIT
- AlicenseNot gradedqualityBmaintenanceProvides a read-only MCP bridge that lets Claude Web inspect workspace files, git state, and recorded test results while Codex remains the sole executor of changes.542 npm2MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI clients to observe local codebases in real time through a secure, read-only MCP interface, providing workspace snapshots, git history and diffs, cross-project search, and project reality coverage without write access.MIT
- AlicenseBqualityCmaintenanceEnables MCP clients to drive local Codex on a target Git repository: inspect repo state, start and follow up on tasks, review events and diffs, and record audit evidence for research governance.272MIT