3fools-pingpong

3 AI models — Claude + GPT + Gemini — pinging in tmux 3-pane.
One project. One router. One Korean reply.

---

⚠️ Read LEGAL.md first. This project orchestrates 3 first-party CLIs (Claude Code / OpenAI Codex / Gemini CLI) in a way that touches grey areas in each company's Terms of Service. Non-commercial / personal research / learning use only. Each user runs everything on their own machine with their own accounts. The author's mesh gateway, tokens, and accounts are NEVER shared.

---

Table of contents

• What it is
• Why
• Architecture
• Quick start
• Role lock
• Command surface
• Safety model
• Self-host requirements
• Repository layout
• Versioning
• Contributing
• License

---

What it is

3fools-pingpong is a meta-harness that boots 3 different AI CLIs in 3 tmux panes on your local machine and dispatches a single user prompt across them with role-locked authority:

pane	AI	CLI	role	final authority
pane 4 (main)	Claude Opus 4.x	claude	architecture · safety · quality · router	system design
pane 2	GPT-5.x	codex	implementation · code · scripts	implementation code
pane 3	Gemini 3.x	vgemini	exploration · lookup · fact-checking	factual verification

You type one prompt in pane 4 only. The Claude router classifies the work, dispatches English prompts to pane 2 and pane 3, harvests their results from a single append-only JSONL log, then replies to you in Korean.

The harness installs into Claude Code and OpenAI Codex CLI equally — both entrypoints invoke the same agents · skills · tmux bootstrap.

Why

Single-model collaboration has blind spots. Three models with locked roles surface them.

• Architecture decisions that Claude is well-known to be reflective about
• Implementation throughput that Codex pushes hard on
• Factual lookups & prior-art search that Gemini's grounding is good at

3fools-pingpong doesn't ask "which model is better." It assumes none is universally best and gives each one the seat where it earns the final say.

Architecture

_{Live tmux session — Claude routes (top), Codex implements (bottom-left), Gemini verifies (bottom-right). One prompt in, three minds working.}

            ┌──────────────┐
   USER ──▶ │  pane 4      │ ──── classify ───┐
            │  CLAUDE      │                  │
            │  ROUTER      │ ◀──── synthesize ┘
            └──────┬───────┘
                   │ dispatch (English prompt)
            ┌──────┴──────┐
            ▼             ▼
      ┌─────────┐   ┌─────────┐
      │ pane 2  │   │ pane 3  │
      │  GPT    │   │ GEMINI  │
      │  IMPL   │   │ EXPLORE │
      └────┬────┘   └────┬────┘
           │             │
           └──────┬──────┘
                  ▼
      ┌──────────────────────────────────────┐
      │ <project>/.3fools/                   │
      │   context.jsonl    (all utterances)  │
      │   decisions.jsonl  (role authority)  │
      │   handoffs.jsonl   (pane dispatch)   │
      │   sessions/<date>-<slug>.md          │
      └──────────────────────────────────────┘
                  ▲
                  │ OAuth (your own tokens, in your own mesh)
                  │
      ┌──────────────────────────────────────┐
      │  YOUR self-hosted OAuth gateway      │
      │  http://127.0.0.1:10531  or          │
      │  http://<you>.<your-tailnet>.ts.net  │
      │  /openai-oauth                       │
      │  /anthropic-oauth                    │
      │  /google-oauth                       │
      └──────────────────────────────────────┘

Full specification: SPEC.md (19 decisions D1–D19, JSONL contracts, OAuth mesh spec, dogfooding plan).

Quick start

Each user runs this in their own environment. You bring your own 3 accounts (Anthropic / OpenAI / Google) and your own self-hosted OAuth mesh gateway.

1. Install dependencies

brew install tmux jq                         # macOS
# Linux: use your package manager

Then install each AI CLI:

• claude — https://claude.com/claude-code
• codex — https://platform.openai.com/codex
• vgemini — see docs/vgemini-setup.md

2. Self-host your OAuth mesh gateway

Read docs/oauth-setup.md carefully. Run the gateway on 127.0.0.1 or inside your own Tailscale tailnet only. The author's gateway is NOT shared.

3. Install 3fools-pingpong

git clone https://github.com/VoidLight00/3fools-pingpong.git
cd 3fools-pingpong
./install.sh

install.sh will:

• read & require your LEGAL.md acknowledgment
• check binary deps
• ask for your MESH_BASE_URL (refuses the author's IP automatically)
• write ~/.3fools-mesh/config.env (chmod 0600)
• prepare empty ~/.3fools-mesh/secrets.env (chmod 0600)
• symlink (or copy) agents · skills · command into ~/.claude/
• run 3fools doctor for a final health check

4. Authorize OAuth (one time per provider)

In Claude Code or Codex CLI:

/3fools setup openai
/3fools setup anthropic
/3fools setup google

Each opens your browser to your own gateway's /start endpoint. Tokens land in ~/.3fools-mesh/secrets.env (chmod 0600). Never logged, never echoed.

5. Start a project

cd <your-project>

Inside Claude Code:

/3fools init --project=<slug>

This bootstraps a tmux session, launches the 3 CLIs in the right panes, and briefs each pane in English with its locked role. You then type tasks in pane 4 in Korean:

/3fools task "OAuth gateway 코드 살펴보고 anthropic 엔드포인트 추가해줘"

The router (pane 4) classifies → dispatches → harvests → replies. The full pingpong is visible in tmux.

6. Wrap up

/3fools kill --archive

Generates .3fools/sessions/<date>-<slug>.md — a session digest with redacted decisions, handoffs, and a timeline.

Role lock

The pane → AI → role mapping is hardcoded by design (SPEC D6). Roles do not float. Each role has final authority in its domain (SPEC D14):

domain	owner	what it decides
architecture · safety · quality	pane 4 / Claude	system design, security gates, code review, conflict tie-break
implementation	pane 2 / GPT	library choice, function structure, naming, test code
verification	pane 3 / Gemini	factual claims, library versions, prior-art lookup, source citations

If a role tries to write outside its domain, the JSONL store rejects the entry. This is enforced, not a convention.

Command surface

/3fools <mode> [args]

mode	one-liner
init	doctor PASS → tmux 3-pane bootstrap → ready
task	dispatch a piece of work through the router
status	ping each fool + tail recent handoffs
resume	recover a dropped tmux session
log	tail context · decisions · handoffs JSONL
kill	tear down tmux (--archive writes a session digest)
doctor	environment check (5 boxes)
retro	session retrospective with user input
replay	replay a past handoff sequence for debugging
fork	branch the current .3fools/ into a new slug
handoff	export a redacted session zip for another developer
setup	one-time OAuth provider setup (openai · anthropic · google)

Full lifecycle spec: SPEC.md §4.

Safety model

Four conditions trigger a P0 abort (immediate teardown + CRITICAL warning in RUN_MANIFEST.json):

code	condition
S1	OAuth token plaintext leak detected (in log · stdout · diff · archive)
S5	Any single fool unreachable
S6	tmux not installed
S7	Model major-version mismatch (e.g. Opus 3.x where Opus 4.x is required)

Redaction patterns (auto-masked everywhere): Bearer …, sk-…, eyJ… (JWT), gho_…, glpat-…, xoxb-…, ya29.…, sk-ant-…. Add more via PR.

Other invariants (SPEC §8):

• S3 Same-file concurrent write forbidden (file locks under .3fools/locks/)
• S4 Role↔domain mismatch in decisions.jsonl is rejected
• S8 No external push · SNS · deploy automation (always requires explicit user approval)
• S9 Dry-run required before writing to ~/.claude/
• S10 Redaction patterns apply at every output stage

See SECURITY.md for vulnerability reporting.

Self-host requirements

requirement	minimum	notes
tmux	3.0+	mandatory by D3 — no fallback
claude	Claude Opus 4.x family	Claude Code CLI
codex	GPT-5.x family	OpenAI Codex CLI
vgemini	Gemini 3.x family	see docs/vgemini-setup.md
OAuth mesh gateway	self-hosted only	see docs/oauth-setup.md
3 accounts	all in your own name	one user, one account per provider, no pooling
disk	~10MB	~/.3fools-mesh/ + per-project .3fools/

The author's hosted gateway is not available to anyone. install.sh actively rejects the author's known IP.

Repository layout

3fools-pingpong/
├── SPEC.md                      v1 specification — single source of truth
├── README.md                    this file
├── LEGAL.md                     read this before use
├── LICENSE                      MIT
├── CHANGELOG.md                 Keep a Changelog format, semver
├── CONTRIBUTING.md              contributor guide + RFC process
├── SECURITY.md                  vulnerability reporting
├── install.sh                   one-way self-setup bootstrap
│
├── .claude-plugin/
│   └── plugin.json              Claude Code plugin manifest
│
├── codex-extension/
│   └── extension.json           OpenAI Codex CLI extension manifest
│
├── scripts/
│   └── tmux-bootstrap.sh        deterministic 3-pane spawn
│
├── agents/                      7 agent definitions (mirror of ~/.claude/agents/)
│   ├── 3fools-conductor.md
│   ├── 3fools-router-claude.md
│   ├── 3fools-impl-gpt.md
│   ├── 3fools-explorer-gemini.md
│   ├── 3fools-doctor.md
│   ├── 3fools-archivist.md
│   └── 3fools-installer.md
│
├── skills/                      5 skill modules (mirror of ~/.claude/skills/)
│   ├── 3fools-pipeline/
│   ├── 3fools-tmux-bootstrap/
│   ├── 3fools-oauth-mesh/
│   ├── 3fools-context-store/
│   └── 3fools-dogfood-runner/
│
├── commands/
│   └── 3fools.md                /3fools slash command
│
├── docs/
│   ├── oauth-setup.md           self-host your gateway
│   ├── vgemini-setup.md         set up vgemini wrapper
│   └── assets/
│       └── banner.png           hero image
│
└── .gitignore                   secrets / .3fools/ workspace / OS noise

Versioning

Semantic Versioning 2.0.0 + Keep a Changelog. See CHANGELOG.md.

bump	meaning	example
MAJOR	breaking change to any of the 19 decisions in SPEC.md	D6 role mapping ceases to be hardcoded → v2.0.0
MINOR	new command mode, new agent, new skill (no breaking change)	add a 13th mode → v0.2.0
PATCH	bug fix, doc tweak, new redaction pattern	new secret regex → v0.1.1

Pre-release tags:

• -alpha — spec frozen, runtime validation pending (current)
• -beta — dogfood T1–T9 (SPEC §10) pass
• -rc — at least one external user installs cleanly
• (no suffix) — production-ready, 3+ external dogfood reports

Contributing

PRs welcome under the contract in CONTRIBUTING.md. Highlights:

1. Read LEGAL.md and agree before submitting
2. SPEC.md changes require an RFC issue first
3. New secret patterns → also update redaction regex
4. New agents → always model: "opus"
5. Description fields stay pushy + include resume / re-run trigger words

Security issues: file a GitHub Security Advisory (private), not a public issue.

License

MIT.

License does not waive the LEGAL.md terms of use. The MIT license governs copying and modifying the code in this repository; it does not grant any permission with respect to the three first-party CLIs or their providers' terms of service. Read both before use.

---

_{Built with three minds at one table. Documented at one source of truth.}