ouroboros-workspace-bridge

English | [한국어](README.ko.md) # Ouroboros Workspace Bridge <p align="center"> <img src="assets/brand/ouroboros-by-KwakWooJae.png" alt="Ouroboros by KwakWooJae logo" width="220"> </p> Local-first MCP bridge for safely letting ChatGPT work inside your workspace. Ouroboros Workspace Bridge lets ChatGPT inspect a local project and propose file edits or commands without applying them directly. Mutating work is staged as a durable bundle and governed by the local approval policy: **Normal** requires a manual review click, while **Safe Auto** and **YOLO** can authorize eligible bundles without that click. The local runner still performs execution-time validation, backup/rollback handling, and terminal-state recording. Part of Ouroboros by KwakWooJae. Author: KwakWooJae ## Why use this? - ChatGPT can inspect your local project under a configured `WORKSPACE_ROOT`. - File edits are staged as reviewable proposals. - Commands run only after the configured local approval policy authorizes the bundle; Normal is manual, while Safe Auto/YOLO may auto-authorize. - Runtime data stays outside your repository. - Built for `uv run terminalbridge ...` operation with `uv run woojae ...` available for low-level diagnostics. ## Quick Start Prerequisites: Python 3.12+, `uv`, and a ChatGPT environment that can create a custom MCP app/connector. Each installation uses that user's own ngrok account, Cloudflare account/tunnel/domain, or another external HTTPS connector. macOS/Linux: ```bash git clone https://github.com/kwj903/ouroboros-workspace-bridge.git cd ouroboros-workspace-bridge uv sync uv run terminalbridge setup uv run terminalbridge start uv run terminalbridge mcp-url ``` Windows PowerShell: ```powershell git clone https://github.com/kwj903/ouroboros-workspace-bridge.git cd ouroboros-workspace-bridge uv sync uv run terminalbridge setup uv run terminalbridge start uv run terminalbridge mcp-url ``` During setup, choose `ngrok`, managed `cloudflare`, or generic `external`, the `WORKSPACE_ROOT` ChatGPT may access, and the default help language. Existing shell and runtime settings are respected. Public connection modes: - `ngrok` (default): starts review, MCP, and the user's own ngrok connector. - `cloudflare`: starts review, MCP, and the user's configured named Cloudflare Tunnel from their own account and config. - `external`: starts review and MCP while another user-managed proxy or tunnel remains outside the project lifecycle. - No maintainer token, domain, tunnel ID, or credential is a working product default. - Keep the review UI local-only and run a shared-domain connector on only one computer at a time. Optional browser onboarding: ```bash uv run terminalbridge setup-ui ``` `setup-ui` opens a temporary localhost setup wizard for first-time users. It shows mode-aware ngrok, managed Cloudflare, or generic external guidance, workspace concepts, ChatGPT app connection, and the first success test. It does not replace `uv run terminalbridge setup` and does not start, stop, or restart the normal session. `uv run terminalbridge mcp-url` prints a redacted URL preview for checking configuration without exposing the token. Use `uv run terminalbridge copy-url` when a fixed public endpoint, `MCP_ACCESS_TOKEN`, and a platform clipboard helper are configured and you are ready to paste the real token-protected MCP URL into ChatGPT. Next steps: - [Choose ngrok or your own public domain](docs/en/public-access.md) - [Connect as a ChatGPT custom app](docs/en/chatgpt-app-setup.md) - [Use the pending review UI](docs/en/pending-review-ui.md) First success test: ```text Use this workspace directory: /path/to/your/project Show me a brief overview of this directory's structure and tell me what kind of project it looks like. ``` With the default Normal mode, approve only the expected pending bundle in the local review UI. If Safe Auto or YOLO is intentionally enabled, verify the bundle's `running`/terminal status instead of expecting a manual approval step. Stop the local session: ```bash uv run terminalbridge stop ``` Optional install helpers: These scripts are optional OS-specific setup helpers. They do not replace `uv run terminalbridge setup`; they prepare local conveniences so the normal operator workflow is easier to use. - `./install.sh`: Bash helper for macOS/Linux. - `./install.ps1`: PowerShell helper for Windows. - They install/sync Python dependencies and check or guide platform tools used by the local workflow. - Platform tools include browser opening, clipboard copy helpers, and desktop notifications for pending review events when available. - After running a helper, continue with `uv run terminalbridge setup` or `uv run terminalbridge setup-ui`. ## Update From an existing checkout: ```bash cd ouroboros-workspace-bridge uv run woojae update ``` `woojae update` stops if local uncommitted changes are present. It pulls the current branch with `--ff-only`, runs `uv sync`, restarts the local session, and prints status. Preview the update without changing files: ```bash uv run woojae update --dry-run ``` After updates that change MCP tools, refresh or reconnect the ChatGPT app connector. ## After starting - A local MCP server is running for the configured workspace. - A localhost review UI is available. - A token-protected MCP URL can be added to ChatGPT as a custom app/connector. - Pending and completed bundles are reviewed at `http://127.0.0.1:8790/pending` and the history views. - The default ChatGPT connector exposes a canonical **31-tool** MCP surface; `workspace_info` and smoke/schema checks use the same manifest. ## How it works ```text ChatGPT -> Local MCP bridge -> Durable bundle -> Approval policy Normal: manual review Safe Auto / YOLO: policy-based auto authorization -> Atomic pending -> running claim -> Local runner -> applied / failed / interrupted ``` ## Safety model - ChatGPT does not directly edit files or run commands; it submits proposals to the Bridge runtime. - Start with Normal mode and approve only small, expected bundles. If Safe Auto or YOLO is enabled, treat that mode itself as authorization for eligible pending bundles. - Reject bundles that mix unrelated edits, tests, commits, or surprising files. - Keep the review UI localhost-only. - Treat every public MCP endpoint, whether ngrok or your own domain, as externally reachable and token-protected. ## Platform support - macOS: supported through the shared Python supervisor workflow. - Linux: supported through the shared Python supervisor workflow; desktop clipboard/notification conveniences may vary by distribution. - Windows 10/11: supported through PowerShell and the shared Python supervisor workflow; ngrok or external-tunnel setup, firewall, browser, and clipboard behavior may need local adjustment. CI runs the unit and smoke suites on GitHub-hosted Ubuntu, macOS, and Windows runners. Platform-specific desktop integrations still require local verification on the target machine. Use `uv run terminalbridge ...` as the normal operator command for the complete connection stack on every platform. `uv run woojae ...` remains the lower-level diagnostic/update interface, and `scripts/dev_session.sh` / `scripts/dev_session.ps1` remain compatibility wrappers. ## Documentation English docs: - [Quickstart](docs/en/quickstart.md) - [Public access modes](docs/en/public-access.md) - [Connect as a ChatGPT custom app](docs/en/chatgpt-app-setup.md) - [Use the pending review UI](docs/en/pending-review-ui.md) - [Local session guide](docs/en/local-session.md) - [Recommended local workflow](docs/en/workflow.md) - [Troubleshooting](docs/en/troubleshooting.md) - [ChatGPT agent instructions](docs/en/chatgpt-agent-usage.md) Korean docs: - [빠른 시작](docs/ko/quickstart.md) - [공개 연결 모드](docs/ko/public-access.md) - [ChatGPT 앱으로 연결하기](docs/ko/chatgpt-app-setup.md) - [pending review UI 사용하기](docs/ko/pending-review-ui.md) - [로컬 세션 운영](docs/ko/local-session.md) - [권장 로컬 작업 흐름](docs/ko/workflow.md) - [문제 해결](docs/ko/troubleshooting.md) - [ChatGPT 에이전트 지침](docs/ko/chatgpt-agent-usage.md) Repository hygiene: - [LICENSE](LICENSE) - [SECURITY.md](SECURITY.md) - [CONTRIBUTING.md](CONTRIBUTING.md) ## Runtime data Runtime data is stored outside the repository, usually under `~/.mcp_terminal_bridge/my-terminal-tool`. ```bash uv run woojae paths uv run woojae storage uv run woojae cleanup --dry-run ``` `cleanup` is conservative and defaults to dry-run behavior unless `--apply` is passed. Session secrets, pending bundles, and process pid files are protected. ## License This project is licensed under the **KwakWooJae Non-Commercial License 1.0**. Non-commercial use is permitted. Commercial use requires prior written permission from KwakWooJae. For commercial permission, contact: kwakwoojae@gmail.com This is a source-available project, not an OSI-approved open source project. See [LICENSE](LICENSE). ## Repository layout ```text my-terminal-tool/ ├── assets/ ├── docs/ │ ├── en/ │ ├── ko/ │ └── project/ ├── scripts/ ├── terminal_bridge/ ├── tests/ ├── pyproject.toml ├── README.md ├── README.ko.md ├── server.py └── uv.lock ``` Core implementation files: - `server.py`: MCP registration, public wrapper signatures, annotations, validation, and thin adapters. - `terminal_bridge/public_tools.py`: canonical default 31-tool public MCP manifest and annotation policy helpers. - `terminal_bridge/bundles.py`: canonical filesystem bundle store for atomic JSON persistence, request identity/indexing, generation signaling, claim, transition, and finalization. - `terminal_bridge/bundle_service.py`: focused stage/find/status/list/cancel orchestration over the canonical bundle store. - `terminal_bridge/mcp_tools/`: helper modules for read-only inspection, proposal construction, async wait/status flows, and runtime status views. - `scripts/command_bundle_review_server.py`: local HTTP review server routes, bundle views, approval-mode handling, and long-poll state updates. - `scripts/command_bundle_runner.py`: validated single-workspace-cwd execution, snapshots/backups, rollback, and terminal bundle finalization. - `terminal_bridge/mcp_runtime.py`: shared MCP runtime helpers for audit logging, async-aware tool-call journaling, and runtime directory setup. - `terminal_bridge/operator_cli.py`: `terminalbridge` complete-stack operator CLI; `terminal_bridge/cli.py` keeps lower-level `woojae` diagnostics/update commands, with shared primitives in `terminal_bridge/cli_common.py`. - `terminal_bridge/review_layout.py`: review UI shell, navigation, and shared CSS. - `terminal_bridge/review_intents.py`: signed intent token import parsing helpers for the local review UI. ## Safety notes - Do not commit or paste real tokens, `.env` values, ngrok authtokens, or bearer tokens. - Approve only small, expected bundles. - In the default public workflow, stage-and-wait proposal tools should keep action and command proposals to exactly one action or one command step. - Reject bundles that mix unrelated edits, tests, commits, or surprising files. - Do not include real tokens, private file contents, or workspace secrets in public issues.