# artyomsv/quil architecture

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

- Interactive diagram: https://gitdiagram.com/artyomsv/quil
- Repository: https://github.com/artyomsv/quil

## Overview

Quil is a persistent, project-aware terminal multiplexer for coordinating local and remote development sessions, including AI assistants. The main workflow starts at the `quil` CLI, enters the TUI, sends workspace actions over IPC to the daemon, and runs commands in managed panes. MCP exposes terminal control to AI agents. The graph also preserves documented worktree, sandbox, session-resume, and workspace-restoration capabilities. Some feature nodes use their exact enclosing directory because their implementation was not sampled; those links are included only where the README documents the relationship.

Main entry points: [`internal/daemon`](https://github.com/artyomsv/quil/tree/master/internal/daemon) (Daemon services), [`internal/tui`](https://github.com/artyomsv/quil/tree/master/internal/tui) (Terminal UI), [`cmd/quil/main.go`](https://github.com/artyomsv/quil/blob/master/cmd/quil/main.go) (CLI entry), [`internal/daemon/session.go`](https://github.com/artyomsv/quil/blob/master/internal/daemon/session.go) (Workspace sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client experience"]
  node_quil["CLI entry<br/>[main.go]"]
  node_tui["Terminal UI"]
end

subgraph group_runtime["Workspace runtime"]
  node_ipc["IPC transport<br/>[server.go]"]
  node_quild["Daemon entry<br/>[main.go]"]
  node_daemon["Daemon services"]
  node_sessions["Workspace sessions<br/>[session.go]"]
  node_pty["Pane processes<br/>[session.go]"]
end

subgraph group_agents["Agent integration"]
  node_mcp["MCP tools<br/>[mcp_tools_tasks.go]"]
  node_hooks["Agent hooks<br/>[runhook.go]"]
  node_hookevents[("Hook event ledger<br/>[ingest.go]")]
  node_tasks["Delegated tasks<br/>[task.go]"]
end

subgraph group_remote["Remote execution"]
  node_remote["Remote transport"]
  node_remoteinstall["Remote setup<br/>[source.go]"]
end

subgraph group_support["Workspace capabilities"]
  node_state[("Persisted workspace")]
  node_worktrees["Git worktrees"]
  node_sandbox["Command sandbox<br/>[sandbox.go]"]
  node_notifications["Agent notifications"]
  node_plugins["Typed pane plugins"]
end

node_developer(("Developer"))
node_assistant(("AI assistant"))

node_developer -->|"launches"| node_quil
node_quil -->|"starts"| node_tui
node_tui -->|"sends requests"| node_ipc
node_quild -->|"starts"| node_daemon
node_daemon -.->|"serves clients"| node_ipc
node_daemon -->|"manages"| node_sessions
node_sessions -->|"runs panes"| node_pty
node_assistant -->|"invokes tools"| node_mcp
node_mcp -->|"requests tasks"| node_ipc
node_sessions -.->|"restores workspace"| node_state
node_hooks -->|"records events"| node_hookevents
node_tui -->|"requests worktrees"| node_worktrees
node_daemon -.->|"runs isolated panes"| node_sandbox
node_tui -->|"connects hosts"| node_remote
node_quil -.->|"sets up hosts"| node_remoteinstall
node_daemon -.->|"signals attention"| node_notifications
node_daemon -.->|"loads pane types"| node_plugins
node_mcp -->|"delegates tasks"| node_tasks

click node_quil "https://github.com/artyomsv/quil/blob/master/cmd/quil/main.go"
click node_tui "https://github.com/artyomsv/quil/tree/master/internal/tui"
click node_mcp "https://github.com/artyomsv/quil/blob/master/cmd/quil/mcp_tools_tasks.go"
click node_ipc "https://github.com/artyomsv/quil/blob/master/internal/ipc/server.go"
click node_quild "https://github.com/artyomsv/quil/blob/master/cmd/quild/main.go"
click node_daemon "https://github.com/artyomsv/quil/tree/master/internal/daemon"
click node_sessions "https://github.com/artyomsv/quil/blob/master/internal/daemon/session.go"
click node_pty "https://github.com/artyomsv/quil/blob/master/internal/pty/session.go"
click node_state "https://github.com/artyomsv/quil/tree/master/internal/persist"
click node_hooks "https://github.com/artyomsv/quil/blob/master/internal/claudehook/runhook.go"
click node_hookevents "https://github.com/artyomsv/quil/blob/master/internal/hookevents/ingest.go"
click node_worktrees "https://github.com/artyomsv/quil/tree/master/internal/gitworktree"
click node_sandbox "https://github.com/artyomsv/quil/blob/master/internal/sandbox/sandbox.go"
click node_remote "https://github.com/artyomsv/quil/tree/master/internal/transport"
click node_remoteinstall "https://github.com/artyomsv/quil/blob/master/internal/remoteinstall/source.go"
click node_notifications "https://github.com/artyomsv/quil/tree/master/internal/notify"
click node_plugins "https://github.com/artyomsv/quil/tree/master/internal/plugin"
click node_tasks "https://github.com/artyomsv/quil/blob/master/internal/daemon/task.go"

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_quil,node_tui toneBlue
class node_ipc,node_quild,node_daemon,node_sessions,node_pty toneAmber
class node_mcp,node_hooks,node_hookevents,node_tasks toneMint
class node_remote,node_remoteinstall toneRose
class node_state,node_worktrees,node_sandbox,node_notifications,node_plugins,node_developer,node_assistant toneIndigo
```

## Components

### Client experience

- [CLI entry](https://github.com/artyomsv/quil/blob/master/cmd/quil/main.go): `cmd/quil/main.go`
- [Terminal UI](https://github.com/artyomsv/quil/tree/master/internal/tui): `internal/tui`

### Workspace runtime

- [IPC transport](https://github.com/artyomsv/quil/blob/master/internal/ipc/server.go): `internal/ipc/server.go`
- [Daemon entry](https://github.com/artyomsv/quil/blob/master/cmd/quild/main.go): `cmd/quild/main.go`
- [Daemon services](https://github.com/artyomsv/quil/tree/master/internal/daemon): `internal/daemon`
- [Workspace sessions](https://github.com/artyomsv/quil/blob/master/internal/daemon/session.go): `internal/daemon/session.go`
- [Pane processes](https://github.com/artyomsv/quil/blob/master/internal/pty/session.go): `internal/pty/session.go`

### Agent integration

- [MCP tools](https://github.com/artyomsv/quil/blob/master/cmd/quil/mcp_tools_tasks.go): `cmd/quil/mcp_tools_tasks.go`
- [Agent hooks](https://github.com/artyomsv/quil/blob/master/internal/claudehook/runhook.go): `internal/claudehook/runhook.go`
- [Hook event ledger](https://github.com/artyomsv/quil/blob/master/internal/hookevents/ingest.go): `internal/hookevents/ingest.go`
- [Delegated tasks](https://github.com/artyomsv/quil/blob/master/internal/daemon/task.go): `internal/daemon/task.go`

### Remote execution

- [Remote transport](https://github.com/artyomsv/quil/tree/master/internal/transport): `internal/transport`
- [Remote setup](https://github.com/artyomsv/quil/blob/master/internal/remoteinstall/source.go): `internal/remoteinstall/source.go`

### Workspace capabilities

- [Persisted workspace](https://github.com/artyomsv/quil/tree/master/internal/persist): `internal/persist`
- [Git worktrees](https://github.com/artyomsv/quil/tree/master/internal/gitworktree): `internal/gitworktree`
- [Command sandbox](https://github.com/artyomsv/quil/blob/master/internal/sandbox/sandbox.go): `internal/sandbox/sandbox.go`
- [Agent notifications](https://github.com/artyomsv/quil/tree/master/internal/notify): `internal/notify`
- [Typed pane plugins](https://github.com/artyomsv/quil/tree/master/internal/plugin): `internal/plugin`

### Other components

- **Developer**
- **AI assistant**

## Connections

- Developer → CLI entry: launches (evidence: `README.md`)
- CLI entry → Terminal UI: starts (evidence: `cmd/quil/main.go`)
- Terminal UI → IPC transport: sends requests (evidence: `internal/tui/router.go`)
- Daemon entry → Daemon services: starts (evidence: `cmd/quild/main.go`)
- Daemon services → IPC transport: serves clients
- Daemon services → Workspace sessions: manages (evidence: `internal/daemon/session.go`)
- Workspace sessions → Pane processes: runs panes (evidence: `internal/daemon/session.go`)
- AI assistant → MCP tools: invokes tools (evidence: `README.md`)
- MCP tools → IPC transport: requests tasks (evidence: `cmd/quil/mcp_tools_tasks.go`)
- Workspace sessions → Persisted workspace: restores workspace
- Agent hooks → Hook event ledger: records events (evidence: `internal/claudehook/runhook.go`)
- Terminal UI → Git worktrees: requests worktrees (evidence: `internal/tui/worktree_client.go`)
- Daemon services → Command sandbox: runs isolated panes
- Terminal UI → Remote transport: connects hosts (evidence: `README.md`)
- CLI entry → Remote setup: sets up hosts
- Daemon services → Agent notifications: signals attention
- Daemon services → Typed pane plugins: loads pane types
- MCP tools → Delegated tasks: delegates tasks (evidence: `cmd/quil/mcp_tools_tasks.go`)
