L-Jovi/keyhole

Let ChatGPT read, and carefully edit, only the local folders you choose. No shell, no public port.
**Example: turn a note on your computer into a TODO list, without uploading the file by hand.**
**1. In your terminal, allow the sample folder to be edited.** One-time setup creates
~/KeyholeDemo with a fictional notes.md and shares it read-only as demo. Editing needs an explicit
local command:
**2. In ChatGPT, select your Keyhole app and ask:**
> Read notes.md in demo, turn its three ideas into TODO checkboxes, and save the file.
This is the real response from a session with the same fictional note, shared there as KeyholeDemo:
**3. Back in your terminal, inspect the same file.**
Its three ideas now contain checkboxes. These lines were checked on disk after the edit:
You can ask ChatGPT to restore the returned change id. When finished, run keyhole close demo to stop
sharing the folder. See the complete read → edit → restore → close example, with real screenshots.
Keyhole is a small MCP server that runs on your Mac, Linux or Windows computer, plus a command-line
tool, keyhole. You open a folder with keyhole open; ChatGPT on the web can then read it through OpenAI's
official Secure MCP Tunnel. Give a folder
rw, and ChatGPT can also create and edit text files in it. Every edit is checked against the file's current
hash and recorded before it is applied. Individual file replacements are atomic; retained changes can be restored without overwriting later edits.
Unofficial project; not affiliated with OpenAI.
What you get
- **Read-only by default.** ChatGPT sees a folder only after you open it, and cannot change a file until you
say --access rw. Nothing ChatGPT does can widen its own access: grants are managed by the local CLI only.
- **Careful edits you can undo.** Writes require the file's current SHA-256; updates based on a stale hash
are refused. The previous content is kept in a private local history, and restore_change rolls it back.
- **Several folders, useful file formats.** Open folders independently with their own ro/rw permissions.
Text, PDF, Word, PowerPoint, Excel and images come back with hashes and ranges,
so answers can cite what was read. Document parsers have CPU, time and input-size limits, but run with
your OS permissions; they are not an OS sandbox.
The connection uses OpenAI's official client. It exposes no public endpoint and no remote shell.
Close the last folder and the tunnel stops. Compare related projects.
Start here
**Follow the complete setup guide →**
The setup wizard can download the verified official client, resume incomplete configuration and open a
read-only example. If PyPI is unavailable, use the exact wheel URL from
GitHub Releases.
**On Windows, follow the PowerShell guide instead.** Its install command requests the
x64 Python that Keyhole's dependencies need, on both x64 and ARM PCs.
That is the complete first-time path: check your account access, install the tools, connect your own tunnel,
create a private ChatGPT app, and read a real demo file. Follow it once, from top to bottom. No Python, Git,
Node, Docker or tmux installation is required. You need macOS, Ubuntu Linux or Windows 11, ChatGPT Developer mode and permission to create
an OpenAI Platform tunnel and restricted runtime key. Budget about 15 minutes after account access is ready.
The GitHub repository supplies the software. **You create your own tunnel and private ChatGPT app**;
there is no public Keyhole app to add in one click. OpenAI's Secure MCP Tunnel is for private connections,
not public plugin-store distribution.
What makes it useful
Open several folders independently, keep some read-only, and allow recoverable text edits in others.
Read documents as well as source code, then close a folder when the task is finished. Folder access always
stays under your local control.
Compatibility
| Surface | Verified / limitation |
| --- | --- |
| macOS | Apple silicon, macOS 15.6 and 15.7.7. Intel and older macOS remain untested. |
| Python | 3.11–3.14 in CI; uv supplies Python automatically. |