pickleshell

<h1 align="center"> <img src="docs/assets/pickleshell-logo.png" height="48" alt="PickleShell cucumber logo" align="center"> PickleShell </h1> <p align="center"><strong>Give ChatGPT a local machine to work with</strong></p>

Website: pickleshell.github.io

Want to give your ChatGPT a gift? Give it PickleShell.

<p align="center"> <img src="docs/assets/pickleshell-crt-monitor.png" width="256" alt="PickleShell carrying a CRT monitor"> </p>

PickleShell connects ChatGPT to a local host running three mandatory core services: an Agent, a Browser, and a Terminal. ChatGPT can inspect repositories, edit files, run tests, automate a browser, transfer small files, and coordinate long-running tasks. The connection uses an outbound-only OpenAI Secure MCP Tunnel, while execution remains inside your selected workspace.

The Agent exposes four MCP tools—send-chat, session-status, session-output, and cancel-request—and receives structured results with full traces. The Browser exposes Playwright automation tools. Continue local coding sessions, delegate to an operator-approved model, and transfer files into a controlled workspace.

What PickleShell Is For

PickleShell solves a practical problem: ChatGPT can analyze tasks, but it normally cannot work directly with a local repository.

Through PickleShell, ChatGPT sends instructions and small files to a local Agent, follows the execution, reads the result, and can continue in the same session when it passes the session ID. The same connection reaches the Browser service, and will reach the Terminal service once it is implemented.

The services run on your machine, inside a selected workspace, through a protected outbound-only tunnel. PickleShell removes the human relay between ChatGPT and your machine, while you remain the owner and observer.

PickleShell is for developers and experienced users. Installation is designed to be guided by Codex: ask it to clone the repository, read AGENTS.md, and walk you through the setup step by step using docs/deployment.md and docs/chatgpt.md. AGENTS.md is the contributor guide for the development workflow, architecture, security invariants, and change boundaries.

Use Case

Create three PickleShell tunnels to three different machines, then give the plugins unique names: PickleShell Mars, PickleShell Moon, and PickleShell Starbase. The first tunnel connects to a machine on Mars, the second to a machine on the Moon, and the third to a machine at Starbase. Tell your ChatGPT Assistant which named plugin belongs to which machine, and it can route each task to the right destination.

With this setup, your ChatGPT Assistant can manage colonies on Mars and the Moon, as well as coordinate launches from Starbase to them—the big rockets Elon launches. The same pattern is useful today for everything from saving a technical specification to asking the Agent on a selected machine to carry out a complex task directly from ChatGPT.

[!WARNING] PickleShell is pre-release software (0.1.0). Use it only with trusted users and a dedicated service account. Read SECURITY.md before deployment.

Quick Start

1. Follow the Deployment guide to install the Gateway and tunnel-client on a Linux host.
2. Follow the ChatGPT setup to create the Secure MCP Tunnel, configure the PickleShell plugin, and run the connection test.
3. Send a test message: Reply exactly: pong. Do not use tools or modify files.
4. Poll `session-st