{"id":45765213,"url":"https://github.com/leonardocbsr/multiagents","last_synced_at":"2026-02-26T00:58:05.354Z","repository":{"id":336702313,"uuid":"1150036796","full_name":"leonardocbsr/multiagents","owner":"leonardocbsr","description":"Multi-agent AI orchestration platform — collaborate with Claude, Codex, and Kimi with kanban workflows, memory, personas, and real-time streaming","archived":false,"fork":false,"pushed_at":"2026-02-06T04:02:15.000Z","size":362,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-06T04:06:05.089Z","etag":null,"topics":["ai","claude","codex","fastapi","kanban","kimi","multiagent","orchestration","react","websocket"],"latest_commit_sha":null,"homepage":null,"language":"Python","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/leonardocbsr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-04T20:07:07.000Z","updated_at":"2026-02-06T04:02:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/leonardocbsr/multiagents","commit_stats":null,"previous_names":["leonardocbsr/multiagents"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/leonardocbsr/multiagents","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonardocbsr%2Fmultiagents","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonardocbsr%2Fmultiagents/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonardocbsr%2Fmultiagents/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonardocbsr%2Fmultiagents/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leonardocbsr","download_url":"https://codeload.github.com/leonardocbsr/multiagents/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonardocbsr%2Fmultiagents/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29846536,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-25T22:37:40.667Z","status":"ssl_error","status_checked_at":"2026-02-25T22:37:25.960Z","response_time":61,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["ai","claude","codex","fastapi","kanban","kimi","multiagent","orchestration","react","websocket"],"created_at":"2026-02-26T00:58:03.225Z","updated_at":"2026-02-26T00:58:05.346Z","avatar_url":"https://github.com/leonardocbsr.png","language":"Python","readme":"# Multiagents\n\nMulti-agent AI orchestration platform. Run collaborative sessions with Claude, Codex, and Kimi — featuring event-driven messaging, round consensus with `[PASS]`, kanban task workflows, agent personas, cross-session memory, and real-time streaming.\n\n## Features\n\n- **Event-driven collaboration with rounds** — agents react to incoming events in real time; rounds close on settlement and advance after all agents return `[PASS]`\n- **Kanban task workflows** — cards move through Backlog, Planning, Reviewing, Implementing, Done\n- **Agent personas** — dynamic roles let you run multiple instances of the same model with different specializations\n- **Direct messages** — message individual agents mid-discussion\n- **Cross-session memory** — agent learning profiles persist and grow across sessions\n- **Split layout** — agent raw streams | shared narrative | kanban board\n- **Real-time streaming** — live output via WebSocket with tool badges and thinking blocks\n- **Configurable settings** — models, system prompts, and timeouts adjustable from the UI\n- **Session persistence** — SQLite-backed history with replay on reconnect\n- **Pause/resume/cancel** — full control over ongoing discussions\n- **Web-first client** — responsive browser UI for local development\n\n## Quick Start\n\n```bash\n./setup.sh          # Install Python + Node dependencies\n./start.sh --backend python   # Launch backend + frontend (http://localhost:5174)\n```\n\nOr manually:\n\n```bash\npip install -e .                # Backend dependencies\ncd web \u0026\u0026 pnpm install          # Frontend dependencies\n./start.sh --backend python     # Run both\n```\n\nSee the [Quickstart Tutorial](./docs/quickstart.md) for a guided walkthrough.\n\n## UI Preview\n\nSession picker:\n\n![Session picker](./docs/images/session-picker.png)\n\nCreate session flow:\n\n![Create session](./docs/images/roster-editor.png)\n\nMain workspace:\n\n![Chat workspace](./docs/images/chat-layout.png)\n\nSettings modal:\n\n![Settings modal](./docs/images/settings-modal.png)\n\n## Runtime Controls\n\n- `Stop agent`: interrupt one agent's active turn.\n- `Stop round`: interrupt all active turns in the current round.\n- `Resume`: continue after a paused round.\n- `Direct message`: send a targeted instruction to one agent.\n  - If active, the agent is restarted with the DM.\n  - If idle, the DM triggers a focused single-agent turn.\n\n## Technology Stack\n\n### Backend (Python)\n- **Language**: Python 3.12+\n- **Framework**: FastAPI with native WebSocket support\n- **Server**: Uvicorn\n- **Database**: SQLite with WAL mode (`~/.multiagents/multiagents.db`)\n- **Build**: Hatchling\n\n### Frontend\n- **Language**: TypeScript ~5.9\n- **Framework**: React 19\n- **Build Tool**: Vite 7\n- **Styling**: Tailwind CSS 4 with Typography plugin\n- **Package Manager**: pnpm\n\n## Project Structure\n\n```\n.\n├── pyproject.toml              # Python project config \u0026 dependencies\n├── setup.sh                    # One-command install script\n├── start.sh                    # Full-stack dev launcher\n├── scripts/\n│   └── multiagents-cards       # Cards CLI utility\n├── src/                        # Python backend source\n│   ├── main.py                 # CLI entry point \u0026 server bootstrap\n│   ├── agents/                 # AI agent integrations\n│   │   ├── base.py             # Abstract base agent class\n│   │   ├── persistent.py       # Long-lived subprocess management\n│   │   ├── claude.py           # Claude Code CLI integration\n│   │   ├── codex.py            # OpenAI Codex CLI integration\n│   │   ├── kimi.py             # Kimi Code CLI integration\n│   │   ├── prompts.py          # System prompts \u0026 persona templates\n│   │   └── protocols/          # Protocol adapters (claude, codex, kimi)\n│   ├── cards/                  # Kanban task engine\n│   ├── chat/                   # Chat orchestration \u0026 round settlement\n│   ├── memory/                 # Cross-session memory \u0026 learning\n│   └── server/                 # FastAPI app, WebSocket, REST APIs\n├── tests/                      # Test suite (pytest)\n├── web/                        # Frontend application\n│   ├── src/\n│   │   ├── App.tsx             # Main app component\n│   │   ├── types.ts            # TypeScript type definitions\n│   │   ├── hooks/              # React hooks (useWebSocket, etc.)\n│   │   ├── components/         # UI components\n│   │   └── components/ui/      # Reusable component library\n│   └── dist/                   # Built frontend assets\n└── docs/                       # Documentation \u0026 images\n```\n\n## Commands\n\n### Backend (Python)\n\n```bash\npip install -e .                                  # Install dependencies\npip install -e \".[dev]\"                           # Install with dev/test dependencies\npython3 -m src.main                               # Run server (port 8421)\nmultiagents --agents claude,codex --port 8080     # Custom options\npytest                                            # Run all tests\npytest tests/test_room.py -k test_name            # Run single test\n```\n\n### Frontend\n\n```bash\ncd web \u0026\u0026 pnpm install       # Install dependencies\ncd web \u0026\u0026 pnpm dev           # Dev server (port 5174, proxies to backend)\ncd web \u0026\u0026 pnpm build         # Production build (includes lint:ui-tokens + tsc)\n```\n\n### Full Stack\n\n```bash\n./start.sh --backend python                       # Python backend + frontend\n./start.sh --backend python --port 8080 --agents claude,codex  # Custom options\n```\n\n### CLI Arguments\n\n```\n-a, --agents        Comma-separated agent list (default: claude,codex,kimi)\n-t, --timeout       Idle timeout per agent in seconds (default: 1800)\n--parse-timeout     Timeout for parsing agent output (default: 1200)\n--send-timeout      WebSocket send timeout (default: 120)\n--hard-timeout      Hard timeout per agent, 0 = disabled (default: 0)\n--host              Bind host (default: 127.0.0.1)\n--port              Bind port (default: 8421)\n```\n\nBy default, the server binds to loopback (`127.0.0.1`). Use `--host 0.0.0.0` only when you intentionally want LAN access.\n\n## Architecture\n\n### Python Backend (`src/`)\n\nFive layers: **agents** spawn and stream from external CLI tools via protocol adapters, **chat** orchestrates event-driven messaging with round settlement, **memory** provides cross-session learning, **cards** runs kanban workflows, **server** handles WebSocket connections and persistence.\n\n**Agent layer** (`src/agents/`): Each agent (Claude, Codex, Kimi) inherits `BaseAgent` and wraps an external CLI. `PersistentAgent` manages long-lived subprocesses with bidirectional stdio, crash recovery (exponential backoff, max 3 retries), and session ID tracking for resume.\n\n**Protocol adapters** (`src/agents/protocols/`): Each CLI has a dedicated `ProtocolAdapter` subclass that translates wire-level JSON into common event types (`TextDelta`, `ThinkingDelta`, `ToolBadge`, `TurnComplete`).\n\n**Chat layer** (`src/chat/`): `ChatRoom` runs persistent event loops as an async generator yielding typed `ChatEvent` dataclasses. Features DM debouncing, per-agent inbox queues, `[PASS]` detection, coordination pattern extraction, and `\u003cShare\u003e` tag protocol.\n\n**Memory layer** (`src/memory/`): Cross-session learning system. Persists to project-local `.multiagents/memory.db`. Extracts insights via LLM and injects agent profiles into prompts.\n\n**Cards layer** (`src/cards/`): Kanban workflow engine with role delegation, `[DONE]` detection, and phase transitions. Cards flow: Backlog → Planning → Reviewing → Implementing → Done.\n\n**Server layer** (`src/server/`): FastAPI app with WebSocket at `/ws` and REST APIs. Manages per-session chat tasks, WebSocket subscriber broadcast, and pre-warmed agent pools.\n\n### Frontend (`web/src/`)\n\nReact 19 + Tailwind CSS 4 SPA. `useWebSocket` hook manages the connection lifecycle with auto-reconnect (exponential backoff) and a reducer for state updates. The WebSocket protocol uses `event_id` for replay on reconnect. UI components use a local component library (`components/ui/`) with semantic design tokens enforced by `lint:ui-tokens` (blocks raw Tailwind palette colors in favor of semantic classes).\n\n### REST API\n\n**Sessions**: `GET/POST /api/sessions`, `GET/DELETE /api/sessions/{id}`, `GET /api/sessions/{id}/messages`, `GET /api/sessions/{id}/export`, `GET /api/sessions/{id}/status`\n**Cards**: `GET/POST /api/sessions/{id}/cards`, `GET/PATCH/DELETE /api/sessions/{id}/cards/{card_id}`\n**Settings**: `GET/PUT /api/settings`, `GET/PUT/DELETE /api/settings/{key}`\n**Other**: `GET /health`, `GET /api/filesystem/list?path=\u003cpath\u003e`\n\n### Key Protocols\n\n**Coordination patterns** are parsed both in `src/chat/router.py` (backend) and `web/src/types.ts` (frontend) using matching regexes. Patterns: `@AgentName` (mention), `+1 AgentName` (agreement), `[HANDOFF:Agent]`, `[EXPLORE]`, `[DECISION]`, `[BLOCKED]`, `[DONE]`, `[TODO]`, `[QUESTION]`.\n\n**Share tags**: Agents wrap coordinated content in `\u003cShare\u003e...\u003c/Share\u003e`. Backend extracts shareable content via `extract_shareable()` for history; content outside tags stays private.\n\n**Tool badges**: Streaming output wraps tool use in `\u003ctool\u003eName detail\u003c/tool\u003e` tags. Frontend renders these as inline UI badges.\n\n**WebSocket message types**: server emits events such as `round_started`, `agent_stream`, `agent_completed`, `round_ended`, `paused`, `agent_interrupted`, `dm_sent`, and client sends controls such as `message`, `stop_agent`, `stop_round`, `resume`, `direct_message`, `cancel`, `ack`.\n\n## Testing\n\n```bash\npytest               # Run all tests (Python backend)\npytest -v            # Verbose output\npytest tests/test_room.py -k test_name   # Single test\ncd web \u0026\u0026 pnpm build                     # Frontend build + lint\n```\n\nTests use `FakeAgent` mocks to simulate agent behavior without spawning real CLIs. Coverage includes event-driven room behavior, round settlement/advancement, prompt formatting, pass detection, and user message injection.\n\n## External Dependencies\n\nRequires these CLI tools in `$PATH`:\n\n- `claude` — Anthropic's Claude Code CLI\n- `codex` — OpenAI's Codex CLI\n- `kimi` — Moonshot AI's Kimi Code CLI\n\nYou only need one agent to get started, but the platform shines with two or more.\n\n## Agent Guidelines\n\nFor agent collaboration protocols, see [GUIDELINES.md](./GUIDELINES.md).\n\n## Project Policies\n\n- [Contributing Guide](./CONTRIBUTING.md)\n- [Security Policy](./SECURITY.md)\n- [Code of Conduct](./CODE_OF_CONDUCT.md)\n\n## License\n\n[MIT](./LICENSE)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleonardocbsr%2Fmultiagents","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleonardocbsr%2Fmultiagents","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleonardocbsr%2Fmultiagents/lists"}