# futuregene/future-os architecture

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

- Interactive diagram: https://gitdiagram.com/futuregene/future-os
- Repository: https://github.com/futuregene/future-os

## Overview

FutureOS is a local-first, multi-surface AI agent: users submit work through desktop, terminal/CLI, mobile, or chat; a shared Rust agent runs model-backed turns, applies configurable tool safety, and persists session history. Desktop adds workspace, artifact, review, and remote-control features; chat adapters bridge external messaging services. The README documents durable long-running loop control and built-in skills as major capabilities. The sampled source confirms desktop send orchestration, session persistence, and mobile timeline synchronization; other subsystem links follow documented behavior and the source tree rather than inspected implementations.

Main entry points: [`agent/src/agent/run_loop.rs`](https://github.com/futuregene/future-os/blob/main/agent/src/agent/run_loop.rs) (Turn execution), [`agent/src/grpc/mod.rs`](https://github.com/futuregene/future-os/blob/main/agent/src/grpc/mod.rs) (Agent service), [`channels/src/bridge/mod.rs`](https://github.com/futuregene/future-os/blob/main/channels/src/bridge/mod.rs) (Chat bridge), [`desktop/src-tauri/src/agent_bridge/mod.rs`](https://github.com/futuregene/future-os/blob/main/desktop/src-tauri/src/agent_bridge/mod.rs) (Desktop backend)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surfaces["User surfaces"]
  node_desktop_ui["Desktop interface<br/>[AgentThread.tsx]"]
  node_cli["CLI and TUI<br/>[run.rs]"]
  node_mobile_client["Mobile client"]
  node_channel_bridge["Chat bridge<br/>[mod.rs]"]
  node_mobile_timeline["Timeline sync<br/>[syncEngine.ts]"]
end

subgraph group_agent["Agent runtime"]
  node_agent_service["Agent service<br/>[mod.rs]"]
  node_run_engine["Turn execution<br/>[run_loop.rs]"]
  node_rpc_commands["Session RPC<br/>[mod.rs]"]
  node_session_store[("Session history<br/>[manager.rs]")]
  node_model_adapters["Model adapters<br/>[mod.rs]"]
end

subgraph group_capabilities["Agent capabilities"]
  node_tool_safety["Tool safety<br/>[mod.rs]"]
  node_skills["Skills<br/>[manager.rs]"]
  node_loop_control["Long-run control"]
  node_browser["Browser tools<br/>[mod.rs]"]
end

subgraph group_desktop["Desktop application"]
  node_desktop_backend["Desktop backend<br/>[mod.rs]"]
  node_desktop_store[("Desktop state<br/>[store.rs]")]
  node_remote_control["Remote control<br/>[mod.rs]"]
  node_desktop_send["Prompt send flow<br/>[sendPipeline.ts]"]
end

subgraph group_connectors["External connections"]
  node_model_provider(("Model providers"))
  node_chat_services(("Chat services"))
  node_phone(("Mobile device"))
end

node_desktop_user(("Desktop user"))
node_terminal_user(("Terminal user"))
node_mobile_user(("Mobile user"))
node_chat_user(("Chat user"))

node_desktop_user -->|"submits prompt"| node_desktop_ui
node_desktop_ui -->|"starts send flow"| node_desktop_send
node_desktop_send -->|"sends prompt"| node_desktop_backend
node_desktop_send -->|"creates run"| node_desktop_store
node_desktop_backend -->|"forwards requests"| node_agent_service
node_terminal_user -->|"runs command"| node_cli
node_cli -->|"calls by gRPC"| node_agent_service
node_mobile_user -->|"submits work"| node_mobile_client
node_mobile_client -->|"requests session"| node_agent_service
node_mobile_timeline -->|"syncs history"| node_session_store
node_chat_user -->|"sends message"| node_channel_bridge
node_channel_bridge -->|"dispatches turn"| node_agent_service
node_agent_service -->|"dispatches RPC"| node_rpc_commands
node_rpc_commands -->|"starts or controls"| node_run_engine
node_run_engine -->|"reads and writes"| node_session_store
node_run_engine -->|"requests completion"| node_model_adapters
node_model_adapters -->|"calls model API"| node_model_provider
node_run_engine -->|"constrains tools"| node_tool_safety
node_run_engine -->|"uses skills"| node_skills
node_run_engine -.->|"supports long runs"| node_loop_control
node_run_engine -.->|"invokes browser tools"| node_browser
node_desktop_backend -->|"persists app state"| node_desktop_store
node_desktop_user -->|"pairs and connects"| node_remote_control
node_remote_control -->|"transfers encrypted data"| node_phone
node_channel_bridge -->|"connects providers"| node_chat_services

click node_desktop_ui "https://github.com/futuregene/future-os/blob/main/desktop/src/features/agent/AgentThread.tsx"
click node_cli "https://github.com/futuregene/future-os/blob/main/cli/src/commands/run.rs"
click node_mobile_client "https://github.com/futuregene/future-os/blob/main/mobile/src/remote/useConversationController.ts"
click node_channel_bridge "https://github.com/futuregene/future-os/blob/main/channels/src/bridge/mod.rs"
click node_agent_service "https://github.com/futuregene/future-os/blob/main/agent/src/grpc/mod.rs"
click node_run_engine "https://github.com/futuregene/future-os/blob/main/agent/src/agent/run_loop.rs"
click node_rpc_commands "https://github.com/futuregene/future-os/blob/main/agent/src/rpc/commands/mod.rs"
click node_session_store "https://github.com/futuregene/future-os/blob/main/agent/src/session/manager.rs"
click node_model_adapters "https://github.com/futuregene/future-os/blob/main/agent/src/llm/adapters/mod.rs"
click node_tool_safety "https://github.com/futuregene/future-os/blob/main/agent/src/sandbox/mod.rs"
click node_skills "https://github.com/futuregene/future-os/blob/main/agent/src/skills/manager.rs"
click node_browser "https://github.com/futuregene/future-os/blob/main/cli/src/browser/mod.rs"
click node_desktop_backend "https://github.com/futuregene/future-os/blob/main/desktop/src-tauri/src/agent_bridge/mod.rs"
click node_desktop_store "https://github.com/futuregene/future-os/blob/main/desktop/src-tauri/src/store.rs"
click node_remote_control "https://github.com/futuregene/future-os/blob/main/desktop/src-tauri/src/remote/mod.rs"
click node_desktop_send "https://github.com/futuregene/future-os/blob/main/desktop/src/features/agent/sendPipeline.ts"
click node_mobile_timeline "https://github.com/futuregene/future-os/blob/main/mobile/src/remote/syncEngine.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_desktop_ui,node_cli,node_mobile_client,node_channel_bridge,node_mobile_timeline,node_desktop_user,node_terminal_user,node_mobile_user,node_chat_user toneBlue
class node_agent_service,node_run_engine,node_rpc_commands,node_session_store,node_model_adapters toneAmber
class node_tool_safety,node_skills,node_loop_control,node_browser toneMint
class node_desktop_backend,node_desktop_store,node_remote_control,node_desktop_send toneRose
class node_model_provider,node_chat_services,node_phone toneIndigo
```

## Components

### User surfaces

- [Desktop interface](https://github.com/futuregene/future-os/blob/main/desktop/src/features/agent/AgentThread.tsx): `desktop/src/features/agent/AgentThread.tsx`
- [CLI and TUI](https://github.com/futuregene/future-os/blob/main/cli/src/commands/run.rs): `cli/src/commands/run.rs`
- [Mobile client](https://github.com/futuregene/future-os/blob/main/mobile/src/remote/useConversationController.ts): `mobile/src/remote/useConversationController.ts`
- [Chat bridge](https://github.com/futuregene/future-os/blob/main/channels/src/bridge/mod.rs): `channels/src/bridge/mod.rs`
- [Timeline sync](https://github.com/futuregene/future-os/blob/main/mobile/src/remote/syncEngine.ts): `mobile/src/remote/syncEngine.ts`

### Agent runtime

- [Agent service](https://github.com/futuregene/future-os/blob/main/agent/src/grpc/mod.rs): `agent/src/grpc/mod.rs`
- [Turn execution](https://github.com/futuregene/future-os/blob/main/agent/src/agent/run_loop.rs): `agent/src/agent/run_loop.rs`
- [Session RPC](https://github.com/futuregene/future-os/blob/main/agent/src/rpc/commands/mod.rs): `agent/src/rpc/commands/mod.rs`
- [Session history](https://github.com/futuregene/future-os/blob/main/agent/src/session/manager.rs): `agent/src/session/manager.rs`
- [Model adapters](https://github.com/futuregene/future-os/blob/main/agent/src/llm/adapters/mod.rs): `agent/src/llm/adapters/mod.rs`

### Agent capabilities

- [Tool safety](https://github.com/futuregene/future-os/blob/main/agent/src/sandbox/mod.rs): `agent/src/sandbox/mod.rs`
- [Skills](https://github.com/futuregene/future-os/blob/main/agent/src/skills/manager.rs): `agent/src/skills/manager.rs`
- **Long-run control**
- [Browser tools](https://github.com/futuregene/future-os/blob/main/cli/src/browser/mod.rs): `cli/src/browser/mod.rs`

### Desktop application

- [Desktop backend](https://github.com/futuregene/future-os/blob/main/desktop/src-tauri/src/agent_bridge/mod.rs): `desktop/src-tauri/src/agent_bridge/mod.rs`
- [Desktop state](https://github.com/futuregene/future-os/blob/main/desktop/src-tauri/src/store.rs): `desktop/src-tauri/src/store.rs`
- [Remote control](https://github.com/futuregene/future-os/blob/main/desktop/src-tauri/src/remote/mod.rs): `desktop/src-tauri/src/remote/mod.rs`
- [Prompt send flow](https://github.com/futuregene/future-os/blob/main/desktop/src/features/agent/sendPipeline.ts): `desktop/src/features/agent/sendPipeline.ts`

### External connections

- **Model providers**
- **Chat services**
- **Mobile device**

### Other components

- **Desktop user**
- **Terminal user**
- **Mobile user**
- **Chat user**

## Connections

- Desktop user → Desktop interface: submits prompt
- Desktop interface → Prompt send flow: starts send flow
- Prompt send flow → Desktop backend: sends prompt
- Prompt send flow → Desktop state: creates run
- Desktop backend → Agent service: forwards requests
- Terminal user → CLI and TUI: runs command
- CLI and TUI → Agent service: calls by gRPC
- Mobile user → Mobile client: submits work
- Mobile client → Agent service: requests session
- Timeline sync → Session history: syncs history
- Chat user → Chat bridge: sends message
- Chat bridge → Agent service: dispatches turn
- Agent service → Session RPC: dispatches RPC
- Session RPC → Turn execution: starts or controls
- Turn execution → Session history: reads and writes
- Turn execution → Model adapters: requests completion
- Model adapters → Model providers: calls model API
- Turn execution → Tool safety: constrains tools
- Turn execution → Skills: uses skills
- Turn execution → Long-run control: supports long runs
- Turn execution → Browser tools: invokes browser tools
- Desktop backend → Desktop state: persists app state
- Desktop user → Remote control: pairs and connects
- Remote control → Mobile device: transfers encrypted data
- Chat bridge → Chat services: connects providers