# henomis/cicoria architecture

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

- Interactive diagram: https://gitdiagram.com/henomis/cicoria
- Repository: https://github.com/henomis/cicoria

## Overview

Cicoria is an interactive terminal workspace for supervising multiple coding-agent sessions, not an agent orchestrator. The main flow is user → CLI/workspace → session → agent process in a terminal; users inspect changes and status, send or queue messages, and persist workspace history. Separate branches provide backlog cards, timelines, worktrees, and an optional phone/browser cockpit. The excerpts show the workspace coordinating several layers; some capability links are documented by the README because their implementation was not sampled.

Main entry points: [`internal/app/app.go`](https://github.com/henomis/cicoria/blob/main/internal/app/app.go) (Workspace model), [`internal/session/session.go`](https://github.com/henomis/cicoria/blob/main/internal/session/session.go) (Session runtime), [`internal/ipc/ipc.go`](https://github.com/henomis/cicoria/blob/main/internal/ipc/ipc.go) (Hook IPC), [`internal/git/git.go`](https://github.com/henomis/cicoria/blob/main/internal/git/git.go) (Git operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and workspace"]
  node_cli["CLI entry<br/>[main.go]"]
  node_workspace["Workspace model<br/>[app.go]"]
  node_config["Configuration<br/>[config.go]"]
  node_panels["Terminal workspace<br/>[view.go]"]
end

subgraph group_sessions["Agent sessions"]
  node_session["Session runtime<br/>[session.go]"]
  node_claude["Claude adapter<br/>[claude.go]"]
  node_copilot["Copilot adapter<br/>[copilot.go]"]
  node_codex["Codex adapter<br/>[codex.go]"]
  node_generic["Generic adapter<br/>[generic.go]"]
  node_terminal["PTY terminal<br/>[term.go]"]
  node_hooks["Hook IPC<br/>[ipc.go]"]
end

subgraph group_review["Review and planning"]
  node_git["Git operations<br/>[git.go]"]
  node_reviewer["Diff review<br/>[fullview.go]"]
  node_queue["Message queue<br/>[queue.go]"]
  node_board["Backlog board<br/>[board.go]"]
  node_worktrees["Worktree sessions<br/>[commands.go]"]
  node_timeline["Activity timeline<br/>[timeline.go]"]
  node_eventlog["Timeline log<br/>[timeline_log.go]"]
end

subgraph group_state["Workspace state"]
  node_store[("Session storage<br/>[store.go]")]
  node_ledger[("Event history<br/>[ledger.go]")]
end

subgraph group_cockpit["Web cockpit"]
  node_webcontrol["Cockpit control<br/>[web.go]"]
  node_webserver["Cockpit server<br/>[web.go]"]
  node_webpage["Cockpit page<br/>[app.js]"]
end

node_user(("User"))

node_user -->|"opens workspace"| node_cli
node_cli -->|"loads settings"| node_config
node_cli -->|"starts"| node_workspace
node_workspace -->|"manages sessions"| node_session
node_workspace -->|"renders workspace"| node_panels
node_workspace -->|"uses settings"| node_config
node_workspace -->|"listens for events"| node_hooks
node_session -->|"starts agent command"| node_terminal
node_session -.->|"launches adapter"| node_claude
node_session -.->|"launches adapter"| node_copilot
node_session -.->|"launches adapter"| node_codex
node_session -.->|"launches adapter"| node_generic
node_claude -->|"reports hook events"| node_hooks
node_copilot -->|"reports hook events"| node_hooks
node_codex -.->|"reports hook events"| node_hooks
node_hooks -->|"forwards events"| node_workspace
node_workspace -->|"reads repository state"| node_git
node_reviewer -.->|"gets diffs"| node_git
node_workspace -.->|"routes queued messages"| node_queue
node_board -.->|"starts card session"| node_session
node_worktrees -->|"creates worktrees"| node_git
node_timeline -->|"shows activity log"| node_eventlog
node_workspace -.->|"remembers sessions"| node_store
node_workspace -.->|"records activity"| node_ledger
node_workspace -->|"controls sharing"| node_webcontrol
node_webcontrol -->|"publishes cockpit"| node_webserver
node_webpage -.->|"receives snapshots"| node_webserver
node_webserver -->|"serves change diffs"| node_git
node_user -.->|"reviews changes"| node_reviewer
node_user -.->|"writes backlog cards"| node_board
node_user -.->|"inspects activity"| node_timeline

click node_cli "https://github.com/henomis/cicoria/blob/main/main.go"
click node_workspace "https://github.com/henomis/cicoria/blob/main/internal/app/app.go"
click node_config "https://github.com/henomis/cicoria/blob/main/internal/config/config.go"
click node_panels "https://github.com/henomis/cicoria/blob/main/internal/app/view.go"
click node_session "https://github.com/henomis/cicoria/blob/main/internal/session/session.go"
click node_claude "https://github.com/henomis/cicoria/blob/main/internal/agent/claude.go"
click node_copilot "https://github.com/henomis/cicoria/blob/main/internal/agent/copilot.go"
click node_codex "https://github.com/henomis/cicoria/blob/main/internal/agent/codex.go"
click node_generic "https://github.com/henomis/cicoria/blob/main/internal/agent/generic.go"
click node_terminal "https://github.com/henomis/cicoria/blob/main/internal/term/term.go"
click node_hooks "https://github.com/henomis/cicoria/blob/main/internal/ipc/ipc.go"
click node_git "https://github.com/henomis/cicoria/blob/main/internal/git/git.go"
click node_reviewer "https://github.com/henomis/cicoria/blob/main/internal/app/fullview.go"
click node_queue "https://github.com/henomis/cicoria/blob/main/internal/app/queue.go"
click node_board "https://github.com/henomis/cicoria/blob/main/internal/app/board.go"
click node_worktrees "https://github.com/henomis/cicoria/blob/main/internal/app/commands.go"
click node_timeline "https://github.com/henomis/cicoria/blob/main/internal/app/timeline.go"
click node_eventlog "https://github.com/henomis/cicoria/blob/main/internal/app/timeline_log.go"
click node_store "https://github.com/henomis/cicoria/blob/main/internal/session/store.go"
click node_ledger "https://github.com/henomis/cicoria/blob/main/internal/session/ledger.go"
click node_webcontrol "https://github.com/henomis/cicoria/blob/main/internal/app/web.go"
click node_webserver "https://github.com/henomis/cicoria/blob/main/internal/web/web.go"
click node_webpage "https://github.com/henomis/cicoria/blob/main/internal/web/page/app.js"

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_cli,node_workspace,node_config,node_panels,node_user toneBlue
class node_session,node_claude,node_copilot,node_codex,node_generic,node_terminal,node_hooks toneAmber
class node_git,node_reviewer,node_queue,node_board,node_worktrees,node_timeline,node_eventlog toneMint
class node_store,node_ledger toneRose
class node_webcontrol,node_webserver,node_webpage toneIndigo
```

## Components

### Entry and workspace

- [CLI entry](https://github.com/henomis/cicoria/blob/main/main.go): `main.go`
- [Workspace model](https://github.com/henomis/cicoria/blob/main/internal/app/app.go): `internal/app/app.go`
- [Configuration](https://github.com/henomis/cicoria/blob/main/internal/config/config.go): `internal/config/config.go`
- [Terminal workspace](https://github.com/henomis/cicoria/blob/main/internal/app/view.go): `internal/app/view.go`

### Agent sessions

- [Session runtime](https://github.com/henomis/cicoria/blob/main/internal/session/session.go): `internal/session/session.go`
- [Claude adapter](https://github.com/henomis/cicoria/blob/main/internal/agent/claude.go): `internal/agent/claude.go`
- [Copilot adapter](https://github.com/henomis/cicoria/blob/main/internal/agent/copilot.go): `internal/agent/copilot.go`
- [Codex adapter](https://github.com/henomis/cicoria/blob/main/internal/agent/codex.go): `internal/agent/codex.go`
- [Generic adapter](https://github.com/henomis/cicoria/blob/main/internal/agent/generic.go): `internal/agent/generic.go`
- [PTY terminal](https://github.com/henomis/cicoria/blob/main/internal/term/term.go): `internal/term/term.go`
- [Hook IPC](https://github.com/henomis/cicoria/blob/main/internal/ipc/ipc.go): `internal/ipc/ipc.go`

### Review and planning

- [Git operations](https://github.com/henomis/cicoria/blob/main/internal/git/git.go): `internal/git/git.go`
- [Diff review](https://github.com/henomis/cicoria/blob/main/internal/app/fullview.go): `internal/app/fullview.go`
- [Message queue](https://github.com/henomis/cicoria/blob/main/internal/app/queue.go): `internal/app/queue.go`
- [Backlog board](https://github.com/henomis/cicoria/blob/main/internal/app/board.go): `internal/app/board.go`
- [Worktree sessions](https://github.com/henomis/cicoria/blob/main/internal/app/commands.go): `internal/app/commands.go`
- [Activity timeline](https://github.com/henomis/cicoria/blob/main/internal/app/timeline.go): `internal/app/timeline.go`
- [Timeline log](https://github.com/henomis/cicoria/blob/main/internal/app/timeline_log.go): `internal/app/timeline_log.go`

### Workspace state

- [Session storage](https://github.com/henomis/cicoria/blob/main/internal/session/store.go): `internal/session/store.go`
- [Event history](https://github.com/henomis/cicoria/blob/main/internal/session/ledger.go): `internal/session/ledger.go`

### Web cockpit

- [Cockpit control](https://github.com/henomis/cicoria/blob/main/internal/app/web.go): `internal/app/web.go`
- [Cockpit server](https://github.com/henomis/cicoria/blob/main/internal/web/web.go): `internal/web/web.go`
- [Cockpit page](https://github.com/henomis/cicoria/blob/main/internal/web/page/app.js): `internal/web/page/app.js`

### Other components

- **User**

## Connections

- User → CLI entry: opens workspace
- CLI entry → Configuration: loads settings (evidence: `main.go`)
- CLI entry → Workspace model: starts (evidence: `main.go`)
- Workspace model → Session runtime: manages sessions (evidence: `internal/app/app.go`)
- Workspace model → Terminal workspace: renders workspace (evidence: `internal/app/app.go`)
- Workspace model → Configuration: uses settings (evidence: `internal/app/app.go`)
- Workspace model → Hook IPC: listens for events (evidence: `internal/app/app.go`)
- Session runtime → PTY terminal: starts agent command (evidence: `internal/session/session.go`)
- Session runtime → Claude adapter: launches adapter
- Session runtime → Copilot adapter: launches adapter
- Session runtime → Codex adapter: launches adapter
- Session runtime → Generic adapter: launches adapter
- Claude adapter → Hook IPC: reports hook events (evidence: `internal/agent/claude.go`)
- Copilot adapter → Hook IPC: reports hook events (evidence: `internal/agent/copilot.go`)
- Codex adapter → Hook IPC: reports hook events
- Hook IPC → Workspace model: forwards events
- Workspace model → Git operations: reads repository state (evidence: `internal/app/app.go`)
- Diff review → Git operations: gets diffs
- Workspace model → Message queue: routes queued messages
- Backlog board → Session runtime: starts card session
- Worktree sessions → Git operations: creates worktrees (evidence: `internal/app/commands.go`)
- Activity timeline → Timeline log: shows activity log
- Workspace model → Session storage: remembers sessions
- Workspace model → Event history: records activity
- Workspace model → Cockpit control: controls sharing (evidence: `internal/app/app.go`)
- Cockpit control → Cockpit server: publishes cockpit (evidence: `internal/app/web.go`)
- Cockpit page → Cockpit server: receives snapshots
- Cockpit server → Git operations: serves change diffs (evidence: `internal/web/web.go`)
- User → Diff review: reviews changes
- User → Backlog board: writes backlog cards
- User → Activity timeline: inspects activity
