{"id":50751999,"url":"https://github.com/leandrojo/forum","last_synced_at":"2026-06-11T02:01:40.703Z","repository":{"id":361879174,"uuid":"1254696135","full_name":"leandrojo/forum","owner":"leandrojo","description":"Lean, high-quality tool for structured multi-model debates. Radical equality between participants. Deliberately not another orchestration framework.","archived":false,"fork":false,"pushed_at":"2026-06-01T16:13:13.000Z","size":25,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-01T17:25:25.333Z","etag":null,"topics":["agents","ai","debate","llm","llm-evaluation","multi-model","structured-reasoning"],"latest_commit_sha":null,"homepage":"https://github.com/leandrojo/forum","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/leandrojo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-30T22:30:14.000Z","updated_at":"2026-06-01T16:14:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/leandrojo/forum","commit_stats":null,"previous_names":["leandrojo/forum"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/leandrojo/forum","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leandrojo%2Fforum","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leandrojo%2Fforum/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leandrojo%2Fforum/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leandrojo%2Fforum/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leandrojo","download_url":"https://codeload.github.com/leandrojo/forum/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leandrojo%2Fforum/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34178819,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","ai","debate","llm","llm-evaluation","multi-model","structured-reasoning"],"created_at":"2026-06-11T02:01:28.961Z","updated_at":"2026-06-11T02:01:40.697Z","avatar_url":"https://github.com/leandrojo.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/forum-hero-forvm.jpg\" alt=\"Forum — the public square of debate\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n# Forum\n\n[![CI](https://github.com/leandrojo/forum/actions/workflows/ci.yml/badge.svg)](https://github.com/leandrojo/forum/actions/workflows/ci.yml)\n[![Release](https://img.shields.io/github/v/release/leandrojo/forum?sort=semver)](https://github.com/leandrojo/forum/releases)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n**Run equal-footing, auditable debates between local AI CLIs — and get a full transcript of every round.**\n\nForum points your already-authenticated CLIs (`grok`, `codex`, `gemini`, `claude`)\nat the same question, runs them as peers through one strict execution contract,\nand writes a structured, replayable transcript. No API keys. No model favoritism.\nThe transcript is the product.\n\n## Show me\n\n**1. Run a debate:**\n\n```bash\n./examples/forum_debate.sh --rounds 1 \\\n  \"Should a small CLI prioritize zero runtime dependencies over developer convenience?\" \\\n  codex grok claude\n```\n\n\u003e Participant names are just the provider (`grok`, `codex`, `gemini`, `claude`) —\n\u003e each adapter picks a sensible default model, so you don't think about tiers.\n\n**2. Watch it run** (each participant is a real, local CLI):\n\n```\nRound 1:\n  P1 (codex)... ok\n  P2 (grok)... ok\n  P3 (claude)... ok\nTranscript: transcripts/debate-20260601T182039Z-48889/transcript.md\n```\n\n**3. Read the artifact** — a single Markdown transcript with each peer's answer\nunder a neutral label. Excerpt:\n\n```markdown\n### P1 (codex)\nYes, for a small, single-purpose open-source CLI, zero or near-zero runtime\ndependencies should be the default bias... unless a dependency delivers\nsubstantial user-facing value that would be expensive or error-prone to\nreimplement correctly.\n\n### P3 (claude)\nYes, zero runtime dependencies should be the default... a tool that fails to\ninstall or breaks because a transitive dependency released a bad patch has\nfailed its users before doing any work. The one legitimate exception is when a\ndependency provides correctness guarantees the tool genuinely cannot replicate.\n```\n\n→ Full transcript of this run: [`docs/examples/sample-debate.md`](docs/examples/sample-debate.md)\n\n## Why this isn't generic multi-agent tooling\n\nForum's distinctiveness is a *refusal*, enforced in code:\n\n- **One contract for everyone.** Every participant goes through `call_participant`\n  in [`providers/base.sh`](providers/base.sh): stdout is the clean model answer,\n  stderr is errors, exit codes are respected, timeouts are uniform. A model's\n  adapter is the *only* place a difference may exist — there is no `if model == X`\n  anywhere in the orchestration.\n- **No keys, no broker.** It shells out to CLIs you already authenticated. No\n  OpenRouter, no API-key plumbing.\n- **The transcript is the source of truth**, not a side effect. Prompts, each\n  participant's raw response, errors, and metadata are written per round.\n\n## When to use Forum\n\n- You want several models to genuinely deliberate on a decision and you want the\n  full record to audit later.\n- You value a single, inspectable shell engine over a hosted black box.\n\n## When *not* to use it\n\n- You need a chat UI, a hosted service, or a general agent framework. Forum is\n  none of those, on purpose — see the [roadmap](docs/ROADMAP.md).\n\n## Install\n\nForum is a self-contained **agent skill** — the debate engine ships inside the\nskill folder, so it installs into any supported agent (Claude Code, Codex,\nCursor, Gemini, Copilot, …) with one command via the open\n[skills](https://github.com/vercel-labs/skills) CLI:\n\n```bash\nnpx skills add leandrojo/forum              # into the current project (.\u003cagent\u003e/skills/)\nnpx skills add leandrojo/forum -g           # global (~/.\u003cagent\u003e/skills/)\nnpx skills add leandrojo/forum -a claude-code -g   # target a specific agent\n```\n\nThen invoke it in your agent:\n\n```\n/forum \"Should we use a queue or direct processing here?\" grok codex gemini claude\n```\n\n\u003e **What it runs.** Forum shells out to the provider CLIs you've already\n\u003e authenticated — it manages no API keys and transmits nothing itself. It is a\n\u003e skill that executes commands, so review what it does before installing.\n\u003e See [SECURITY.md](SECURITY.md).\n\n**From source** (development, or to run the engine directly):\n\n```bash\ngit clone https://github.com/leandrojo/forum\ncd forum\n./examples/forum_debate.sh --rounds 2 \"Your question here\" grok codex gemini\n```\n\n## Quick start\n\nYou need at least one of these CLIs authenticated on your machine:\n\n| Provider | Default command | Override variable | Last tested |\n|----------|-----------------|-------------------|-------------|\n| Grok     | `grok`          | `GROK_BIN`        | 2026-06-01  |\n| Codex    | `codex`         | `CODEX_BIN`       | 2026-06-01  |\n| Gemini   | `gemini`        | `GEMINI_BIN`      | 2026-06-01  |\n| Claude   | `claude` (`-p`) | `CLAUDE_BIN`      | 2026-06-01  |\n\n\u003e Forum depends on external CLIs that evolve. The \"last tested\" column is when\n\u003e each adapter was last verified against a live debate.\n\n```bash\n# Two-round debate across three peers\n./examples/forum_debate.sh --rounds 2 \"Evaluate this architecture decision\" grok codex gemini\n\n# Single round\n./examples/forum_debate.sh --rounds 1 \"Queues or direct processing for welcome emails?\" codex gemini\n```\n\nThe script prints the path to a `transcript.md` with the full debate.\n\nProvider model selection and sandboxing are controlled via environment\nvariables — see the individual files under [`providers/`](providers/).\n\n## Project structure\n\n```\nforum/\n├── providers/                  # Model adapters — strictly equal treatment\n│   ├── base.sh                 # The execution contract + dispatcher\n│   ├── grok.sh  codex.sh  gemini.sh  claude.sh\n├── utils/common.sh             # Shared timeout / normalization / error handling\n├── core/debate_orchestrator.sh # Multi-round orchestration + neutral context\n├── examples/forum_debate.sh    # Recommended entrypoint\n├── tests/                      # Contract + smoke tests (run with stubs, no auth)\n└── docs/\n    ├── DESIGN.md               # Architecture + naming rationale\n    ├── ROADMAP.md              # Now / Next / Later / Not planned\n    ├── examples/               # Curated sample transcripts\n    └── archive/                # Historical planning notes\n```\n\n## Adding a provider\n\n1. Create `providers/yourmodel.sh` implementing `call_yourmodel()`.\n2. Source it in `base.sh` and add the dispatch case.\n3. Follow the exact same contract as the others (clean stdout, useful stderr,\n   respected exit codes, neutral preamble, `run_with_timeout`).\n\nThe contract is specified in [`providers/base.sh`](providers/base.sh) and the\nexisting adapters are short — read one before writing yours. See\n[CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Development\n\n```bash\n./tests/provider_contract_test.sh   # provider contract, via stubs\n./tests/orchestrator_smoke_test.sh  # multi-round orchestration, via stubs\n```\n\nNeither test needs an authenticated CLI.\n\n## Why \"Forum\"?\n\nThe Roman Forum was the physical and symbolic center of public debate in the\nRoman Republic — one of history's earliest structured attempts at collective\ndeliberation. We borrow that spirit: serious, equal, transparent, and focused on\nbetter collective reasoning rather than spectacle. The full naming rationale is\nin [docs/DESIGN.md](docs/DESIGN.md).\n\n## Contributing\n\nForum welcomes contributions **on narrow terms** — new provider adapters, debate\nprotocols, transcript/auditability work, portability, and tests. It will decline\nscope creep by charter. Start with [CONTRIBUTING.md](CONTRIBUTING.md) and the\n[Code of Conduct](CODE_OF_CONDUCT.md).\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n---\n\nThis project is intentionally small. If you're looking for a massive multi-agent\nplatform, this is not it. If you want a sharp, principled tool for high-quality\nmulti-model debate — welcome.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleandrojo%2Fforum","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleandrojo%2Fforum","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleandrojo%2Fforum/lists"}