How cyberash-dev/veche works
1. What this repo is
- Veche is a local MCP server + companion CLI + local web viewer for running structured multi-agent “committee meetings.”
- The core business object is a Meeting containing one or more Jobs; each job drives a round-based deliberation until termination.
2. Primary runtime entrypoints
- src/bin/veche-server.ts starts the stdio MCP server used by orchestrator agents.
- src/bin/veche.ts starts the human-facing CLI (list, show, watch, install).
- The CLI and MCP server both operate on the same underlying meeting store, so they can run concurrently.
3. Top-level architecture style
- The code follows Hexagonal + Vertical Slices.
- Each feature lives in src/features/<feature>/ with separate domain/, application/, ports/, and adapters/ as needed.
- Inbound adapters live under src/adapters/inbound/ and are thin shells around the feature application layer.
4. Core domain slices
- meeting: the central orchestration slice; owns meetings, jobs, transcripts, participant state, and the MCP tool workflows.
- committee-protocol: the deliberation algorithm itself; handles rounds, pass signals (<PASS/>), dropout, and termination conditions.
- agent-integration: resolves participant profiles and wraps external CLI agents such as Codex and Claude Code.
- persistence: stores meeting state using either file-backed JSONL or in-memory storage.
5. Main data flow for a meeting
- An orchestrator calls MCP tools such as start_meeting, send_message, and get_response.
- send_message creates a Job; the committee protocol runner dispatches turns to active participants in parallel.
- Each agent adapter returns speech or <PASS/>; results are merged into the meeting transcript.
- Polling via get_response exposes job status plus transcript deltas until the job terminates.
6. Human + machine interaction model
- Meetings may include an optional Human Participant.
- When enabled, the job pauses in a waiting state after a model round and accepts human actions like agree, skip, or steer.
- Human-facing controls are exposed through the MCP tool surface and the local web viewer.
7. External agent execution boundary
- agent-integration is the boundary to real model processes.
- Codex participants are launched through codex exec; Claude Code participants through claude -p.
- The Claude adapter includes a recursion guard so a child Claude cannot re-enter the same MCP server and recursively spawn more agents.
8. Persistence and storage boundary
- Default storage is file-backed under $VECHE_HOME; the README describes the file store as shared safely between processes.
- VECHE_STORE can switch between file and memory, which changes persistence behavior without changing core meeting logic.
- The CLI read-only views (list, show, watch) read from the same store as the MCP server, enabling cross-process visibility.
9. Web viewer subsystem
- src/adapters/inbound/web/ implements the local viewer: a loopback HTTP server, SSE channels, and a single-page app.
- It watches the on-disk store and streams live updates for meeting lists and selected meeting transcripts.
- The viewer is intentionally narrow in write scope: only human-turn and participation toggles are exposed.
10. CLI rendering subsystem
- src/adapters/inbound/cli/ provides the human CLI and transcript renderers for text, markdown, HTML, and JSON.
- show --format html produces a self-contained offline report.
- watch reuses the web viewer infrastructure for live inspection; list and show are read-only over the store.
11. Shared infrastructure
- src/infra/ provides composition and runtime services: bootstrap wiring, structured logging, system clock, UUID generation, and config loading.
- src/shared/ contains cross-cutting primitives such as branded IDs, domain errors, and port interfaces for clock, ID generation, and logging.
- These keep the feature slices isolated from concrete runtime concerns.
12. Specification-first organization
- The repo is explicitly spec-driven: spec/spec.md and spec/partitions/*.md define behavior for install, meeting, committee protocol, persistence, agent integration, and web viewer.
- The implementation is organized to match those partitions, which is why the feature boundaries are so prominent in the tree.
13. Operational and packaging boundary
- veche install wires the tool into external hosts like Claude Code, Codex, and optionally Hermes by copying skill metadata and registering the MCP server.
- This is an installation/distribution concern, not part of the meeting runtime itself, but it affects how the server is discovered and launched.
14. What to draw in an architecture diagram
- The central box should be the meeting/committee protocol core.
- On the left, show MCP host/orchestrator agents invoking the stdio MCP server.
- On the bottom/right, show external CLI agents (Codex, Claude Code) as subprocess-bound participants.
- Add file/in-memory persistence as the shared state boundary.
- Add CLI and web viewer as separate inbound read paths over the same store.
Main entry points: persistence Meeting store · bootstrap.ts Infra & shared · VecheCli.ts CLI commands · meeting Meeting core
Components 18
Runtimes
Entrypoints and user-facing execution surfaces
- MCP server · Starts the stdio MCP server for orchestrator agents
src/bin/veche-server.ts - CLI · Starts the human-facing command line interface
src/bin/veche.ts - MCP tools · Exposes start, send, get-response and other MCP workflows
src/adapters/inbound/mcp/VecheMcpServer.ts - CLI commands · Implements list, show, watch, and install commands
src/adapters/inbound/cli/VecheCli.ts - Renderers · Formats transcripts as text, markdown, HTML, or JSON
src/adapters/inbound/cli/renderers/text.ts - Web viewer · Local loopback viewer with SSE updates and human controls
src/adapters/inbound/web/WatchServer.ts - Install flow · Registers the MCP server and copies skill metadata into host tools
src/adapters/inbound/cli/commands/install.ts
Core slices
Main domain and application logic
- Meeting core · Owns meetings, jobs, transcripts, participants, and MCP-facing workflows
src/features/meeting - Job runner · Drives job lifecycle and round execution
src/features/meeting/application/JobRunner.ts - Committee protocol · Runs rounds, pass handling, dropout, and termination logic
src/features/committee-protocol - Human turn · Optional human-in-the-loop pause, agree, skip, or steer actions
src/features/meeting/application/SubmitHumanTurnUseCase.ts - Agent integration · Resolves profiles and launches Codex or Claude Code subprocess participants
src/features/agent-integration - Codex agent · Invokes codex exec for participant turns
src/features/agent-integration/adapters/codex-cli/CodexCliAgentAdapter.ts - Claude agent · Invokes claude -p with recursion guard against re-entry
src/features/agent-integration/adapters/claude-code-cli/ClaudeCodeCliAgentAdapter.ts
State
Shared persistence boundary
- Meeting store · Shared meeting-state persistence boundary
src/features/persistence - File store · Default file-backed JSONL store under VECHE_HOME
src/features/persistence/adapters/file/FileMeetingStore.ts - Memory store · In-memory store selected via VECHE_STORE
src/features/persistence/adapters/in-memory/InMemoryMeetingStore.ts
Infrastructure
Composition and cross-cutting runtime services
- Infra & shared · Bootstrap wiring, logging, clock, ids, config, and shared primitives
src/infra/bootstrap.ts
Connections 21
- MCP server → MCP tools: starts · Bootstraps the MCP server runtime and request handlers
- CLI → CLI commands: starts · Bootstraps the human CLI command surface
- CLI commands → Renderers: renders · Formats read-only views and offline reports
- CLI commands → Install flow: includes · Runs the installation/distribution workflow
- MCP tools → Meeting core: orchestrates · Maps MCP tools to meeting use cases
- CLI commands → Meeting store: reads · List, show, and watch inspect the shared store
- Web viewer → Meeting store: reads · Polls the on-disk store and streams updates
- Web viewer → Human turn: controls · Exposes human-turn and participation toggles
- Meeting core → Job runner: delegates · Creates jobs and drives job lifecycle
- Job runner → Committee protocol: runs · Executes rounds and termination decisions
- Committee protocol → Agent integration: dispatches · Sends turns to active participants in parallel
- Committee protocol → Human turn: waits for · Pauses when a human turn is enabled
- Agent integration → Codex agent: launches · Spawns Codex subprocess participants
- Agent integration → Claude agent: launches · Spawns Claude Code subprocess participants
- Meeting core → Meeting store: writes · Persists meeting state, jobs, and transcript deltas
- Meeting store → File store: default · Uses the shared file-backed store by default
- Meeting store → Memory store: alt mode · Switches to in-memory behavior when configured
- Infra & shared → MCP server: boots · Provides composition and runtime services
- Infra & shared → CLI: boots · Provides composition and runtime services
- Infra & shared → Meeting core: supports · Supplies logging, clock, id generation, and config
- Infra & shared → Meeting store: supports · Supplies runtime configuration and shared primitives