# jacobbweber/companion-ai-os architecture

> Architecture diagram of the GitHub repository jacobbweber/companion-ai-os, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jacobbweber/companion-ai-os
- Repository: https://github.com/jacobbweber/companion-ai-os

## Overview

Companion is a local-first assistant and autonomous engineering workspace. A user enters through the web UI or CLI, sends a chat request, and receives a streamed response or tool-driven result; persistent memory and project state support that interaction. Separate product branches cover projects, calendar, learning and wiki, background routines, and governed engineering workflows. The graph includes the principal runtime and documented capabilities. Some domain modules were not sampled, so their internal call paths are not asserted.

Main entry points: [`companion/agent.py`](https://github.com/jacobbweber/companion-ai-os/blob/main/companion/agent.py) (Assistant agent), [`companion/memory_store.py`](https://github.com/jacobbweber/companion-ai-os/blob/main/companion/memory_store.py) (Memory store), [`surfaces/web_server.py`](https://github.com/jacobbweber/companion-ai-os/blob/main/surfaces/web_server.py) (Web server), [`companion/routines.py`](https://github.com/jacobbweber/companion-ai-os/blob/main/companion/routines.py) (Routine manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_webui["Web Studio<br/>[App.tsx]"]
  node_webserver["Web server<br/>[web_server.py]"]
  node_api["Web API<br/>[api_extensions.py]"]
  node_cli["CLI entry<br/>[harness.py]"]
end

subgraph group_runtime["Assistant runtime"]
  node_agent["Assistant agent<br/>[agent.py]"]
  node_llm["LLM router<br/>[llm.py]"]
  node_tools["Tool execution<br/>[tools.py]"]
  node_streaming["Response streaming<br/>[streaming.py]"]
end

subgraph group_state["Memory and projects"]
  node_memory[("Memory store<br/>[memory_store.py]")]
  node_project["Project graph<br/>[project_graph.py]"]
end

subgraph group_knowledge["Knowledge and planning"]
  node_calendar["Unified calendar<br/>[calendar_engine.py]"]
  node_wiki["Knowledge wiki<br/>[wiki_engine.py]"]
  node_education["Learning engine"]
end

subgraph group_automation["Automation and governance"]
  node_dag["DAG runtime<br/>[dag_runtime.py]"]
  node_workflow["Workflow graph<br/>[workflow_graph.py]"]
  node_routines["Routine manager<br/>[routines.py]"]
  node_jobs["Background jobs<br/>[background_jobs.py]"]
  node_approvals["Approvals and trust"]
  node_safety["Safety controls<br/>[safety.py]"]
  node_vault["Credential vault<br/>[vault.py]"]
  node_mcp["MCP hub<br/>[mcp_hub.py]"]
end

node_user(("User"))

node_user -->|"uses"| node_webui
node_webui -.->|"API requests"| node_webserver
node_webui -->|"calls"| node_api
node_webserver -->|"dispatches turns"| node_agent
node_webserver -->|"routes extensions"| node_api
node_cli -->|"starts assistant"| node_agent
node_agent -->|"requests completion"| node_llm
node_agent -->|"reads and writes"| node_memory
node_agent -->|"dispatches tools"| node_tools
node_agent -->|"uses project context"| node_project
node_webserver -->|"streams responses"| node_streaming
node_llm -->|"uses stream support"| node_streaming
node_project -->|"persists graph state"| node_memory
node_calendar -->|"uses stored state"| node_memory
node_education -->|"stores mastery"| node_memory
node_education -->|"curates study notes"| node_wiki
node_routines -->|"manages job routines"| node_jobs
node_routines -->|"runs DAG routines"| node_dag
node_routines -->|"requests approvals"| node_approvals
node_dag -->|"uses persistent state"| node_memory
node_workflow -.->|"persists workflow state"| node_memory
node_user -->|"uses"| node_cli
node_approvals -->|"stores approval state"| node_memory
node_safety -.->|"guards actions"| node_agent
node_vault -.->|"injects credentials"| node_tools
node_mcp -.->|"provides integrations"| node_tools

click node_webui "https://github.com/jacobbweber/companion-ai-os/blob/main/frontend/src/App.tsx"
click node_webserver "https://github.com/jacobbweber/companion-ai-os/blob/main/surfaces/web_server.py"
click node_api "https://github.com/jacobbweber/companion-ai-os/blob/main/surfaces/api_extensions.py"
click node_cli "https://github.com/jacobbweber/companion-ai-os/blob/main/harness.py"
click node_agent "https://github.com/jacobbweber/companion-ai-os/blob/main/companion/agent.py"
click node_llm "https://github.com/jacobbweber/companion-ai-os/blob/main/companion/llm.py"
click node_tools "https://github.com/jacobbweber/companion-ai-os/blob/main/companion/tools.py"
click node_streaming "https://github.com/jacobbweber/companion-ai-os/blob/main/companion/streaming.py"
click node_memory "https://github.com/jacobbweber/companion-ai-os/blob/main/companion/memory_store.py"
click node_project "https://github.com/jacobbweber/companion-ai-os/blob/main/companion/project_graph.py"
click node_calendar "https://github.com/jacobbweber/companion-ai-os/blob/main/companion/calendar_engine.py"
click node_wiki "https://github.com/jacobbweber/companion-ai-os/blob/main/companion/wiki_engine.py"
click node_education "https://github.com/jacobbweber/companion-ai-os/blob/main/companion/education_engine.py"
click node_dag "https://github.com/jacobbweber/companion-ai-os/blob/main/companion/dag_runtime.py"
click node_workflow "https://github.com/jacobbweber/companion-ai-os/blob/main/companion/workflow_graph.py"
click node_routines "https://github.com/jacobbweber/companion-ai-os/blob/main/companion/routines.py"
click node_jobs "https://github.com/jacobbweber/companion-ai-os/blob/main/companion/background_jobs.py"
click node_approvals "https://github.com/jacobbweber/companion-ai-os/blob/main/companion/archive_and_approvals.py"
click node_safety "https://github.com/jacobbweber/companion-ai-os/blob/main/companion/safety.py"
click node_vault "https://github.com/jacobbweber/companion-ai-os/blob/main/companion/vault.py"
click node_mcp "https://github.com/jacobbweber/companion-ai-os/blob/main/companion/mcp_hub.py"

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_webui,node_webserver,node_api,node_cli,node_user toneBlue
class node_agent,node_llm,node_tools,node_streaming toneAmber
class node_memory,node_project toneMint
class node_calendar,node_wiki,node_education toneRose
class node_dag,node_workflow,node_routines,node_jobs,node_approvals,node_safety,node_vault,node_mcp toneIndigo
```

## Components

### User interfaces

- [Web Studio](https://github.com/jacobbweber/companion-ai-os/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Web server](https://github.com/jacobbweber/companion-ai-os/blob/main/surfaces/web_server.py): `surfaces/web_server.py`
- [Web API](https://github.com/jacobbweber/companion-ai-os/blob/main/surfaces/api_extensions.py): `surfaces/api_extensions.py`
- [CLI entry](https://github.com/jacobbweber/companion-ai-os/blob/main/harness.py): `harness.py`

### Assistant runtime

- [Assistant agent](https://github.com/jacobbweber/companion-ai-os/blob/main/companion/agent.py): `companion/agent.py`
- [LLM router](https://github.com/jacobbweber/companion-ai-os/blob/main/companion/llm.py): `companion/llm.py`
- [Tool execution](https://github.com/jacobbweber/companion-ai-os/blob/main/companion/tools.py): `companion/tools.py`
- [Response streaming](https://github.com/jacobbweber/companion-ai-os/blob/main/companion/streaming.py): `companion/streaming.py`

### Memory and projects

- [Memory store](https://github.com/jacobbweber/companion-ai-os/blob/main/companion/memory_store.py): `companion/memory_store.py`
- [Project graph](https://github.com/jacobbweber/companion-ai-os/blob/main/companion/project_graph.py): `companion/project_graph.py`

### Knowledge and planning

- [Unified calendar](https://github.com/jacobbweber/companion-ai-os/blob/main/companion/calendar_engine.py): `companion/calendar_engine.py`
- [Knowledge wiki](https://github.com/jacobbweber/companion-ai-os/blob/main/companion/wiki_engine.py): `companion/wiki_engine.py`
- [Learning engine](https://github.com/jacobbweber/companion-ai-os/blob/main/companion/education_engine.py): `companion/education_engine.py`

### Automation and governance

- [DAG runtime](https://github.com/jacobbweber/companion-ai-os/blob/main/companion/dag_runtime.py): `companion/dag_runtime.py`
- [Workflow graph](https://github.com/jacobbweber/companion-ai-os/blob/main/companion/workflow_graph.py): `companion/workflow_graph.py`
- [Routine manager](https://github.com/jacobbweber/companion-ai-os/blob/main/companion/routines.py): `companion/routines.py`
- [Background jobs](https://github.com/jacobbweber/companion-ai-os/blob/main/companion/background_jobs.py): `companion/background_jobs.py`
- [Approvals and trust](https://github.com/jacobbweber/companion-ai-os/blob/main/companion/archive_and_approvals.py): `companion/archive_and_approvals.py`
- [Safety controls](https://github.com/jacobbweber/companion-ai-os/blob/main/companion/safety.py): `companion/safety.py`
- [Credential vault](https://github.com/jacobbweber/companion-ai-os/blob/main/companion/vault.py): `companion/vault.py`
- [MCP hub](https://github.com/jacobbweber/companion-ai-os/blob/main/companion/mcp_hub.py): `companion/mcp_hub.py`

### Other components

- **User**

## Connections

- User → Web Studio: uses (evidence: `README.md`)
- Web Studio → Web server: API requests
- Web Studio → Web API: calls (evidence: `frontend/src/App.tsx`)
- Web server → Assistant agent: dispatches turns (evidence: `surfaces/web_server.py`)
- Web server → Web API: routes extensions (evidence: `surfaces/web_server.py`)
- CLI entry → Assistant agent: starts assistant (evidence: `harness.py`)
- Assistant agent → LLM router: requests completion (evidence: `companion/agent.py`)
- Assistant agent → Memory store: reads and writes (evidence: `companion/agent.py`)
- Assistant agent → Tool execution: dispatches tools (evidence: `companion/agent.py`)
- Assistant agent → Project graph: uses project context (evidence: `companion/agent.py`)
- Web server → Response streaming: streams responses (evidence: `surfaces/web_server.py`)
- LLM router → Response streaming: uses stream support (evidence: `companion/llm.py`)
- Project graph → Memory store: persists graph state (evidence: `companion/project_graph.py`)
- Unified calendar → Memory store: uses stored state (evidence: `companion/calendar_engine.py`)
- Learning engine → Memory store: stores mastery (evidence: `companion/education_engine.py`)
- Learning engine → Knowledge wiki: curates study notes (evidence: `companion/education_engine.py`)
- Routine manager → Background jobs: manages job routines (evidence: `companion/routines.py`)
- Routine manager → DAG runtime: runs DAG routines (evidence: `companion/routines.py`)
- Routine manager → Approvals and trust: requests approvals (evidence: `companion/routines.py`)
- DAG runtime → Memory store: uses persistent state (evidence: `companion/dag_runtime.py`)
- Workflow graph → Memory store: persists workflow state
- User → CLI entry: uses (evidence: `README.md`)
- Approvals and trust → Memory store: stores approval state (evidence: `companion/archive_and_approvals.py`)
- Safety controls → Assistant agent: guards actions (evidence: `companion/agent.py`)
- Credential vault → Tool execution: injects credentials
- MCP hub → Tool execution: provides integrations
