# cyberash-dev/veche architecture

> Architecture diagram of the GitHub repository cyberash-dev/veche, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cyberash-dev/veche
- Repository: https://github.com/cyberash-dev/veche

## Overview

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: [`src/features/persistence`](https://github.com/cyberash-dev/veche/tree/main/src/features/persistence) (Meeting store), [`src/infra/bootstrap.ts`](https://github.com/cyberash-dev/veche/blob/main/src/infra/bootstrap.ts) (Infra & shared), [`src/adapters/inbound/cli/VecheCli.ts`](https://github.com/cyberash-dev/veche/blob/main/src/adapters/inbound/cli/VecheCli.ts) (CLI commands), [`src/features/meeting`](https://github.com/cyberash-dev/veche/tree/main/src/features/meeting) (Meeting core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtimes"]
  node_bin_server["MCP server<br/>stdio entrypoint<br/>[veche-server.ts]"]
  node_bin_cli["CLI<br/>human entrypoint<br/>[veche.ts]"]
  node_mcp_adapter["MCP tools<br/>inbound adapter<br/>[VecheMcpServer.ts]"]
  node_cli_commands["CLI commands<br/>inbound adapter<br/>[VecheCli.ts]"]
  node_cli_renderers["Renderers<br/>presentation<br/>[text.ts]"]
  node_web_viewer["Web viewer<br/>inbound adapter<br/>[WatchServer.ts]"]
  node_install_flow["Install flow<br/>distribution concern<br/>[install.ts]"]
end

subgraph group_core["Core slices"]
  node_meeting_core{{"Meeting core<br/>orchestration slice"}}
  node_job_runner["Job runner<br/>execution service<br/>[JobRunner.ts]"]
  node_committee_protocol{{"Committee protocol<br/>deliberation slice"}}
  node_human_participant(("Human turn<br/>interactive participant"))
  node_agent_integration{{"Agent integration<br/>external boundary"}}
  node_codex_agent["Codex agent<br/>subprocess adapter"]
  node_claude_agent["Claude agent<br/>subprocess adapter"]
end

subgraph group_storage["State"]
  node_persistence[("Meeting store<br/>storage port")]
  node_file_store[("File store<br/>persistent adapter")]
  node_memory_store[("Memory store<br/>ephemeral adapter")]
end

subgraph group_infra["Infrastructure"]
  node_shared_infra["Infra & shared<br/>bootstrap/runtime<br/>[bootstrap.ts]"]
end

node_bin_server -->|"starts"| node_mcp_adapter
node_bin_cli -->|"starts"| node_cli_commands
node_cli_commands -->|"renders"| node_cli_renderers
node_cli_commands -->|"includes"| node_install_flow
node_mcp_adapter -->|"orchestrates"| node_meeting_core
node_cli_commands -->|"reads"| node_persistence
node_web_viewer -->|"reads"| node_persistence
node_web_viewer -->|"controls"| node_human_participant
node_meeting_core -->|"delegates"| node_job_runner
node_job_runner -->|"runs"| node_committee_protocol
node_committee_protocol -->|"dispatches"| node_agent_integration
node_committee_protocol -->|"waits for"| node_human_participant
node_agent_integration -->|"launches"| node_codex_agent
node_agent_integration -->|"launches"| node_claude_agent
node_meeting_core -->|"writes"| node_persistence
node_persistence -->|"default"| node_file_store
node_persistence -->|"alt mode"| node_memory_store
node_shared_infra -->|"boots"| node_bin_server
node_shared_infra -->|"boots"| node_bin_cli
node_shared_infra -->|"supports"| node_meeting_core
node_shared_infra -->|"supports"| node_persistence

click node_bin_server "https://github.com/cyberash-dev/veche/blob/main/src/bin/veche-server.ts"
click node_bin_cli "https://github.com/cyberash-dev/veche/blob/main/src/bin/veche.ts"
click node_mcp_adapter "https://github.com/cyberash-dev/veche/blob/main/src/adapters/inbound/mcp/VecheMcpServer.ts"
click node_cli_commands "https://github.com/cyberash-dev/veche/blob/main/src/adapters/inbound/cli/VecheCli.ts"
click node_cli_renderers "https://github.com/cyberash-dev/veche/blob/main/src/adapters/inbound/cli/renderers/text.ts"
click node_web_viewer "https://github.com/cyberash-dev/veche/blob/main/src/adapters/inbound/web/WatchServer.ts"
click node_meeting_core "https://github.com/cyberash-dev/veche/tree/main/src/features/meeting"
click node_job_runner "https://github.com/cyberash-dev/veche/blob/main/src/features/meeting/application/JobRunner.ts"
click node_committee_protocol "https://github.com/cyberash-dev/veche/tree/main/src/features/committee-protocol"
click node_human_participant "https://github.com/cyberash-dev/veche/blob/main/src/features/meeting/application/SubmitHumanTurnUseCase.ts"
click node_agent_integration "https://github.com/cyberash-dev/veche/tree/main/src/features/agent-integration"
click node_codex_agent "https://github.com/cyberash-dev/veche/blob/main/src/features/agent-integration/adapters/codex-cli/CodexCliAgentAdapter.ts"
click node_claude_agent "https://github.com/cyberash-dev/veche/blob/main/src/features/agent-integration/adapters/claude-code-cli/ClaudeCodeCliAgentAdapter.ts"
click node_persistence "https://github.com/cyberash-dev/veche/tree/main/src/features/persistence"
click node_file_store "https://github.com/cyberash-dev/veche/blob/main/src/features/persistence/adapters/file/FileMeetingStore.ts"
click node_memory_store "https://github.com/cyberash-dev/veche/blob/main/src/features/persistence/adapters/in-memory/InMemoryMeetingStore.ts"
click node_shared_infra "https://github.com/cyberash-dev/veche/blob/main/src/infra/bootstrap.ts"
click node_install_flow "https://github.com/cyberash-dev/veche/blob/main/src/adapters/inbound/cli/commands/install.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_bin_server,node_bin_cli,node_mcp_adapter,node_cli_commands,node_cli_renderers,node_web_viewer,node_install_flow toneBlue
class node_meeting_core,node_job_runner,node_committee_protocol,node_human_participant,node_agent_integration,node_codex_agent,node_claude_agent toneAmber
class node_persistence,node_file_store,node_memory_store toneMint
class node_shared_infra toneRose
```

## Components

### Runtimes

Entrypoints and user-facing execution surfaces

- [MCP server](https://github.com/cyberash-dev/veche/blob/main/src/bin/veche-server.ts): stdio entrypoint · Starts the stdio MCP server for orchestrator agents · `src/bin/veche-server.ts`
- [CLI](https://github.com/cyberash-dev/veche/blob/main/src/bin/veche.ts): human entrypoint · Starts the human-facing command line interface · `src/bin/veche.ts`
- [MCP tools](https://github.com/cyberash-dev/veche/blob/main/src/adapters/inbound/mcp/VecheMcpServer.ts): inbound adapter · Exposes start, send, get-response and other MCP workflows · `src/adapters/inbound/mcp/VecheMcpServer.ts`
- [CLI commands](https://github.com/cyberash-dev/veche/blob/main/src/adapters/inbound/cli/VecheCli.ts): inbound adapter · Implements list, show, watch, and install commands · `src/adapters/inbound/cli/VecheCli.ts`
- [Renderers](https://github.com/cyberash-dev/veche/blob/main/src/adapters/inbound/cli/renderers/text.ts): presentation · Formats transcripts as text, markdown, HTML, or JSON · `src/adapters/inbound/cli/renderers/text.ts`
- [Web viewer](https://github.com/cyberash-dev/veche/blob/main/src/adapters/inbound/web/WatchServer.ts): inbound adapter · Local loopback viewer with SSE updates and human controls · `src/adapters/inbound/web/WatchServer.ts`
- [Install flow](https://github.com/cyberash-dev/veche/blob/main/src/adapters/inbound/cli/commands/install.ts): distribution concern · 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](https://github.com/cyberash-dev/veche/tree/main/src/features/meeting): orchestration slice · Owns meetings, jobs, transcripts, participants, and MCP-facing workflows · `src/features/meeting`
- [Job runner](https://github.com/cyberash-dev/veche/blob/main/src/features/meeting/application/JobRunner.ts): execution service · Drives job lifecycle and round execution · `src/features/meeting/application/JobRunner.ts`
- [Committee protocol](https://github.com/cyberash-dev/veche/tree/main/src/features/committee-protocol): deliberation slice · Runs rounds, pass handling, dropout, and termination logic · `src/features/committee-protocol`
- [Human turn](https://github.com/cyberash-dev/veche/blob/main/src/features/meeting/application/SubmitHumanTurnUseCase.ts): interactive participant · Optional human-in-the-loop pause, agree, skip, or steer actions · `src/features/meeting/application/SubmitHumanTurnUseCase.ts`
- [Agent integration](https://github.com/cyberash-dev/veche/tree/main/src/features/agent-integration): external boundary · Resolves profiles and launches Codex or Claude Code subprocess participants · `src/features/agent-integration`
- [Codex agent](https://github.com/cyberash-dev/veche/blob/main/src/features/agent-integration/adapters/codex-cli/CodexCliAgentAdapter.ts): subprocess adapter · Invokes codex exec for participant turns · `src/features/agent-integration/adapters/codex-cli/CodexCliAgentAdapter.ts`
- [Claude agent](https://github.com/cyberash-dev/veche/blob/main/src/features/agent-integration/adapters/claude-code-cli/ClaudeCodeCliAgentAdapter.ts): subprocess adapter · 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](https://github.com/cyberash-dev/veche/tree/main/src/features/persistence): storage port · Shared meeting-state persistence boundary · `src/features/persistence`
- [File store](https://github.com/cyberash-dev/veche/blob/main/src/features/persistence/adapters/file/FileMeetingStore.ts): persistent adapter · Default file-backed JSONL store under VECHE_HOME · `src/features/persistence/adapters/file/FileMeetingStore.ts`
- [Memory store](https://github.com/cyberash-dev/veche/blob/main/src/features/persistence/adapters/in-memory/InMemoryMeetingStore.ts): ephemeral adapter · In-memory store selected via VECHE_STORE · `src/features/persistence/adapters/in-memory/InMemoryMeetingStore.ts`

### Infrastructure

Composition and cross-cutting runtime services

- [Infra & shared](https://github.com/cyberash-dev/veche/blob/main/src/infra/bootstrap.ts): bootstrap/runtime · Bootstrap wiring, logging, clock, ids, config, and shared primitives · `src/infra/bootstrap.ts`

## Connections

- 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
