# cankalsoftware/ecc architecture

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

- Interactive diagram: https://gitdiagram.com/cankalsoftware/ecc
- Repository: https://github.com/cankalsoftware/ecc

## Overview

ECC is a harness-native agent operating system: it installs agent skills and hooks into supported coding harnesses, and includes a Rust session-orchestration CLI for starting and monitoring agent work. A typical setup begins with a user invoking guided installation; during operation, the ECC CLI manages sessions and persists state, with messaging, worktree support, and a terminal dashboard as distinct capabilities. The tree and excerpts support the named subsystems, but do not establish all their runtime wiring, so uncertain connections are omitted.

Main entry points: [`ecc2/src/main.rs`](https://github.com/cankalsoftware/ecc/blob/main/ecc2/src/main.rs) (ECC2 CLI), [`scripts/install-guided.js`](https://github.com/cankalsoftware/ecc/blob/main/scripts/install-guided.js) (Guided Setup), [`scripts/lib/install-targets/registry.js`](https://github.com/cankalsoftware/ecc/blob/main/scripts/lib/install-targets/registry.js) (Harness Targets), [`ecc2/src/session/manager.rs`](https://github.com/cankalsoftware/ecc/blob/main/ecc2/src/session/manager.rs) (Session Manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_install["Setup and Install"]
  node_guided_setup["Guided Setup<br/>[install-guided.js]"]
  node_install_plan["Install Planning<br/>[install-plan.js]"]
  node_install_apply["Install Apply<br/>[install-apply.js]"]
  node_install_targets["Harness Targets<br/>[registry.js]"]
end

subgraph group_harness["Harness Resources"]
  node_skills["Agent Skills"]
  node_hooks["Agent Hooks"]
end

subgraph group_sessions["Session Orchestration"]
  node_ecc_cli["ECC2 CLI<br/>[main.rs]"]
  node_configuration["Configuration<br/>[mod.rs]"]
  node_session_manager["Session Manager<br/>[manager.rs]"]
  node_session_runtime["Session Runtime<br/>[runtime.rs]"]
  node_state_store[("Session State<br/>[store.rs]")]
  node_communications["Agent Messaging<br/>[mod.rs]"]
end

subgraph group_operations["Operations and Visibility"]
  node_worktrees["Git Worktrees<br/>[mod.rs]"]
  node_dashboard["Terminal Dashboard<br/>[app.rs]"]
  node_observability["Tool Observability<br/>[mod.rs]"]
  node_notifications["Notifications<br/>[notifications.rs]"]
end

subgraph group_llm["LLM Support"]
  node_llm_cli["LLM CLI<br/>[selector.py]"]
  node_llm_providers["Model Providers<br/>[resolver.py]"]
end

node_user(("User"))
node_harnesses{{"Coding Harnesses"}}
node_agent_process(("Agent Process"))

node_user -->|"invokes setup"| node_guided_setup
node_guided_setup -->|"creates plan"| node_install_plan
node_guided_setup -->|"applies setup"| node_install_apply
node_install_apply -->|"selects targets"| node_install_targets
node_install_targets -->|"installs resources"| node_skills
node_install_targets -->|"installs hooks"| node_hooks
node_harnesses -->|"loads skills"| node_skills
node_harnesses -->|"runs hooks"| node_hooks
node_user -->|"runs commands"| node_ecc_cli
node_ecc_cli -->|"loads config"| node_configuration
node_ecc_cli -->|"manages sessions"| node_session_manager
node_ecc_cli -->|"launches dashboard"| node_dashboard
node_session_manager -->|"persists state"| node_state_store
node_communications -->|"stores messages"| node_state_store
node_session_manager -->|"spawns sessions"| node_agent_process
node_agent_process -.->|"uses worktree"| node_worktrees
node_ecc_cli -->|"records tool activity"| node_observability
node_dashboard -->|"reads session state"| node_state_store
node_user -->|"requests model task"| node_llm_cli
node_llm_cli -->|"selects provider"| node_llm_providers

click node_guided_setup "https://github.com/cankalsoftware/ecc/blob/main/scripts/install-guided.js"
click node_install_plan "https://github.com/cankalsoftware/ecc/blob/main/scripts/install-plan.js"
click node_install_apply "https://github.com/cankalsoftware/ecc/blob/main/scripts/install-apply.js"
click node_install_targets "https://github.com/cankalsoftware/ecc/blob/main/scripts/lib/install-targets/registry.js"
click node_skills "https://github.com/cankalsoftware/ecc/tree/main/skills"
click node_hooks "https://github.com/cankalsoftware/ecc/tree/main/scripts/hooks"
click node_ecc_cli "https://github.com/cankalsoftware/ecc/blob/main/ecc2/src/main.rs"
click node_configuration "https://github.com/cankalsoftware/ecc/blob/main/ecc2/src/config/mod.rs"
click node_session_manager "https://github.com/cankalsoftware/ecc/blob/main/ecc2/src/session/manager.rs"
click node_session_runtime "https://github.com/cankalsoftware/ecc/blob/main/ecc2/src/session/runtime.rs"
click node_state_store "https://github.com/cankalsoftware/ecc/blob/main/ecc2/src/session/store.rs"
click node_communications "https://github.com/cankalsoftware/ecc/blob/main/ecc2/src/comms/mod.rs"
click node_worktrees "https://github.com/cankalsoftware/ecc/blob/main/ecc2/src/worktree/mod.rs"
click node_dashboard "https://github.com/cankalsoftware/ecc/blob/main/ecc2/src/tui/app.rs"
click node_observability "https://github.com/cankalsoftware/ecc/blob/main/ecc2/src/observability/mod.rs"
click node_notifications "https://github.com/cankalsoftware/ecc/blob/main/ecc2/src/notifications.rs"
click node_llm_cli "https://github.com/cankalsoftware/ecc/blob/main/src/llm/cli/selector.py"
click node_llm_providers "https://github.com/cankalsoftware/ecc/blob/main/src/llm/providers/resolver.py"

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_guided_setup,node_install_plan,node_install_apply,node_install_targets,node_user toneBlue
class node_skills,node_hooks toneAmber
class node_ecc_cli,node_configuration,node_session_manager,node_session_runtime,node_state_store,node_communications toneMint
class node_worktrees,node_dashboard,node_observability,node_notifications toneRose
class node_llm_cli,node_llm_providers,node_harnesses,node_agent_process toneIndigo
```

## Components

### Setup and Install

- [Guided Setup](https://github.com/cankalsoftware/ecc/blob/main/scripts/install-guided.js): `scripts/install-guided.js`
- [Install Planning](https://github.com/cankalsoftware/ecc/blob/main/scripts/install-plan.js): `scripts/install-plan.js`
- [Install Apply](https://github.com/cankalsoftware/ecc/blob/main/scripts/install-apply.js): `scripts/install-apply.js`
- [Harness Targets](https://github.com/cankalsoftware/ecc/blob/main/scripts/lib/install-targets/registry.js): `scripts/lib/install-targets/registry.js`

### Harness Resources

- [Agent Skills](https://github.com/cankalsoftware/ecc/tree/main/skills): `skills`
- [Agent Hooks](https://github.com/cankalsoftware/ecc/tree/main/scripts/hooks): `scripts/hooks`

### Session Orchestration

- [ECC2 CLI](https://github.com/cankalsoftware/ecc/blob/main/ecc2/src/main.rs): `ecc2/src/main.rs`
- [Configuration](https://github.com/cankalsoftware/ecc/blob/main/ecc2/src/config/mod.rs): `ecc2/src/config/mod.rs`
- [Session Manager](https://github.com/cankalsoftware/ecc/blob/main/ecc2/src/session/manager.rs): `ecc2/src/session/manager.rs`
- [Session Runtime](https://github.com/cankalsoftware/ecc/blob/main/ecc2/src/session/runtime.rs): `ecc2/src/session/runtime.rs`
- [Session State](https://github.com/cankalsoftware/ecc/blob/main/ecc2/src/session/store.rs): `ecc2/src/session/store.rs`
- [Agent Messaging](https://github.com/cankalsoftware/ecc/blob/main/ecc2/src/comms/mod.rs): `ecc2/src/comms/mod.rs`

### Operations and Visibility

- [Git Worktrees](https://github.com/cankalsoftware/ecc/blob/main/ecc2/src/worktree/mod.rs): `ecc2/src/worktree/mod.rs`
- [Terminal Dashboard](https://github.com/cankalsoftware/ecc/blob/main/ecc2/src/tui/app.rs): `ecc2/src/tui/app.rs`
- [Tool Observability](https://github.com/cankalsoftware/ecc/blob/main/ecc2/src/observability/mod.rs): `ecc2/src/observability/mod.rs`
- [Notifications](https://github.com/cankalsoftware/ecc/blob/main/ecc2/src/notifications.rs): `ecc2/src/notifications.rs`

### LLM Support

- [LLM CLI](https://github.com/cankalsoftware/ecc/blob/main/src/llm/cli/selector.py): `src/llm/cli/selector.py`
- [Model Providers](https://github.com/cankalsoftware/ecc/blob/main/src/llm/providers/resolver.py): `src/llm/providers/resolver.py`

### Other components

- **User**
- **Coding Harnesses**
- **Agent Process**

## Connections

- User → Guided Setup: invokes setup
- Guided Setup → Install Planning: creates plan
- Guided Setup → Install Apply: applies setup
- Install Apply → Harness Targets: selects targets
- Harness Targets → Agent Skills: installs resources
- Harness Targets → Agent Hooks: installs hooks
- Coding Harnesses → Agent Skills: loads skills
- Coding Harnesses → Agent Hooks: runs hooks
- User → ECC2 CLI: runs commands
- ECC2 CLI → Configuration: loads config
- ECC2 CLI → Session Manager: manages sessions
- ECC2 CLI → Terminal Dashboard: launches dashboard
- Session Manager → Session State: persists state
- Agent Messaging → Session State: stores messages
- Session Manager → Agent Process: spawns sessions
- Agent Process → Git Worktrees: uses worktree
- ECC2 CLI → Tool Observability: records tool activity
- Terminal Dashboard → Session State: reads session state
- User → LLM CLI: requests model task
- LLM CLI → Model Providers: selects provider