# codejunkie99/keel architecture

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

- Interactive diagram: https://gitdiagram.com/codejunkie99/keel
- Repository: https://github.com/codejunkie99/keel

## Overview

Keel is a local-first macOS coding workspace. Users configure providers and a decision mode, compose a task, and run it in a session; for eligible fresh, unpinned tasks, host-prepared routes may be selected by local Laya or optional hosted Jev, then checked by Keel before the chosen coding harness executes. Normal mode skips selection, and external ACP agents retain their own tool loops. The app also exposes workspace, terminal, settings, and session features. The README documents sync and decision-record capabilities; sampled excerpts do not establish all their runtime wiring.

Main entry points: [`crates/engine/src/lib.rs`](https://github.com/codejunkie99/keel/blob/main/crates/engine/src/lib.rs) (Engine), [`crates/engine/src/jev_routing.rs`](https://github.com/codejunkie99/keel/blob/main/crates/engine/src/jev_routing.rs) (Route selection), [`crates/dsh/tools/src/runtime.rs`](https://github.com/codejunkie99/keel/blob/main/crates/dsh/tools/src/runtime.rs) (Tool runtime), [`crates/ui/src/lib.rs`](https://github.com/codejunkie99/keel/blob/main/crates/ui/src/lib.rs) (Workspace UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Workspace app"]
  node_keel["Keel app<br/>[main.rs]"]
  node_ui["Workspace UI<br/>[lib.rs]"]
  node_engine["Engine<br/>[lib.rs]"]
end

subgraph group_routing["Task routing"]
  node_decision_mode["Decision mode<br/>[decision_mode.rs]"]
  node_routing_logic["Route selection<br/>[jev_routing.rs]"]
  node_registry["Harness registry<br/>[registry.rs]"]
  node_laya["Local Laya<br/>[lib.rs]"]
  node_laya_worker["Laya worker<br/>[worker.py]"]
  node_jev["Hosted Jev<br/>[lib.rs]"]
end

subgraph group_execution["Agent execution"]
  node_harness["ACP harnesses<br/>[lib.rs]"]
  node_agent_loop["Embedded agent loop<br/>[agent.rs]"]
  node_tools["Tool runtime<br/>[runtime.rs]"]
  node_filesystem["Filesystem tools<br/>[tools.rs]"]
  node_shell["Shell tools<br/>[tool.rs]"]
end

subgraph group_workspace["Workspace services"]
  node_rpc["RPC transport<br/>[server.rs]"]
  node_workspace_host["Workspace host<br/>[workspace_host.rs]"]
  node_terminal["Terminal service<br/>[terminals.rs]"]
end

subgraph group_state["Sessions and sync"]
  node_session["Event sessions<br/>[session.rs]"]
  node_persistence["Session persistence<br/>[lib.rs]"]
  node_sync["Chat sync<br/>[chat_client.rs]"]
end

node_user(("User"))
node_provider(("Coding provider"))

node_user -->|"uses"| node_ui
node_ui -->|"requests tasks"| node_engine
node_keel -->|"starts"| node_engine
node_engine -->|"checks mode"| node_decision_mode
node_engine -->|"routes eligible tasks"| node_routing_logic
node_routing_logic -->|"prepares candidates"| node_registry
node_routing_logic -.->|"requests choice"| node_laya
node_laya -->|"uses worker"| node_laya_worker
node_routing_logic -.->|"requests choice"| node_jev
node_routing_logic -->|"returns decision"| node_engine
node_engine -->|"checks route"| node_registry
node_engine -->|"dispatches task"| node_harness
node_engine -->|"runs embedded tasks"| node_agent_loop
node_agent_loop -->|"dispatches tools"| node_tools
node_tools -->|"invokes"| node_filesystem
node_tools -->|"invokes"| node_shell
node_engine -->|"manages sessions"| node_session
node_session -->|"persists events"| node_persistence
node_engine -->|"syncs chat"| node_sync
node_engine -->|"serves requests"| node_rpc
node_engine -->|"hosts workspace"| node_workspace_host
node_engine -->|"manages terminals"| node_terminal

click node_keel "https://github.com/codejunkie99/keel/blob/main/apps/keel/src/main.rs"
click node_ui "https://github.com/codejunkie99/keel/blob/main/crates/ui/src/lib.rs"
click node_engine "https://github.com/codejunkie99/keel/blob/main/crates/engine/src/lib.rs"
click node_decision_mode "https://github.com/codejunkie99/keel/blob/main/crates/engine/src/decision_mode.rs"
click node_routing_logic "https://github.com/codejunkie99/keel/blob/main/crates/engine/src/jev_routing.rs"
click node_registry "https://github.com/codejunkie99/keel/blob/main/crates/engine/src/registry.rs"
click node_laya "https://github.com/codejunkie99/keel/blob/main/crates/laya-local/src/lib.rs"
click node_laya_worker "https://github.com/codejunkie99/keel/blob/main/crates/laya-local/worker.py"
click node_jev "https://github.com/codejunkie99/keel/blob/main/crates/jev-core/src/lib.rs"
click node_harness "https://github.com/codejunkie99/keel/blob/main/crates/harness/src/lib.rs"
click node_agent_loop "https://github.com/codejunkie99/keel/blob/main/crates/dsh/agent-loop/src/agent.rs"
click node_tools "https://github.com/codejunkie99/keel/blob/main/crates/dsh/tools/src/runtime.rs"
click node_filesystem "https://github.com/codejunkie99/keel/blob/main/crates/dsh/fs/src/tools.rs"
click node_shell "https://github.com/codejunkie99/keel/blob/main/crates/dsh/shell/src/tool.rs"
click node_session "https://github.com/codejunkie99/keel/blob/main/crates/dsh/session/src/session.rs"
click node_persistence "https://github.com/codejunkie99/keel/blob/main/crates/dsh/session-persistence-jsonl/src/lib.rs"
click node_sync "https://github.com/codejunkie99/keel/blob/main/crates/sync/src/chat_client.rs"
click node_rpc "https://github.com/codejunkie99/keel/blob/main/crates/rpc/src/server.rs"
click node_workspace_host "https://github.com/codejunkie99/keel/blob/main/crates/engine/src/workspace_host.rs"
click node_terminal "https://github.com/codejunkie99/keel/blob/main/crates/engine/src/terminals.rs"

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_keel,node_ui,node_engine,node_user toneBlue
class node_decision_mode,node_routing_logic,node_registry,node_laya,node_laya_worker,node_jev toneAmber
class node_harness,node_agent_loop,node_tools,node_filesystem,node_shell toneMint
class node_rpc,node_workspace_host,node_terminal toneRose
class node_session,node_persistence,node_sync,node_provider toneIndigo
```

## Components

### Workspace app

- [Keel app](https://github.com/codejunkie99/keel/blob/main/apps/keel/src/main.rs): `apps/keel/src/main.rs`
- [Workspace UI](https://github.com/codejunkie99/keel/blob/main/crates/ui/src/lib.rs): `crates/ui/src/lib.rs`
- [Engine](https://github.com/codejunkie99/keel/blob/main/crates/engine/src/lib.rs): `crates/engine/src/lib.rs`

### Task routing

- [Decision mode](https://github.com/codejunkie99/keel/blob/main/crates/engine/src/decision_mode.rs): `crates/engine/src/decision_mode.rs`
- [Route selection](https://github.com/codejunkie99/keel/blob/main/crates/engine/src/jev_routing.rs): `crates/engine/src/jev_routing.rs`
- [Harness registry](https://github.com/codejunkie99/keel/blob/main/crates/engine/src/registry.rs): `crates/engine/src/registry.rs`
- [Local Laya](https://github.com/codejunkie99/keel/blob/main/crates/laya-local/src/lib.rs): `crates/laya-local/src/lib.rs`
- [Laya worker](https://github.com/codejunkie99/keel/blob/main/crates/laya-local/worker.py): `crates/laya-local/worker.py`
- [Hosted Jev](https://github.com/codejunkie99/keel/blob/main/crates/jev-core/src/lib.rs): `crates/jev-core/src/lib.rs`

### Agent execution

- [ACP harnesses](https://github.com/codejunkie99/keel/blob/main/crates/harness/src/lib.rs): `crates/harness/src/lib.rs`
- [Embedded agent loop](https://github.com/codejunkie99/keel/blob/main/crates/dsh/agent-loop/src/agent.rs): `crates/dsh/agent-loop/src/agent.rs`
- [Tool runtime](https://github.com/codejunkie99/keel/blob/main/crates/dsh/tools/src/runtime.rs): `crates/dsh/tools/src/runtime.rs`
- [Filesystem tools](https://github.com/codejunkie99/keel/blob/main/crates/dsh/fs/src/tools.rs): `crates/dsh/fs/src/tools.rs`
- [Shell tools](https://github.com/codejunkie99/keel/blob/main/crates/dsh/shell/src/tool.rs): `crates/dsh/shell/src/tool.rs`

### Workspace services

- [RPC transport](https://github.com/codejunkie99/keel/blob/main/crates/rpc/src/server.rs): `crates/rpc/src/server.rs`
- [Workspace host](https://github.com/codejunkie99/keel/blob/main/crates/engine/src/workspace_host.rs): `crates/engine/src/workspace_host.rs`
- [Terminal service](https://github.com/codejunkie99/keel/blob/main/crates/engine/src/terminals.rs): `crates/engine/src/terminals.rs`

### Sessions and sync

- [Event sessions](https://github.com/codejunkie99/keel/blob/main/crates/dsh/session/src/session.rs): `crates/dsh/session/src/session.rs`
- [Session persistence](https://github.com/codejunkie99/keel/blob/main/crates/dsh/session-persistence-jsonl/src/lib.rs): `crates/dsh/session-persistence-jsonl/src/lib.rs`
- [Chat sync](https://github.com/codejunkie99/keel/blob/main/crates/sync/src/chat_client.rs): `crates/sync/src/chat_client.rs`

### Other components

- **User**
- **Coding provider**

## Connections

- User → Workspace UI: uses
- Workspace UI → Engine: requests tasks
- Keel app → Engine: starts
- Engine → Decision mode: checks mode
- Engine → Route selection: routes eligible tasks
- Route selection → Harness registry: prepares candidates
- Route selection → Local Laya: requests choice
- Local Laya → Laya worker: uses worker
- Route selection → Hosted Jev: requests choice
- Route selection → Engine: returns decision
- Engine → Harness registry: checks route
- Engine → ACP harnesses: dispatches task
- Engine → Embedded agent loop: runs embedded tasks
- Embedded agent loop → Tool runtime: dispatches tools
- Tool runtime → Filesystem tools: invokes
- Tool runtime → Shell tools: invokes
- Engine → Event sessions: manages sessions
- Event sessions → Session persistence: persists events
- Engine → Chat sync: syncs chat
- Engine → RPC transport: serves requests
- Engine → Workspace host: hosts workspace
- Engine → Terminal service: manages terminals