Project Brain Bridge

Project Brain Bridge / 项目大脑桥接

Project Brain Bridge is a reusable Codex skill for connecting a local project to ChatGPT as a review and planning brain.

它解决的问题很明确：让 ChatGPT 读取项目状态、提出阶段计划，让 Codex 在本地执行、回写证据，再让 ChatGPT 复审。它不是某个具体项目的脚本，也不绑定任何私人路径。

What It Provides

• A reusable .ai-bridge project state structure.
• A read-only MCP bridge for project status review.
• A narrow write-stage MCP bridge for writing current-plan.md.
• Prompt templates for read-only diagnosis, stage planning, and review.
• Local setup and doctor scripts.
• Security boundaries that keep secrets, tokens, raw private data, and unrelated projects out of scope.

When To Use It

Use this skill when you want:

• ChatGPT to act as a skeptical project brain.
• Codex to act as the local executor.
• A repeatable loop: state -> plan -> execution -> status/log/diff -> review.
• A bridge pattern that can be reused across different local projects.

Do not use it to give ChatGPT unrestricted filesystem write access. The write bridge is intentionally narrow.

Install As A Codex Skill

Clone this repository directly into your Codex skills folder:

mkdir -p ~/.codex/skills
git clone https://github.com/YOUR_ACCOUNT/project-brain-bridge.git ~/.codex/skills/project-brain-bridge

Then invoke it in Codex:

$project-brain-bridge

If you are using the repository locally before publishing:

cp -R /path/to/project-brain-bridge ~/.codex/skills/project-brain-bridge

Quick Start

Initialize bridge files inside a target project:

python3 ~/.codex/skills/project-brain-bridge/scripts/init_ai_bridge.py /path/to/your/project

Start or adapt the read-only MCP server from:

assets/server-template/readonly_bridge_server.js

Start or adapt the write-stage MCP server from:

assets/server-template/write_stage_bridge_server.js

Run the doctor:

python3 ~/.codex/skills/project-brain-bridge/scripts/doctor.py \
  --project-root /path/to/your/project \
  --readonly-url http://127.0.0.1:18891/mcp \
  --write-url http://127.0.0.1:18893/handoff-mcp-v2 \
  --write-test

Recommended Workflow

1. Codex initializes .ai-bridge.
2. ChatGPT uses the read-only connector to inspect state and evidence.
3. ChatGPT writes a bounded stage plan through the write connector.
4. Codex reads current-plan.md and executes locally.
5. Codex writes status, log, and diff evidence.
6. ChatGPT reviews the result before the next stage.

Security Model

The default design separates reading and writing:

• Read-only connector: project state inspection only.
• Write-stage connector: writes only .ai-bridge/current-plan.md.
• No secret reading by default.
• No direct source-code modification by ChatGPT.
• No broad filesystem write tool.

Before using this with a real project, review:

• references/architecture.md
• references/deployment.md
• references/mode-workflow.md
• references/prompts.md

Repository Structure

SKILL.md
agents/openai.yaml
assets/
  launchagent-template/
  server-template/
  starter-ai-bridge/
references/
scripts/

License

MIT. See LICENSE.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: 17557295964-ops
• Source: 17557295964-ops/project-brain-bridge
• License: MIT

Install and usage instructions live in the source repository linked above.