# enso-team/enso-cli architecture

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

- Interactive diagram: https://gitdiagram.com/enso-team/enso-cli
- Repository: https://github.com/enso-team/enso-cli

## Overview

Enso CLI links local commands to the Enso app’s bridge for vault and Canvas work, including targeting, discovery, context, editing, and layout. A separate local prompt runner manages canvas-bound sessions and can execute through fake or Claude providers. The graph emphasizes documented workflows and relationships visible in the supplied excerpts or README; several command implementations and integrations were not sampled, so uncertain connections are omitted.

Main entry points: [`src/client.ts`](https://github.com/enso-team/enso-cli/blob/main/src/client.ts) (Bridge client), [`src/commands`](https://github.com/enso-team/enso-cli/tree/main/src/commands) (Command handlers), [`src/commands/layout.ts`](https://github.com/enso-team/enso-cli/blob/main/src/commands/layout.ts) (Layout command), [`src/runner/engine.ts`](https://github.com/enso-team/enso-cli/blob/main/src/runner/engine.ts) (Session engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflows"]
  node_commands["Command handlers"]
  node_auth["Pairing<br/>[auth.ts]"]
  node_context["Context and search<br/>[context.ts]"]
  node_vault["Vault operations<br/>[vault.ts]"]
  node_skill["Agent skill install<br/>[skill.ts]"]
end

subgraph group_bridge["Bridge access"]
  node_client["Bridge client<br/>[client.ts]"]
  node_targeting["Target binding<br/>[targeting.ts]"]
  node_discovery["App discovery<br/>[discovery.ts]"]
  node_config["Pairing config<br/>[config.ts]"]
end

subgraph group_canvas["Canvas modeling"]
  node_canvascmd["Canvas commands<br/>[canvas.ts]"]
  node_layoutcmd["Layout command<br/>[layout.ts]"]
  node_nodecmd["Node commands<br/>[node.ts]"]
  node_canvasintent["Intent compiler<br/>[canvas-intent.ts]"]
  node_spec["Canvas specification<br/>[canvas-spec.ts]"]
  node_layout["Layout engine<br/>[layout.ts]"]
  node_linkmodel["Link model<br/>[link-model.ts]"]
  node_markmodel["Mark model<br/>[mark-model.ts]"]
end

subgraph group_runner["Prompt runner"]
  node_runnercmd["Runner commands<br/>[runner.ts]"]
  node_service["Runner service<br/>[service.ts]"]
  node_engine["Session engine<br/>[engine.ts]"]
  node_provider["Provider interface<br/>[provider.ts]"]
  node_claude["Claude provider<br/>[claude.ts]"]
  node_storage[("Session storage<br/>[storage.ts]")]
  node_protocol["Runner protocol<br/>[protocol.ts]"]
  node_socket["Local socket client<br/>[client.ts]"]
end

node_user(("User or agent"))
node_enso["Enso app bridge"]

node_user -->|"runs commands"| node_commands
node_commands -->|"pairs app"| node_auth
node_commands -->|"runs canvas"| node_canvascmd
node_commands -->|"requests context"| node_context
node_commands -->|"runs layout"| node_layoutcmd
node_commands -->|"runs runner"| node_runnercmd
node_auth -->|"links through"| node_client
node_auth -->|"stores pairing"| node_config
node_context -->|"requests data"| node_client
node_vault -.->|"requests vault"| node_client
node_skill -->|"installs skill"| node_commands
node_client -->|"resolves target"| node_targeting
node_client -->|"repairs pairing"| node_discovery
node_client -->|"reads pairing"| node_config
node_client -->|"sends requests"| node_enso
node_canvascmd -->|"sends operations"| node_client
node_canvascmd -->|"compiles apply"| node_canvasintent
node_layoutcmd -->|"sends operations"| node_client
node_layoutcmd -->|"parses input"| node_spec
node_layoutcmd -->|"computes placement"| node_layout
node_nodecmd -->|"sends operations"| node_client
node_layout -->|"creates intent"| node_canvasintent
node_canvasintent -->|"validates links"| node_linkmodel
node_canvasintent -->|"validates marks"| node_markmodel
node_runnercmd -->|"starts service"| node_service
node_runnercmd -->|"calls service"| node_socket
node_service -->|"routes requests"| node_engine
node_engine -->|"executes prompts"| node_provider
node_engine -.->|"persists state"| node_storage
node_claude -->|"implements provider"| node_provider
node_engine -->|"validates requests"| node_protocol

click node_commands "https://github.com/enso-team/enso-cli/tree/main/src/commands"
click node_auth "https://github.com/enso-team/enso-cli/blob/main/src/commands/auth.ts"
click node_context "https://github.com/enso-team/enso-cli/blob/main/src/commands/context.ts"
click node_vault "https://github.com/enso-team/enso-cli/blob/main/src/commands/vault.ts"
click node_skill "https://github.com/enso-team/enso-cli/blob/main/src/commands/skill.ts"
click node_client "https://github.com/enso-team/enso-cli/blob/main/src/client.ts"
click node_targeting "https://github.com/enso-team/enso-cli/blob/main/src/targeting.ts"
click node_discovery "https://github.com/enso-team/enso-cli/blob/main/src/discovery.ts"
click node_config "https://github.com/enso-team/enso-cli/blob/main/src/config.ts"
click node_canvascmd "https://github.com/enso-team/enso-cli/blob/main/src/commands/canvas.ts"
click node_layoutcmd "https://github.com/enso-team/enso-cli/blob/main/src/commands/layout.ts"
click node_nodecmd "https://github.com/enso-team/enso-cli/blob/main/src/commands/node.ts"
click node_canvasintent "https://github.com/enso-team/enso-cli/blob/main/src/canvas-intent.ts"
click node_spec "https://github.com/enso-team/enso-cli/blob/main/src/canvas-spec.ts"
click node_layout "https://github.com/enso-team/enso-cli/blob/main/src/layout.ts"
click node_linkmodel "https://github.com/enso-team/enso-cli/blob/main/src/link-model.ts"
click node_markmodel "https://github.com/enso-team/enso-cli/blob/main/src/mark-model.ts"
click node_runnercmd "https://github.com/enso-team/enso-cli/blob/main/src/commands/runner.ts"
click node_service "https://github.com/enso-team/enso-cli/blob/main/src/runner/service.ts"
click node_engine "https://github.com/enso-team/enso-cli/blob/main/src/runner/engine.ts"
click node_provider "https://github.com/enso-team/enso-cli/blob/main/src/runner/provider.ts"
click node_claude "https://github.com/enso-team/enso-cli/blob/main/src/runner/claude.ts"
click node_storage "https://github.com/enso-team/enso-cli/blob/main/src/runner/storage.ts"
click node_protocol "https://github.com/enso-team/enso-cli/blob/main/src/runner/protocol.ts"
click node_socket "https://github.com/enso-team/enso-cli/blob/main/src/runner/client.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_commands,node_auth,node_context,node_vault,node_skill,node_user toneBlue
class node_client,node_targeting,node_discovery,node_config toneAmber
class node_canvascmd,node_layoutcmd,node_nodecmd,node_canvasintent,node_spec,node_layout,node_linkmodel,node_markmodel toneMint
class node_runnercmd,node_service,node_engine,node_provider,node_claude,node_storage,node_protocol,node_socket toneRose
class node_enso toneIndigo
```

## Components

### CLI workflows

- [Command handlers](https://github.com/enso-team/enso-cli/tree/main/src/commands): `src/commands`
- [Pairing](https://github.com/enso-team/enso-cli/blob/main/src/commands/auth.ts): `src/commands/auth.ts`
- [Context and search](https://github.com/enso-team/enso-cli/blob/main/src/commands/context.ts): `src/commands/context.ts`
- [Vault operations](https://github.com/enso-team/enso-cli/blob/main/src/commands/vault.ts): `src/commands/vault.ts`
- [Agent skill install](https://github.com/enso-team/enso-cli/blob/main/src/commands/skill.ts): `src/commands/skill.ts`

### Bridge access

- [Bridge client](https://github.com/enso-team/enso-cli/blob/main/src/client.ts): `src/client.ts`
- [Target binding](https://github.com/enso-team/enso-cli/blob/main/src/targeting.ts): `src/targeting.ts`
- [App discovery](https://github.com/enso-team/enso-cli/blob/main/src/discovery.ts): `src/discovery.ts`
- [Pairing config](https://github.com/enso-team/enso-cli/blob/main/src/config.ts): `src/config.ts`

### Canvas modeling

- [Canvas commands](https://github.com/enso-team/enso-cli/blob/main/src/commands/canvas.ts): `src/commands/canvas.ts`
- [Layout command](https://github.com/enso-team/enso-cli/blob/main/src/commands/layout.ts): `src/commands/layout.ts`
- [Node commands](https://github.com/enso-team/enso-cli/blob/main/src/commands/node.ts): `src/commands/node.ts`
- [Intent compiler](https://github.com/enso-team/enso-cli/blob/main/src/canvas-intent.ts): `src/canvas-intent.ts`
- [Canvas specification](https://github.com/enso-team/enso-cli/blob/main/src/canvas-spec.ts): `src/canvas-spec.ts`
- [Layout engine](https://github.com/enso-team/enso-cli/blob/main/src/layout.ts): `src/layout.ts`
- [Link model](https://github.com/enso-team/enso-cli/blob/main/src/link-model.ts): `src/link-model.ts`
- [Mark model](https://github.com/enso-team/enso-cli/blob/main/src/mark-model.ts): `src/mark-model.ts`

### Prompt runner

- [Runner commands](https://github.com/enso-team/enso-cli/blob/main/src/commands/runner.ts): `src/commands/runner.ts`
- [Runner service](https://github.com/enso-team/enso-cli/blob/main/src/runner/service.ts): `src/runner/service.ts`
- [Session engine](https://github.com/enso-team/enso-cli/blob/main/src/runner/engine.ts): `src/runner/engine.ts`
- [Provider interface](https://github.com/enso-team/enso-cli/blob/main/src/runner/provider.ts): `src/runner/provider.ts`
- [Claude provider](https://github.com/enso-team/enso-cli/blob/main/src/runner/claude.ts): `src/runner/claude.ts`
- [Session storage](https://github.com/enso-team/enso-cli/blob/main/src/runner/storage.ts): `src/runner/storage.ts`
- [Runner protocol](https://github.com/enso-team/enso-cli/blob/main/src/runner/protocol.ts): `src/runner/protocol.ts`
- [Local socket client](https://github.com/enso-team/enso-cli/blob/main/src/runner/client.ts): `src/runner/client.ts`

### Other components

- **User or agent**
- **Enso app bridge**

## Connections

- User or agent → Command handlers: runs commands
- Command handlers → Pairing: pairs app (evidence: `src/index.ts`)
- Command handlers → Canvas commands: runs canvas (evidence: `src/index.ts`)
- Command handlers → Context and search: requests context (evidence: `src/index.ts`)
- Command handlers → Layout command: runs layout (evidence: `src/index.ts`)
- Command handlers → Runner commands: runs runner (evidence: `src/index.ts`)
- Pairing → Bridge client: links through (evidence: `src/commands/auth.ts`)
- Pairing → Pairing config: stores pairing (evidence: `src/commands/auth.ts`)
- Context and search → Bridge client: requests data (evidence: `src/commands/context.ts`)
- Vault operations → Bridge client: requests vault
- Agent skill install → Command handlers: installs skill
- Bridge client → Target binding: resolves target (evidence: `src/client.ts`)
- Bridge client → App discovery: repairs pairing (evidence: `src/client.ts`)
- Bridge client → Pairing config: reads pairing (evidence: `src/client.ts`)
- Bridge client → Enso app bridge: sends requests
- Canvas commands → Bridge client: sends operations (evidence: `src/commands/canvas.ts`)
- Canvas commands → Intent compiler: compiles apply (evidence: `src/commands/canvas.ts`)
- Layout command → Bridge client: sends operations (evidence: `src/commands/layout.ts`)
- Layout command → Canvas specification: parses input (evidence: `src/commands/layout.ts`)
- Layout command → Layout engine: computes placement (evidence: `src/commands/layout.ts`)
- Node commands → Bridge client: sends operations (evidence: `src/commands/node.ts`)
- Layout engine → Intent compiler: creates intent (evidence: `src/layout.ts`)
- Intent compiler → Link model: validates links (evidence: `src/canvas-intent.ts`)
- Intent compiler → Mark model: validates marks (evidence: `src/canvas-intent.ts`)
- Runner commands → Runner service: starts service (evidence: `src/commands/runner.ts`)
- Runner commands → Local socket client: calls service (evidence: `src/commands/runner.ts`)
- Runner service → Session engine: routes requests (evidence: `src/runner/service.ts`)
- Session engine → Provider interface: executes prompts (evidence: `src/runner/engine.ts`)
- Session engine → Session storage: persists state (evidence: `src/runner/engine.ts`)
- Claude provider → Provider interface: implements provider (evidence: `src/runner/claude.ts`)
- Session engine → Runner protocol: validates requests (evidence: `src/runner/engine.ts`)