# behzade/farcaster architecture

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

- Interactive diagram: https://gitdiagram.com/behzade/farcaster
- Repository: https://github.com/behzade/farcaster

## Overview

Farcaster is a native, keyboard-first workspace that coordinates existing coding-agent harnesses alongside per-session editor and terminal workflows. Users compose prompts in the desktop app, run them through a shared runtime and harness-specific adapters, then review streamed conversation and code changes. The README also documents project/session management, Neovim context and review, and optional MCP tools for workers and persistent workgraphs. The tree and excerpts establish the main subsystems; some detailed runtime wiring was not sampled, so the graph omits uncertain internal links.

Main entry points: [`src/app/mod.rs`](https://github.com/behzade/farcaster/blob/main/src/app/mod.rs) (Workspace UI), [`crates/runtime/src/runtime/mod.rs`](https://github.com/behzade/farcaster/blob/main/crates/runtime/src/runtime/mod.rs) (Session runtime), [`crates/mcp-server/src/lib.rs`](https://github.com/behzade/farcaster/blob/main/crates/mcp-server/src/lib.rs) (Optional MCP server), [`crates/agents/src/adapter/mod.rs`](https://github.com/behzade/farcaster/blob/main/crates/agents/src/adapter/mod.rs) (Harness adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop workspace"]
  node_desktop_ui["Workspace UI<br/>[mod.rs]"]
  node_composer["Prompt composer<br/>[submissions.rs]"]
  node_editor_terminal["Editor and terminal<br/>[editor_launch.rs]"]
end

subgraph group_execution["Agent execution"]
  node_runtime["Session runtime<br/>[mod.rs]"]
  node_supervisor["Run supervisor<br/>[supervisor.rs]"]
  node_worker_pool["Worker pool<br/>[pool.rs]"]
  node_harness_adapters["Harness adapters<br/>[mod.rs]"]
  node_conversation["Conversation stream<br/>[lib.rs]"]
end

subgraph group_context["Project context"]
  node_projects["Project management<br/>[lib.rs]"]
  node_repository["Repository context<br/>[lib.rs]"]
  node_access["Access controls<br/>[lib.rs]"]
end

subgraph group_state["Sessions and state"]
  node_sessions["Session catalog<br/>[lib.rs]"]
  node_storage[("Persistent state<br/>[lib.rs]")]
end

subgraph group_tools["Coordination tools"]
  node_mcp_server["Optional MCP server<br/>[lib.rs]"]
  node_worker_tools["Worker coordination<br/>[workers.rs]"]
  node_workgraph["Persistent workgraph<br/>[application.rs]"]
  node_reviews["Review artifacts<br/>[lib.rs]"]
end

node_user(("User"))
node_external_harnesses{{"Agent harnesses"}}
node_neovim{{"Neovim"}}

node_user -->|"interacts"| node_desktop_ui
node_desktop_ui -->|"opens composer"| node_composer
node_composer -->|"submits prompt"| node_runtime
node_runtime -->|"coordinates runs"| node_supervisor
node_supervisor -->|"dispatches work"| node_worker_pool
node_worker_pool -->|"creates workers"| node_harness_adapters
node_harness_adapters -->|"launches sessions"| node_external_harnesses
node_harness_adapters -->|"emits events"| node_conversation
node_runtime -->|"publishes updates"| node_desktop_ui
node_desktop_ui -->|"manages projects"| node_projects
node_projects -->|"uses repository"| node_repository
node_desktop_ui -->|"selects sessions"| node_sessions
node_sessions -->|"persists session data"| node_storage
node_runtime -->|"stores runtime state"| node_storage
node_desktop_ui -->|"opens session tools"| node_editor_terminal
node_editor_terminal -.->|"opens editor"| node_neovim
node_neovim -.->|"sends context"| node_desktop_ui
node_desktop_ui -.->|"enables optionally"| node_mcp_server
node_mcp_server -->|"dispatches tools"| node_worker_tools
node_worker_tools -->|"coordinates workers"| node_worker_pool
node_mcp_server -->|"invokes workgraph"| node_workgraph
node_mcp_server -->|"records reviews"| node_reviews
node_reviews -.->|"presents review"| node_neovim
node_runtime -->|"applies access mode"| node_access
node_desktop_ui -->|"displays transcript"| node_conversation

click node_desktop_ui "https://github.com/behzade/farcaster/blob/main/src/app/mod.rs"
click node_composer "https://github.com/behzade/farcaster/blob/main/src/app/composer/submissions.rs"
click node_editor_terminal "https://github.com/behzade/farcaster/blob/main/src/app/infrastructure/editor_launch.rs"
click node_runtime "https://github.com/behzade/farcaster/blob/main/crates/runtime/src/runtime/mod.rs"
click node_supervisor "https://github.com/behzade/farcaster/blob/main/crates/runtime/src/runtime/supervisor.rs"
click node_worker_pool "https://github.com/behzade/farcaster/blob/main/crates/agents/src/core/pool.rs"
click node_harness_adapters "https://github.com/behzade/farcaster/blob/main/crates/agents/src/adapter/mod.rs"
click node_conversation "https://github.com/behzade/farcaster/blob/main/crates/conversation/src/lib.rs"
click node_projects "https://github.com/behzade/farcaster/blob/main/crates/projects/src/lib.rs"
click node_repository "https://github.com/behzade/farcaster/blob/main/crates/repository/src/lib.rs"
click node_access "https://github.com/behzade/farcaster/blob/main/crates/access/src/lib.rs"
click node_sessions "https://github.com/behzade/farcaster/blob/main/crates/sessions/src/lib.rs"
click node_storage "https://github.com/behzade/farcaster/blob/main/crates/storage/src/lib.rs"
click node_mcp_server "https://github.com/behzade/farcaster/blob/main/crates/mcp-server/src/lib.rs"
click node_worker_tools "https://github.com/behzade/farcaster/blob/main/crates/mcp-server/src/workers.rs"
click node_workgraph "https://github.com/behzade/farcaster/blob/main/workgraph/src/application.rs"
click node_reviews "https://github.com/behzade/farcaster/blob/main/crates/reviews/src/lib.rs"

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_desktop_ui,node_composer,node_editor_terminal,node_user toneBlue
class node_runtime,node_supervisor,node_worker_pool,node_harness_adapters,node_conversation toneAmber
class node_projects,node_repository,node_access toneMint
class node_sessions,node_storage toneRose
class node_mcp_server,node_worker_tools,node_workgraph,node_reviews,node_external_harnesses,node_neovim toneIndigo
```

## Components

### Desktop workspace

- [Workspace UI](https://github.com/behzade/farcaster/blob/main/src/app/mod.rs): `src/app/mod.rs`
- [Prompt composer](https://github.com/behzade/farcaster/blob/main/src/app/composer/submissions.rs): `src/app/composer/submissions.rs`
- [Editor and terminal](https://github.com/behzade/farcaster/blob/main/src/app/infrastructure/editor_launch.rs): `src/app/infrastructure/editor_launch.rs`

### Agent execution

- [Session runtime](https://github.com/behzade/farcaster/blob/main/crates/runtime/src/runtime/mod.rs): `crates/runtime/src/runtime/mod.rs`
- [Run supervisor](https://github.com/behzade/farcaster/blob/main/crates/runtime/src/runtime/supervisor.rs): `crates/runtime/src/runtime/supervisor.rs`
- [Worker pool](https://github.com/behzade/farcaster/blob/main/crates/agents/src/core/pool.rs): `crates/agents/src/core/pool.rs`
- [Harness adapters](https://github.com/behzade/farcaster/blob/main/crates/agents/src/adapter/mod.rs): `crates/agents/src/adapter/mod.rs`
- [Conversation stream](https://github.com/behzade/farcaster/blob/main/crates/conversation/src/lib.rs): `crates/conversation/src/lib.rs`

### Project context

- [Project management](https://github.com/behzade/farcaster/blob/main/crates/projects/src/lib.rs): `crates/projects/src/lib.rs`
- [Repository context](https://github.com/behzade/farcaster/blob/main/crates/repository/src/lib.rs): `crates/repository/src/lib.rs`
- [Access controls](https://github.com/behzade/farcaster/blob/main/crates/access/src/lib.rs): `crates/access/src/lib.rs`

### Sessions and state

- [Session catalog](https://github.com/behzade/farcaster/blob/main/crates/sessions/src/lib.rs): `crates/sessions/src/lib.rs`
- [Persistent state](https://github.com/behzade/farcaster/blob/main/crates/storage/src/lib.rs): `crates/storage/src/lib.rs`

### Coordination tools

- [Optional MCP server](https://github.com/behzade/farcaster/blob/main/crates/mcp-server/src/lib.rs): `crates/mcp-server/src/lib.rs`
- [Worker coordination](https://github.com/behzade/farcaster/blob/main/crates/mcp-server/src/workers.rs): `crates/mcp-server/src/workers.rs`
- [Persistent workgraph](https://github.com/behzade/farcaster/blob/main/workgraph/src/application.rs): `workgraph/src/application.rs`
- [Review artifacts](https://github.com/behzade/farcaster/blob/main/crates/reviews/src/lib.rs): `crates/reviews/src/lib.rs`

### Other components

- **User**
- **Agent harnesses**
- **Neovim**

## Connections

- User → Workspace UI: interacts
- Workspace UI → Prompt composer: opens composer
- Prompt composer → Session runtime: submits prompt
- Session runtime → Run supervisor: coordinates runs
- Run supervisor → Worker pool: dispatches work
- Worker pool → Harness adapters: creates workers
- Harness adapters → Agent harnesses: launches sessions
- Harness adapters → Conversation stream: emits events
- Session runtime → Workspace UI: publishes updates
- Workspace UI → Project management: manages projects
- Project management → Repository context: uses repository
- Workspace UI → Session catalog: selects sessions
- Session catalog → Persistent state: persists session data
- Session runtime → Persistent state: stores runtime state
- Workspace UI → Editor and terminal: opens session tools
- Editor and terminal → Neovim: opens editor
- Neovim → Workspace UI: sends context
- Workspace UI → Optional MCP server: enables optionally
- Optional MCP server → Worker coordination: dispatches tools
- Worker coordination → Worker pool: coordinates workers
- Optional MCP server → Persistent workgraph: invokes workgraph
- Optional MCP server → Review artifacts: records reviews
- Review artifacts → Neovim: presents review
- Session runtime → Access controls: applies access mode
- Workspace UI → Conversation stream: displays transcript