ccc-mcp

A team of AI roles that works on your computer, and shows its work.

Let ChatGPT Chat write, test, and review code (or plan a trip, draft a proposal, check the facts) as a chat room of specialists.

ccc-mcp connects ChatGPT Chat to a local coding workspace through MCP, so it can work on an authorized repository. Its core idea: don't take an AI's word that the code works — keep local evidence. Tests are run by the host, not reported by the agent; every diff, test result and review is saved and resumable, which a chat window can't do on its own. As a bonus, it runs on your existing ChatGPT plan, with no separately metered model API to set up. ChatGPT-only is the primary workflow. Codex and Claude Code are optional providers for teams that want to split roles across tools.

繁體中文 README · English documentation

Highlights

Evidence, not self-reports

The host runs the tests, not the agent. Every diff, test result and review is saved next to the project, so a task can be inspected, paused or resumed from another chat. An agent saying “tests pass” never counts.

A chat room of AI specialists

Work is a conversation. 19 roles (analyst, designer, developer, code reviewer, security reviewer, researcher, writer, fact checker and more) each have a pixel avatar and a name you choose, and report in their own voice as the task moves from one to the next. Pause, stop, or leave a correction at any point. No more guessing who is working now or what the last one did.

Workflows you compose, with gates that push back

7 built-in workflows (Classic, Standard, Full, and four everyday teams) plus any you build and save yourself. ChatGPT, ccc-mcp, or you can choose the workflow per task. Review gates send work back to the step that made it: the adversarial reviewer has Normal / Strict / Extreme strictness, every blocking claim must cite evidence, and the number of rounds is capped (1–5). When a gate runs out of rounds, you decide instead of the agents looping forever.

Not only for code

Four ready-made everyday teams put the same machinery to work on a trip plan, a business proposal, an article or a big decision: assistant → researcher → analyst → planner → fact checker, and so on. They run on ChatGPT, so they can browse. A specification writer turns a discussion into a spec an AI can implement from.

Game-style ability charts

Every role scores 0–5 on six abilities: research, reasoning, planning, creation, verification, risk sense. Each workflow shows the combined team chart and team power, names the abilities nobody on the team is good at, and the chart grows step by step while a task runs. Pick a team by what it is good at, not by guessing.

Handovers without the wait

When ChatGPT plays an everyday-team step, the next step starts as soon as it hands in its report: no extra “PM round” between roles. Tasks stay resumable, and everything runs on your existing ChatGPT plan.

A local control center that feels yours

ccc-mcp ui gives you projects (with custom icons: a pixel character, an emoji or a letter, in your color), groups, settings, Context, Skills and MCP tools in one place. Light and dark themes, English and Traditional Chinese, and a layout that works on a phone.

Watch the demo

1080p · 60 fps · with audio · 63 seconds.

https://github.com/user-attachments/assets/eb7512b3-7f67-4a2e-aa7a-9e4b06a9a7d2

The original recording is on Google Drive. The separate SWE-bench evidence records the official harness results.

Want to try it yourself? The quick start below takes you from ccc-mcp ui to a ChatGPT conversation connected to an authorized local project.

Start with the UI

Install ccc-mcp, then open its local control center:

pip install ccc-mcp
ccc-mcp ui

Requires Git and Python 3.11+. In the UI:

1. Projects: create a project or add an existing folder, then enable write access for the project.
2. Connect: follow Connect ChatGPT to create an OpenAI Platform Tunnel. Enter its Tunnel ID and runtime API key in the console.
3. Settings: select the chatgpt-only profile. The Test command can be left blank: ccc-mcp installs declared Python dependencies and chooses tests from changed test files when possible. Set a command when you need a specific scope.
4. ChatGPT: select the ccc-mcp connection and ask it to make a change. Inspect Tasks and Context in the UI to see the actual edits, test results, and next step.

The UI runs on local 127.0.0.1 and stops with Ctrl+C. See every console page.

About tokens and keys: This workflow uses your existing ChatGPT plan instead of an OpenAI model API key and its per-token API billing. ChatGPT plan limits still apply. ccc-mcp does not claim to use fewer tokens than a single agent: the SA → SD/RD → REVIEW workflow adds rounds in exchange for verification, and a per-task token comparison is still being measured. The Tunnel connection uses its own runtime API key; connection setup explains that key.

What makes ccc-mcp useful

How execution evaluation works

The evaluation engine (opt-in, off by default) scores a completed SA/SD/RD/REVIEW execution from evidence that is already saved — the host-run test result, the execution's diff, and ruff static analysis — with no additional LLM call and no extra token cost. It never asks an Agent whether its own work passed, and never treats one Agent's agreement with another as proof of correctness.

Two numbers are reported separately, on purpose:

• quality_score is the weighted average of only the sub-scores that actually have evidence behind them, using the role's configured weights (test/requirement/code-quality/security/review — editable per role, with one-click presets, in the web console's settings page).
• evidence_coverage is the share of that role's weight budget those sub-scores actually cover. A quality_score of 100 with 70% coverage means "everything we could check looked perfect, but we could only check 70% of what this role is normally judged on" — not "100% confidence."

A small set of hard rules decides task_status separately from the weighted score: a failing acceptance test, or a test suite that never ran, can never read as PASSED, no matter how high the weighted average is. A Beta-Bernoulli reputation tracker (ccc-mcp reputation) keeps per-agent/model/role/task-type reliability across every project, with wide, explicit uncertainty while sample sizes are small — never a confident number from too little data.

See Technical reference for the exact formulas and data model.

Proof: three selected SWE-bench Verified cases

Using ChatGPT-only, ccc-mcp resolved three selected SWE-bench Verified Astropy instances after iterative repair. Each has a local run of the official evaluation harness reporting resolved: true:

Read the evidence and methodology, including run IDs and ChatGPT conversations. These are 3 selected cases, not a full-benchmark score or an official leaderboard submission.

ChatGPT first; other agents are optional

With the chatgpt-only profile selected, ChatGPT handles the project manager and every role of the selected workflow. The workflow records each handoff so the next chat can pick up the saved state.

ChatGPT Chat → local project → tests, diff, review
       ↑                            │
       └──── saved Context and next step ────┘

If you want a multi-agent workflow, assign supported roles to Codex or Claude Code through their native CLIs. Configure providers, effort, quota fallback, test command, and report language in Settings. See the workflow guide.

Web console

ccc-mcp ui

Starts a local web console in the same process that already serves the CLI and MCP server — no separate frontend to clone, build, or run, and no Node.js required even if you build from source (the UI ships as plain HTML/CSS/JS bundled into the ccc-mcp wheel). It binds 127.0.0.1 only, prints its URL, and opens your browser; pass --port to pin a port (ccc-mcp reports clearly if that port is taken) or leave it out to pick a free one automatically, and --no-browser to skip the auto-open. Press Ctrl+C to stop it. It reads the same --home database the CLI and MCP server use, so projects and tasks are always in sync across all three.

The console's main pages:

Claude quota sync is opt-in: open Command center → Usage and remaining allowance → Enable Claude quota sync. It adds a small wrapper to your Claude Code user statusLine setting and preserves and runs an existing status line. The usage snapshot in the local ccc-mcp home contains only reported percentages, reset times, and observation time; separate installation metadata retains the previous status-line setting for restoration. Open an interactive Claude Code session and receive one response to populate the values; Claude Code supplies these fields only after an API response. The dashboard checks the local snapshot every five minutes, labels older observations, and removes expired windows. Disable Claude quota sync restores the previous setting and deletes the local snapshot. This does not call Claude's model or read its login credentials. See Anthropic's status-line field documentation.
| Skills & MCP | View shared Skills; discover, install, and manage local stdio MCP servers and their tools for one project. |
| Documentation | Read the bundled English and Traditional Chinese guides inside the console. |

In Skills & MCP, inspect tools, choose which ones this project may use, invoke enabled tools with JSON arguments, and view recent MCP calls. Globally installed MCP servers also appear there, but still require the CLI to remove. The sidebar's interface language is separate from each project's report language. Connect can remember a runtime API key on this device (~/.ccc-mcp/tunnel/credentials.json, readable only by your OS account); stored keys are never returned to the browser. Enabling write, clearing history, and deleting require typed confirmation. See reliability and security for details.

On All projects, create named groups, move project cards with the dropdown or drag-and-drop, and reorder groups. This only changes local console organization (<home>/ui/project_groups.json), not project paths or settings. Connect can save multiple named profiles, including different keys for the same Tunnel ID; select a saved profile and click Connect to use it. One Tunnel connection runs at a time.

CLI: automation and advanced use

If you prefer a terminal or write scripts, the CLI operates on the same project data. ccc-mcp setup all and signing in to Codex or Claude Code are only needed if you plan to use those optional native roles. For example, to create a project entirely from the CLI:

ccc-mcp project create hello-demo --write
ccc-mcp --project hello-demo task status
ccc-mcp --project hello-demo task usage
ccc-mcp --project hello-demo context show

--write asks for local confirmation while creating the project, authorizing ccc-mcp to write there and run its configured test command. For an existing folder, use ccc-mcp project add <folder> --write. If you only use ChatGPT, skip setup all and select chatgpt-only in the project's Settings, or run ccc-mcp --project hello-demo config profile chatgpt-only.

For native roles, task usage shows whether the CLI was actually invoked. ChatGPT roles are interactive: task usage marks them "interactive": true with invocation.source: "chatgpt_web", so cli_invoked: false is expected. See the CLI reference for all commands.

Documentation

Read the numbered documents in order for a full setup. The two language trees use the same filenames and sequence.

• Traditional Chinese README
• English documentation index

Important boundary

Continuous write authorization — granted via project authorize, project add --write/project create --write, or the web console's "Enable write" — permits ccc-mcp to modify that project and run its configured test command. Dependency installation can execute package scripts, so review dependency changes as part of the diff. Codex runs in its configured sandbox. Claude Code has a restricted tool policy, but does not yet have an equivalent OS-enforced sandbox; use a least-privileged OS account for it.

To remove a project from project list while keeping its folder, use ccc-mcp project remove <id> (or the web console's Remove, keep folder action). This clears ccc-mcp records by default; registering the same ID again starts with empty records. Add --delete-files to delete the project folder too, or --keep-records to retain an archive of the old records. The web console offers the same Keep records checkbox in either removal flow. The CLI and web console require typed confirmation, and running executions must finish or be cancelled first. project delete is different: it permanently retires the ID and preserves historical records and files. See reliability and security for the full guarantee.

Development

python3.11 -m pytest -q

The repository requires Python 3.11 or newer. Real-agent tests are opt-in because they need locally installed, authenticated CLIs; see Chinese or English.

Releasing

You choose when to run checks and when to publish. Nothing runs automatically after a push or pull request. Start CI manually for a short lint and focused test run on Linux and Windows; it does not build release artifacts, change the version, or publish. When ready, start Release manually from main and enter the version in the GitHub form (for example 0.3.0, without v). Release runs the complete Python and platform test matrix, builds and installs the wheel, verifies the wheel and sdist, and tags the matching versioned source commit before publishing to GitHub Releases and PyPI. It does not update main's version file.