<div align="center">
[中文](./README.zh-CN.md) | **English** | [日本語](./README.ja.md)
<br/>
<h1>Agora</h1>
<p><strong>Agents debate. Humans decide. Execution stays governed.</strong></p>
<p>An orchestration and governance layer for agent societies.<br/>
Agora turns free-form multi-agent discussion into staged, auditable delivery.</p>
[](https://github.com/FairladyZ625/Agora/stargazers)
[](https://github.com/FairladyZ625/Agora/network)
[](https://github.com/FairladyZ625/Agora/issues)
[](LICENSE)
[](https://nodejs.org)
[](https://www.typescriptlang.org/)
</div>
---
## The Problem
Putting many agents into one channel does produce better ideas, but it also produces failure modes:
- Discussion noise drowns the task.
- Coordinators get context-polluted.
- Human approval becomes informal and easy to skip.
- Execution starts before decisions are actually settled.
- Chat logs do not equal delivery.
The deeper problem is not "how to connect another bot". It is:
**How do you build a social structure where the right participants see the right information at the right time?**
Agora answers that with explicit orchestration semantics instead of prompt folklore.
---
## What Agora Is
Agora is:
- an orchestration core
- a governance layer
- a task arena with staged participation
- a human-gated decision system
- a provider-neutral execution control plane
Agora is **not**:
- just another IM bot
- just a coding-agent launcher
- just a Claude/Codex/Gemini wrapper
- a runtime that owns the low-level session substrate
The low-level coding runtime is now treated as commodity infrastructure. Agora keeps the orchestration truth.
---
## Core Model
```text
Citizens deliberate -> Archon decides -> Executors deliver
```
| Concept | Role |
| --- | --- |
| **Agora** | The task arena: isolated context, workflow, participants, notifications |
| **Citizens** | Discussion participants: agents that can debate, critique, and refine proposals |
| **Archon** | Human authority at gates: approves, rejects, pauses, or redirects |
| **Craftsman** | A governed execution role, not a self-owned runtime framework |
| **Gate** | A stage transition checkpoint with explicit policy |
| **Decree** | A curated brief or accepted decision that execution is allowed to act on |
The key idea is simple:
> For executors, much discussion is noise.
Executors do not always need the full debate log. Often they need a curated brief, accepted constraints, and permission to act.
That is why Agora distinguishes:
- `execution-only` participants
- `dialogue-capable` participants
Both can exist in the same task system, but they are governed differently.
---
## How It Works
1. Citizens discuss in an isolated task context.
2. Archon reviews the current conclusion at a gate.
3. Agora decides whether execution may start, who may join, and what brief they receive.
4. Execution runs through a provider-neutral substrate.
5. Results flow back into task state, logs, notifications, and archive.
Discussion stays flexible. Delivery stays controlled.
---
## Execution Model
Agora no longer treats its old tmux-based Craftsman path as the primary execution model.
Current position:
- `ACPX` is the default execution substrate.
- `tmux` remains available only as a legacy fallback/debug adapter.
- `CraftsmanAdapter` remains a Core-facing abstraction.
- `Craftsman` remains a business role in orchestration.
- The old tmux public shell has been removed.
This means Agora focuses on:
- when execution starts
- who gets to execute
- whether an executor joins the discussion
- what context the executor receives
- how completion flows back into orchestration state
It does **not** need to be the project that owns every low-level Claude/Codex session primitive itself.
---
## Why Not Just Put Claude In The Channel?
You can. Agora does not fight that.
If a user wants to connect Claude, Codex, or another agent host directly into Discord/OpenClaw, that is fine. Agora still has a job:
- decide when that participant joins
- decide when they stay hidden
- decide whether they receive the whole discussion or only a brief
- decide when human review is mandatory
- decide how output changes task state
Direct IM presence solves transport. It does not solve governance.
---
## Architecture
```text
IM / Entry Adapters
Discord · Feishu · Slack · Dashboard · CLI · REST
|
v
Agora Core / Orchestrator
Task · Context · Participant · Gate · Approval
Scheduler · Notification · Archive · Recovery
|
v
Runtime / Execution Adapters
Hosted runtimes: OpenClaw · future hosts
Execution substrates: ACPX (default) · tmux (legacy fallback)
```
Core rule:
- `packages/core` owns orchestration semantics.
- IM, runtime, and execution systems are adapters.
- Provider-specific details must not become the long-term Core model.
- Current runtime posture is single-core, dual-adapter: ACPX is the default path, while tmux stays as a legacy adapter.
---
## Quickstart
### Prerequisites
- Node.js 22+
- npm 10+
- `acpx`
Optional:
- OpenClaw, if you want IM-hosted agent participation
- Discord, if you want the live thread experience
- Docker plus an embedding API, if you want `project brain` hybrid retrieval instead of raw lexical search
### Install
```bash
git clone https://github.com/FairladyZ625/Agora.git
cd Agora
./scripts/bootstrap-local.sh
```
### Initialize And Start
```bash
./agora init
./agora start
```
If OpenClaw is detected, `./agora init` can optionally help wire the local Agora plugin into `openclaw.json`.
The stable manual path is still:
```bash
openclaw plugins install -l ./extensions/agora-plugin
openclaw config set plugins.entries.agora.config.serverUrl http://127.0.0.1:18420
```
It only automates safe plugin registration and Agora server wiring.
It does **not** rewrite OpenClaw Discord policy such as bot rosters, `allowBots`, `requireMention`, or guild/channel allowlists.
If you want semantic `project brain` retrieval, `./agora init` now offers an optional setup phase that:
- collects your embedding API settings
- verifies the embedding endpoint with a real probe request
- reuses a healthy local Qdrant on `127.0.0.1:6333` when available
- otherwise starts `qdrant/qdrant:latest` locally through Docker
- writes the verified vector config into the repo-root `.env`
That is the primary product path. Manual `.env` editing remains available as a fallback:
```bash
OPENAI_API_KEY=...
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_EMBEDDING_MODEL=text-embedding-3-small
OPENAI_EMBEDDING_DIMENSION=
QDRANT_URL=http://127.0.0.1:6333
QDRANT_API_KEY=
```
With that configured, these commands switch from raw lexical search to hybrid retrieval:
```bash
./agora projects brain index rebuild --project <project_id>
./agora projects brain query --task <task_id> --audience craftsman --query "runtime boundary" --mode auto
./agora projects brain bootstrap-context --task <task_id> --audience craftsman
```
For the end-to-end bootstrap guide, see:
- [Doc/06-INTEGRATIONS/openclaw/agora-openclaw-bootstrap-whitepaper.md](./Doc/06-INTEGRATIONS/openclaw/agora-openclaw-bootstrap-whitepaper.md)
### Developer Live Regression Mode
Agora now supports a developer-only live regression harness for real Discord task threads.
When enabled, the local agent can use AgoraBot as an operator proxy in `regression_test` tasks and drive live smoke/regression loops through the normal orchestration path.
Enable it explicitly in the repo-root `.env`:
```bash
AGORA_DEV_REGRESSION_MODE=true
AGORA_DASHBOARD_LOGIN_USER=
AGORA_DASHBOARD_LOGIN_PASSWORD=
```
This mode is for source-level developers iterating on Agora itself.
Keep it disabled for normal product usage.
Typical commands:
```bash
cd agora-ts
npm run dev -w @agora-ts/cli -- dashboard session login
npm run smoke:discord:regression
npm run dev -w @agora-ts/cli -- regression live --task-id <task_id> --goal "validate the current Discord flow" --message "Drive this task forward and report what blocks you."
```
When `AGORA_DEV_REGRESSION_MODE=true`, `agora dashboard session login` can read `AGORA_DASHBOARD_LOGIN_USER` / `AGORA_DASHBOARD_LOGIN_PASSWORD` directly from the repo-root `.env`.
Default local endpoints:
- API: `http://127.0.0.1:18420/api/health`
- Dashboard: `http://127.0.0.1:33173/dashboard/`
### Create A Task
```bash
./agora create "Add authentication middleware to the API"
```
### Typical Flow
```text
Create task
-> Citizens discuss
-> Archon reviews
-> execution-only or dialogue-capable executor is selected
-> ACPX-backed execution runs
-> output is reviewed and archived
```
### Quality Gates
```bash
cd agora-ts
npm run check:strict
npm run scenario:all
```
---
## Use Cases
- requirement clarification with competing agent viewpoints
- architecture and implementation review with explicit human gates
- code/test/review delivery after discussion converges
- project and context isolation across multiple agent groups
- selective participant exposure in long-running task threads
- auditable human-in-the-loop orchestration for real work
---
## Comparison
| | Agora | IM bot only | CrewAI / AutoGen | LangGraph |
| --- | --- | --- | --- | --- |
| Multi-agent discussion | ✅ | ⚠️ ad hoc | ✅ | ⚠️ |
| Human gates | ✅ | ❌ | ⚠️ | ⚠️ |
| Participant exposure policy | ✅ | ❌ | ❌ | ❌ |
| Execution as governed role | ✅ | ❌ | ⚠️ | ⚠️ |
| Provider-neutral orchestration core | ✅ | ❌ | ❌ | ⚠️ |
---
## Roadmap
- [x] PoC: multi-bot threads, task commands, subagent dispatch
- [x] State machine and gate foundation
- [x] Dashboard and review surfaces
- [x] ACPX-backed default execution substrate
- [x] tmux public shell retirement
- [ ] execution exposure policy hardening
- [ ] richer project / brain / citizen workbench
- [ ] more runtime and IM adapters
- [ ] multi-tenant governance and SaaS mode
---
## Repository Layout
```text
agora-ts/ TypeScript implementation
dashboard/ React dashboard
Doc/ public docs bundle
docs/ architecture / planning / walkthrough docs (separate git repo)
extensions/ external adapters and plugins
```
---
## Contributing
High-value areas:
- orchestration and governance semantics
- runtime and IM adapters
- dashboard operator experience
- project / task / archive workflows
- docs that clarify the social model
Start with [CONTRIBUTING.md](CONTRIBUTING.md).
If you are reading `AGENTS.md` without access to the private `docs/` repo, use the public mirror in [Doc/agents-contributor-reference.md](Doc/agents-contributor-reference.md).