keyhole

Keyhole is a small MCP server that runs on your Mac, Linux, or Windows computer and also provides a command-line tool called keyhole. You open a folder with keyhole open, and web-based ChatGPT can read it via OpenAI's official Secure MCP Tunnel; if you grant the folder rw permission, ChatGPT can also create and edit text files in it. Every edit is compared against the file's current hash and recorded before being applied, individual file replacements are atomic, and retained changes can be restored without overwriting subsequent edits.

This project is unofficial and is not affiliated with OpenAI.

Main capabilities

• Read-only by default: ChatGPT can only see a folder after you open it; ChatGPT cannot modify files until you say --access rw. ChatGPT itself cannot expand permissions; authorization is managed only by the local CLI.
• Reversible, careful edits: writes require the file's current SHA-256; updates based on a stale hash are rejected. Previous content is kept in private local history, and restore_change can roll it back.
• Multiple folders and multiple file formats: multiple folders can be opened independently, each with its own ro/rw permissions. Text, PDF, Word, PowerPoint, Excel, and images are returned with hashes and ranges, and answers can cite what was read. Document parsers have CPU, time, and input size limits, but run with your operating system permissions and are not an operating system sandbox.
• Connections use the official OpenAI client: no public endpoint is exposed, and there is no remote shell. When the last folder is closed, the tunnel stops.

How to use

1. In the terminal, allow the example folder to be edited. A one-time setup creates ~/KeyholeDemo, containing a fictional notes.md, and shares it read-only as demo. Editing requires an explicit local command.
2. In ChatGPT, select your Keyhole app and make a request, for example: Read notes.md in demo, turn its three ideas into TODO checkboxes, and save the file.
3. Return to the terminal and check the same file; the three ideas now contain checkboxes. You can ask ChatGPT to restreturns the change id; when done, run keyhole close demo to stop sharing the folder.

The setup wizard can download the verified official client, restore an unfinished configuration, and open a read-only example. If PyPI is unavailable, you can use the exact wheel URL from GitHub Releases. On Windows, use the PowerShell guide instead; its install command requests the x64 Python required by Keyhole dependencies, on both x64 and ARM computers. The first full walkthrough takes about 15 minutes (once account access is ready): check account access, install the tools, connect your own tunnel, create a private ChatGPT app, and read a real example file. No need to install Python, Git, Node, Docker, or tmux. Requires macOS, Ubuntu Linux, or Windows 11, ChatGPT developer mode, and permission to create OpenAI Platform tunnels and restricted runtime keys.

The GitHub repository provides the software. You need to create your own tunnel and private ChatGPT app; there is no one-click public Keyhole app to add. OpenAI's Secure MCP Tunnel is for private connections, not public plugin store distribution.

Use cases

• Open multiple folders independently, keep some read-only, and allow recoverable text edits in others.
• Read both documentation and source code, and close the folder when the task is done. Folder access is always controlled locally by you.
• Example requests: read app/src/config.py, fix the typo in the error message, then read the file back to confirm; search notes for "invoice", then quote the matching lines and their file paths.

Write behavior: when editing, ChatGPT reads the file and its hash, proposes changes, and calls apply_text_patch or write_file. Whether ChatGPT asks you before writing depends on ChatGPT's settings for the app itself (it asks by default, and can remember your answer for one conversation); if you never see a prompt, check the app details.

Capabilities by file type Copy, move, delete, and restore treat each regular file no larger than 8 MiB as opaque bytes, so they also work for binary files. Keyhole cannot write Office documents, PDF or images, and it does not run code, macros, or formulas.

Limits: text files up to 8 MiB; documents and images up to 64 MiB; 400 lines or 64 KiB per read; 1 MiB per write_file; single files only, no recursive directory operations. Each response states when it was truncated.

Recovery history Every change made by ChatGPT is written to ~/.config/keyhole/changes.sqlite3 before the file is touched (readable only by you): path, hash, and the default previous contents. restore_change and keyhole history use this data. ChatGPT can see paths, hashes, and change ids, but never the stored contents.

History is capped at 1000 records or 450 MiB. When full, the oldest completed records are automatically discarded; interrupted operations are never discarded. Recovery can temporarily reserve one extra record and 48 MiB, so that a full history does not hinder repairs. Retry an interrupted recovery with the same request id; after a successful recovery, history returns to the normal cap.

Closing or forgetting a folder keeps its history. keyhole purge-history --before 2026-01-01 --confirm deletes completed records before a given date. Eviction or purging also removes the recovery and replay protection for those records; history is not a permanent audit log.

If you prefer your own version control, keyhole open <dir> --access rw --recovery off keeps only paths and hashes. Edits still go through hash verification, and interrupted operations can still be repaired, but restore_change will refuse committed edits for that folder.

Security settings Grants are stored in ~/.config/keyhole/grants.json and changed only through keyhole. No remote tool can add folders, run commands, use Git, or fetch URLs.

Names such as .git, .ssh, .env*, *.key, *.pem, credentials.json, node_modules, and agent state directories are hidden at any depth and any size written. keyhole open prints the full list.

Custom --exclude rules: patterns without a slash hide matching names at any depth (Private, .log); patterns containing a slash are anchored at the folder root and hide that subtree (Secret/, docs/*.md). Matching ignores case and Unicode normalization.

ChatGPT can never modify Keyhole's own code or environment, state directory, or shell startup files such as .zshrc and .envrc, regardless of which path form it uses.

Symbolic links, hard-linked files, and special files are rejected. Paths are opened component by component using O_NOFOLLOW on macOS/Linux, using parent directory handles on Windows, and are re-checked before and after each operation.

Hiding by filename is not secret detection: tokens in shared source files can be read while the folder is open, and anything already sent to ChatGPT cannot be recalled by closing the folder. See SECURITY.md for the threat model, out-of-scope content, and how to report vulnerabilities.

Commands and Tools Commands print JSON by default; "ok": false comes with an error.code you can handle accordingly. status --human prints readable text. The settings/status options above require Keyhole 0.4.0 or later.

The five read tools are marked read-only, and the seven write tools are marked destructive, which is the basis for ChatGPT's write confirmation. See docs/reference.md for full parameters, error codes, and limits. See maintenance for upgrading, custom paths, and uninstalling.

Terminology and Troubleshooting Workspace: an opened folder, shown to ChatGPT by name. Not a ChatGPT workspace (team account). ro / rw: read-only / read-write. New folders are ro. Runtime: the tunnel-client process that keeps the tunnel connection and the Keyhole server running. Chat vs Work: ChatGPT's compose mode. Keyhole is tested in pure Chat mode; Work is not required.

Non-goals and When to Use Something Else Keyhole does not run shell commands, tests, or Git, does not control your screen, does not expose public endpoints, and does not let remote parties manage authorization. If you use the ChatGPT desktop app, its local Work mode may already meet your needs on this machine. If you want ChatGPT to run commands in a repository, usea coding-oriented tool. Keyhole is aimed at web-based ChatGPT, documents as evidence, and careful editing.

Optional: Codex Companion skills/keyhole/ is a skill for OpenAI Codex that lets it run keyhole and explain the boundaries when you explicitly instruct it to. Link that directory into ~/.codex/skills/ (the layout Codex discovers); .codex-plugin/plugin.json describes the same skill for the Codex plugin installer. ChatGPT does not need it.

Tracked content: the server and CLI (src/keyhole/), tests, docs, the Codex skill. Runtime state, secrets, authorization, and recovery history live in ~/.config/keyhole/ and never belong in the repository.

Maintained by Jovi; best-effort, single maintainer. See issues for bugs and ideas. See CONTRIBUTING.md for how to develop. See CHANGELOG.md for changes.