# hermes-hq/hermes-ide architecture

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

- Interactive diagram: https://gitdiagram.com/hermes-hq/hermes-ide
- Repository: https://github.com/hermes-hq/hermes-ide

## Overview

Hermes IDE is a cross-platform desktop terminal that combines ordinary agent-in-PTY sessions with an optional rendered Claude conversation, project-aware context, command suggestions, and workflow tools. The main path is user → session/workspace UI and state → terminal or agent runtime, with the React frontend calling Rust through Tauri IPC for persistence and project operations. Other documented branches include Git, plugins, fleet sessions, review/land, cost tracking, and notifications. The graph uses README claims and shown source references; unsampled subsystem links are omitted rather than inferred.

Main entry points: [`src/App.tsx`](https://github.com/hermes-hq/hermes-ide/blob/main/src/App.tsx) (App shell), [`src/state/SessionContext.tsx`](https://github.com/hermes-hq/hermes-ide/blob/main/src/state/SessionContext.tsx) (Session workspace), [`src-tauri/src/lib.rs`](https://github.com/hermes-hq/hermes-ide/blob/main/src-tauri/src/lib.rs) (Rust backend), [`src/api/projects.ts`](https://github.com/hermes-hq/hermes-ide/blob/main/src/api/projects.ts) (Project API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Desktop experience"]
  node_app["App shell<br/>[App.tsx]"]
  node_session_state["Session workspace<br/>[SessionContext.tsx]"]
  node_session_api["Session API<br/>[sessions.ts]"]
end

subgraph group_agent["Agent sessions"]
  node_terminal_pool["Terminal pool<br/>[TerminalPool.ts]"]
  node_agent_store[("Agent conversation store")]
  node_session_events[("Session event store")]
  node_session_providers["Session providers"]
  node_agent_status["Agent status<br/>[deriveStatus.ts]"]
end

subgraph group_intelligence["Project intelligence"]
  node_project_context["Project scanning and context<br/>[mod.rs]"]
  node_context_hook["Context assembly UI<br/>[useContextState.ts]"]
  node_project_api["Project API<br/>[projects.ts]"]
  node_suggestions["Command suggestions"]
end

subgraph group_workflow["Workflow tools"]
  node_git["Git integration<br/>[git.ts]"]
  node_plugins["Plugin runtime<br/>[PluginRuntime.ts]"]
  node_fleet["Fleet controls"]
  node_tracking[("Track workflow<br/>[store.ts]")]
  node_review[("Review workflow<br/>[reviewStore.ts]")]
  node_done_when["Done-when checks<br/>[controller.ts]"]
  node_costs["Cost dashboard<br/>[CostDashboard.tsx]"]
  node_attention["Attention center"]
end

subgraph group_backend["Native services"]
  node_native_backend["Rust backend<br/>[lib.rs]"]
  node_pty["PTY sessions<br/>[commands.rs]"]
  node_database[("SQLite persistence<br/>[mod.rs]")]
end

node_user(("User"))

node_user -->|"uses"| node_app
node_app -->|"manages sessions"| node_session_state
node_session_state -->|"loads and saves"| node_session_api
node_session_state -->|"creates terminals"| node_terminal_pool
node_session_state -->|"loads projects"| node_project_api
node_session_api -.->|"invokes IPC"| node_native_backend
node_project_api -.->|"invokes IPC"| node_native_backend
node_native_backend -.->|"manages PTY"| node_pty
node_native_backend -.->|"persists data"| node_database
node_native_backend -.->|"assembles context"| node_project_context
node_context_hook -->|"assembles context"| node_project_api
node_terminal_pool -.->|"suggests commands"| node_suggestions
node_session_state -->|"integrates Git"| node_git
node_app -->|"hosts runtime"| node_plugins
node_session_providers -->|"dispatches events"| node_session_events
node_session_providers -->|"observes sessions"| node_agent_store
node_agent_status -->|"derives from events"| node_session_events
node_app -.->|"offers fleet tools"| node_fleet
node_app -.->|"offers tracking"| node_tracking
node_app -.->|"offers review"| node_review
node_app -->|"starts checks"| node_done_when
node_app -->|"opens dashboard"| node_costs
node_app -->|"hosts inbox"| node_attention

click node_app "https://github.com/hermes-hq/hermes-ide/blob/main/src/App.tsx"
click node_session_state "https://github.com/hermes-hq/hermes-ide/blob/main/src/state/SessionContext.tsx"
click node_session_api "https://github.com/hermes-hq/hermes-ide/blob/main/src/api/sessions.ts"
click node_terminal_pool "https://github.com/hermes-hq/hermes-ide/blob/main/src/terminal/TerminalPool.ts"
click node_agent_store "https://github.com/hermes-hq/hermes-ide/blob/main/src/agent/agentSessionStore.ts"
click node_session_events "https://github.com/hermes-hq/hermes-ide/blob/main/src/agent/contract/sessionEventStore.ts"
click node_session_providers "https://github.com/hermes-hq/hermes-ide/blob/main/src/agent/providers/useSessionProviders.ts"
click node_agent_status "https://github.com/hermes-hq/hermes-ide/blob/main/src/agent/status/deriveStatus.ts"
click node_native_backend "https://github.com/hermes-hq/hermes-ide/blob/main/src-tauri/src/lib.rs"
click node_pty "https://github.com/hermes-hq/hermes-ide/blob/main/src-tauri/src/pty/commands.rs"
click node_database "https://github.com/hermes-hq/hermes-ide/blob/main/src-tauri/src/db/mod.rs"
click node_project_context "https://github.com/hermes-hq/hermes-ide/blob/main/src-tauri/src/project/mod.rs"
click node_context_hook "https://github.com/hermes-hq/hermes-ide/blob/main/src/hooks/useContextState.ts"
click node_project_api "https://github.com/hermes-hq/hermes-ide/blob/main/src/api/projects.ts"
click node_suggestions "https://github.com/hermes-hq/hermes-ide/blob/main/src/terminal/intelligence/suggestionEngine.ts"
click node_git "https://github.com/hermes-hq/hermes-ide/blob/main/src/api/git.ts"
click node_plugins "https://github.com/hermes-hq/hermes-ide/blob/main/src/plugins/PluginRuntime.ts"
click node_fleet "https://github.com/hermes-hq/hermes-ide/blob/main/src/fleet/useFleetControls.ts"
click node_tracking "https://github.com/hermes-hq/hermes-ide/blob/main/src/track/store.ts"
click node_review "https://github.com/hermes-hq/hermes-ide/blob/main/src/review/reviewStore.ts"
click node_done_when "https://github.com/hermes-hq/hermes-ide/blob/main/src/doneWhen/controller.ts"
click node_costs "https://github.com/hermes-hq/hermes-ide/blob/main/src/components/CostDashboard.tsx"
click node_attention "https://github.com/hermes-hq/hermes-ide/blob/main/src/components/AttentionCenter.tsx"

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_app,node_session_state,node_session_api,node_user toneBlue
class node_terminal_pool,node_agent_store,node_session_events,node_session_providers,node_agent_status toneAmber
class node_project_context,node_context_hook,node_project_api,node_suggestions toneMint
class node_git,node_plugins,node_fleet,node_tracking,node_review,node_done_when,node_costs,node_attention toneRose
class node_native_backend,node_pty,node_database toneIndigo
```

## Components

### Desktop experience

- [App shell](https://github.com/hermes-hq/hermes-ide/blob/main/src/App.tsx): `src/App.tsx`
- [Session workspace](https://github.com/hermes-hq/hermes-ide/blob/main/src/state/SessionContext.tsx): `src/state/SessionContext.tsx`
- [Session API](https://github.com/hermes-hq/hermes-ide/blob/main/src/api/sessions.ts): `src/api/sessions.ts`

### Agent sessions

- [Terminal pool](https://github.com/hermes-hq/hermes-ide/blob/main/src/terminal/TerminalPool.ts): `src/terminal/TerminalPool.ts`
- [Agent conversation store](https://github.com/hermes-hq/hermes-ide/blob/main/src/agent/agentSessionStore.ts): `src/agent/agentSessionStore.ts`
- [Session event store](https://github.com/hermes-hq/hermes-ide/blob/main/src/agent/contract/sessionEventStore.ts): `src/agent/contract/sessionEventStore.ts`
- [Session providers](https://github.com/hermes-hq/hermes-ide/blob/main/src/agent/providers/useSessionProviders.ts): `src/agent/providers/useSessionProviders.ts`
- [Agent status](https://github.com/hermes-hq/hermes-ide/blob/main/src/agent/status/deriveStatus.ts): `src/agent/status/deriveStatus.ts`

### Project intelligence

- [Project scanning and context](https://github.com/hermes-hq/hermes-ide/blob/main/src-tauri/src/project/mod.rs): `src-tauri/src/project/mod.rs`
- [Context assembly UI](https://github.com/hermes-hq/hermes-ide/blob/main/src/hooks/useContextState.ts): `src/hooks/useContextState.ts`
- [Project API](https://github.com/hermes-hq/hermes-ide/blob/main/src/api/projects.ts): `src/api/projects.ts`
- [Command suggestions](https://github.com/hermes-hq/hermes-ide/blob/main/src/terminal/intelligence/suggestionEngine.ts): `src/terminal/intelligence/suggestionEngine.ts`

### Workflow tools

- [Git integration](https://github.com/hermes-hq/hermes-ide/blob/main/src/api/git.ts): `src/api/git.ts`
- [Plugin runtime](https://github.com/hermes-hq/hermes-ide/blob/main/src/plugins/PluginRuntime.ts): `src/plugins/PluginRuntime.ts`
- [Fleet controls](https://github.com/hermes-hq/hermes-ide/blob/main/src/fleet/useFleetControls.ts): `src/fleet/useFleetControls.ts`
- [Track workflow](https://github.com/hermes-hq/hermes-ide/blob/main/src/track/store.ts): `src/track/store.ts`
- [Review workflow](https://github.com/hermes-hq/hermes-ide/blob/main/src/review/reviewStore.ts): `src/review/reviewStore.ts`
- [Done-when checks](https://github.com/hermes-hq/hermes-ide/blob/main/src/doneWhen/controller.ts): `src/doneWhen/controller.ts`
- [Cost dashboard](https://github.com/hermes-hq/hermes-ide/blob/main/src/components/CostDashboard.tsx): `src/components/CostDashboard.tsx`
- [Attention center](https://github.com/hermes-hq/hermes-ide/blob/main/src/components/AttentionCenter.tsx): `src/components/AttentionCenter.tsx`

### Native services

- [Rust backend](https://github.com/hermes-hq/hermes-ide/blob/main/src-tauri/src/lib.rs): `src-tauri/src/lib.rs`
- [PTY sessions](https://github.com/hermes-hq/hermes-ide/blob/main/src-tauri/src/pty/commands.rs): `src-tauri/src/pty/commands.rs`
- [SQLite persistence](https://github.com/hermes-hq/hermes-ide/blob/main/src-tauri/src/db/mod.rs): `src-tauri/src/db/mod.rs`

### Other components

- **User**

## Connections

- User → App shell: uses (evidence: `README.md`)
- App shell → Session workspace: manages sessions (evidence: `src/App.tsx`)
- Session workspace → Session API: loads and saves (evidence: `src/state/SessionContext.tsx`)
- Session workspace → Terminal pool: creates terminals (evidence: `src/state/SessionContext.tsx`)
- Session workspace → Project API: loads projects (evidence: `src/state/SessionContext.tsx`)
- Session API → Rust backend: invokes IPC (evidence: `README.md`)
- Project API → Rust backend: invokes IPC (evidence: `README.md`)
- Rust backend → PTY sessions: manages PTY (evidence: `README.md`)
- Rust backend → SQLite persistence: persists data (evidence: `README.md`)
- Rust backend → Project scanning and context: assembles context (evidence: `README.md`)
- Context assembly UI → Project API: assembles context (evidence: `src/hooks/useContextState.ts`)
- Terminal pool → Command suggestions: suggests commands (evidence: `README.md`)
- Session workspace → Git integration: integrates Git (evidence: `src/state/SessionContext.tsx`)
- App shell → Plugin runtime: hosts runtime (evidence: `src/App.tsx`)
- Session providers → Session event store: dispatches events (evidence: `src/agent/providers/useSessionProviders.ts`)
- Session providers → Agent conversation store: observes sessions (evidence: `src/agent/providers/useSessionProviders.ts`)
- Agent status → Session event store: derives from events (evidence: `src/agent/status/deriveStatus.ts`)
- App shell → Fleet controls: offers fleet tools
- App shell → Track workflow: offers tracking (evidence: `src/App.tsx`)
- App shell → Review workflow: offers review
- App shell → Done-when checks: starts checks (evidence: `src/App.tsx`)
- App shell → Cost dashboard: opens dashboard (evidence: `src/App.tsx`)
- App shell → Attention center: hosts inbox (evidence: `src/App.tsx`)
