# kkkkhazix/agent-autoloop architecture

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

- Interactive diagram: https://gitdiagram.com/kkkkhazix/agent-autoloop
- Repository: https://github.com/kkkkhazix/agent-autoloop

## Overview

Agent Autoloop is a local automation hub that routes scheduled or external events through user-defined rules to command-line agents, then delivers approval cards and resumes work after a response. Its core stages are event intake, rule-based scheduling and dispatch, agent execution, receipt processing, and human approval; the hub also maintains an event-sourced state view. The README documents event, agent, channel, and delivery plugin families. Some plugin wiring and subsystems were not sampled, so those relationships are cited to the README rather than treated as inspected implementation details.

Main entry points: [`protocol/client.ts`](https://github.com/kkkkhazix/agent-autoloop/blob/main/protocol/client.ts) (HTTP client), [`host/channels.ts`](https://github.com/kkkkhazix/agent-autoloop/blob/main/host/channels.ts) (Channel dispatch), [`host/runtime.ts`](https://github.com/kkkkhazix/agent-autoloop/blob/main/host/runtime.ts) (Hub runtime), [`kernel/evolve.ts`](https://github.com/kkkkhazix/agent-autoloop/blob/main/kernel/evolve.ts) (Fact projections)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Operator interface"]
  node_cli["CLI<br/>[main.ts]"]
end

subgraph group_hub["Hub runtime"]
  node_server["HTTP hub<br/>[server.ts]"]
  node_runtime["Hub runtime<br/>[runtime.ts]"]
  node_protocol["HTTP client<br/>[client.ts]"]
end

subgraph group_kernel["Decision kernel"]
  node_rules["Rule parsing<br/>[rules.ts]"]
  node_validate["Input validation<br/>[validate.ts]"]
  node_decide["Event decisions<br/>[decide.ts]"]
  node_query["State queries<br/>[query.ts]"]
  node_projection[("Fact projections<br/>[evolve.ts]")]
end

subgraph group_work["Agent execution"]
  node_worker["Worker loop<br/>[worker.ts]"]
  node_agents["Agent adapters<br/>[agents.ts]"]
end

subgraph group_plugins["Pluggable integrations"]
  node_agentplugins["Agent plugins"]
  node_sources["Event sources<br/>[source.ts]"]
  node_channels["Channel dispatch<br/>[channels.ts]"]
  node_desktop["Desktop channel<br/>[channel.ts]"]
  node_feishu["Feishu channel<br/>[channel.ts]"]
  node_webhook["Webhook channels<br/>[channel.ts]"]
  node_delivery["PR delivery<br/>[delivery.ts]"]
end

node_operator(("Operator"))
node_events(("Event systems"))
node_agentprogram(("CLI agents"))
node_person(("Approval recipient"))
node_sqlite[("SQLite")]

node_operator -->|"runs commands"| node_cli
node_cli -->|"calls hub"| node_protocol
node_cli -->|"parses rules"| node_rules
node_server -->|"delegates requests"| node_runtime
node_runtime -->|"decides actions"| node_decide
node_runtime -->|"reads state"| node_query
node_runtime -->|"persists facts"| node_projection
node_decide -->|"validates events"| node_validate
node_decide -->|"records facts"| node_projection
node_query -->|"reads projections"| node_projection
node_projection -->|"stores log"| node_sqlite
node_worker -->|"claims work"| node_protocol
node_worker -->|"selects adapter"| node_agents
node_worker -->|"checks receipt"| node_validate
node_agents -->|"loads plugin"| node_agentplugins
node_agentplugins -.->|"launches process"| node_agentprogram
node_events -.->|"emits events"| node_sources
node_sources -.->|"submits events"| node_protocol
node_channels -->|"fetches cards"| node_protocol
node_channels -.->|"loads channel"| node_desktop
node_channels -.->|"loads channel"| node_feishu
node_channels -.->|"loads channel"| node_webhook
node_desktop -.->|"delivers cards"| node_person
node_feishu -.->|"delivers cards"| node_person
node_webhook -.->|"delivers cards"| node_person
node_person -.->|"submits answer"| node_protocol
node_events -.->|"triggers delivery"| node_delivery

click node_cli "https://github.com/kkkkhazix/agent-autoloop/blob/main/cli/main.ts"
click node_server "https://github.com/kkkkhazix/agent-autoloop/blob/main/host/server.ts"
click node_runtime "https://github.com/kkkkhazix/agent-autoloop/blob/main/host/runtime.ts"
click node_protocol "https://github.com/kkkkhazix/agent-autoloop/blob/main/protocol/client.ts"
click node_rules "https://github.com/kkkkhazix/agent-autoloop/blob/main/protocol/rules.ts"
click node_validate "https://github.com/kkkkhazix/agent-autoloop/blob/main/protocol/validate.ts"
click node_decide "https://github.com/kkkkhazix/agent-autoloop/blob/main/kernel/decide.ts"
click node_query "https://github.com/kkkkhazix/agent-autoloop/blob/main/kernel/query.ts"
click node_projection "https://github.com/kkkkhazix/agent-autoloop/blob/main/kernel/evolve.ts"
click node_worker "https://github.com/kkkkhazix/agent-autoloop/blob/main/worker/worker.ts"
click node_agents "https://github.com/kkkkhazix/agent-autoloop/blob/main/worker/agents.ts"
click node_agentplugins "https://github.com/kkkkhazix/agent-autoloop/tree/main/plugins"
click node_sources "https://github.com/kkkkhazix/agent-autoloop/blob/main/plugins/github/source.ts"
click node_channels "https://github.com/kkkkhazix/agent-autoloop/blob/main/host/channels.ts"
click node_desktop "https://github.com/kkkkhazix/agent-autoloop/blob/main/plugins/desktop/channel.ts"
click node_feishu "https://github.com/kkkkhazix/agent-autoloop/blob/main/plugins/feishu/channel.ts"
click node_webhook "https://github.com/kkkkhazix/agent-autoloop/blob/main/plugins/webhook/channel.ts"
click node_delivery "https://github.com/kkkkhazix/agent-autoloop/blob/main/plugins/delivery/delivery.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_cli toneBlue
class node_server,node_runtime,node_protocol,node_sqlite toneAmber
class node_rules,node_validate,node_decide,node_query,node_projection toneMint
class node_worker,node_agents toneRose
class node_agentplugins,node_sources,node_channels,node_desktop,node_feishu,node_webhook,node_delivery,node_operator,node_events,node_agentprogram,node_person toneIndigo
```

## Components

### Operator interface

- [CLI](https://github.com/kkkkhazix/agent-autoloop/blob/main/cli/main.ts): `cli/main.ts`

### Hub runtime

- [HTTP hub](https://github.com/kkkkhazix/agent-autoloop/blob/main/host/server.ts): `host/server.ts`
- [Hub runtime](https://github.com/kkkkhazix/agent-autoloop/blob/main/host/runtime.ts): `host/runtime.ts`
- [HTTP client](https://github.com/kkkkhazix/agent-autoloop/blob/main/protocol/client.ts): `protocol/client.ts`

### Decision kernel

- [Rule parsing](https://github.com/kkkkhazix/agent-autoloop/blob/main/protocol/rules.ts): `protocol/rules.ts`
- [Input validation](https://github.com/kkkkhazix/agent-autoloop/blob/main/protocol/validate.ts): `protocol/validate.ts`
- [Event decisions](https://github.com/kkkkhazix/agent-autoloop/blob/main/kernel/decide.ts): `kernel/decide.ts`
- [State queries](https://github.com/kkkkhazix/agent-autoloop/blob/main/kernel/query.ts): `kernel/query.ts`
- [Fact projections](https://github.com/kkkkhazix/agent-autoloop/blob/main/kernel/evolve.ts): `kernel/evolve.ts`

### Agent execution

- [Worker loop](https://github.com/kkkkhazix/agent-autoloop/blob/main/worker/worker.ts): `worker/worker.ts`
- [Agent adapters](https://github.com/kkkkhazix/agent-autoloop/blob/main/worker/agents.ts): `worker/agents.ts`

### Pluggable integrations

- [Agent plugins](https://github.com/kkkkhazix/agent-autoloop/tree/main/plugins): `plugins`
- [Event sources](https://github.com/kkkkhazix/agent-autoloop/blob/main/plugins/github/source.ts): `plugins/github/source.ts`
- [Channel dispatch](https://github.com/kkkkhazix/agent-autoloop/blob/main/host/channels.ts): `host/channels.ts`
- [Desktop channel](https://github.com/kkkkhazix/agent-autoloop/blob/main/plugins/desktop/channel.ts): `plugins/desktop/channel.ts`
- [Feishu channel](https://github.com/kkkkhazix/agent-autoloop/blob/main/plugins/feishu/channel.ts): `plugins/feishu/channel.ts`
- [Webhook channels](https://github.com/kkkkhazix/agent-autoloop/blob/main/plugins/webhook/channel.ts): `plugins/webhook/channel.ts`
- [PR delivery](https://github.com/kkkkhazix/agent-autoloop/blob/main/plugins/delivery/delivery.ts): `plugins/delivery/delivery.ts`

### Other components

- **Operator**
- **Event systems**
- **CLI agents**
- **Approval recipient**
- **SQLite**

## Connections

- Operator → CLI: runs commands
- CLI → HTTP client: calls hub (evidence: `cli/main.ts`)
- CLI → Rule parsing: parses rules (evidence: `cli/main.ts`)
- HTTP hub → Hub runtime: delegates requests (evidence: `host/server.ts`)
- Hub runtime → Event decisions: decides actions (evidence: `host/runtime.ts`)
- Hub runtime → State queries: reads state (evidence: `host/runtime.ts`)
- Hub runtime → Fact projections: persists facts (evidence: `host/runtime.ts`)
- Event decisions → Input validation: validates events (evidence: `kernel/decide.ts`)
- Event decisions → Fact projections: records facts (evidence: `kernel/evolve.ts`)
- State queries → Fact projections: reads projections (evidence: `kernel/query.ts`)
- Fact projections → SQLite: stores log (evidence: `kernel/evolve.ts`)
- Worker loop → HTTP client: claims work (evidence: `worker/worker.ts`)
- Worker loop → Agent adapters: selects adapter (evidence: `worker/worker.ts`)
- Worker loop → Input validation: checks receipt (evidence: `protocol/validate.ts`)
- Agent adapters → Agent plugins: loads plugin (evidence: `worker/agents.ts`)
- Agent plugins → CLI agents: launches process
- Event systems → Event sources: emits events
- Event sources → HTTP client: submits events
- Channel dispatch → HTTP client: fetches cards (evidence: `host/channels.ts`)
- Channel dispatch → Desktop channel: loads channel (evidence: `plugins/desktop/channel.ts`)
- Channel dispatch → Feishu channel: loads channel (evidence: `plugins/feishu/channel.ts`)
- Channel dispatch → Webhook channels: loads channel (evidence: `plugins/webhook/channel.ts`)
- Desktop channel → Approval recipient: delivers cards
- Feishu channel → Approval recipient: delivers cards
- Webhook channels → Approval recipient: delivers cards
- Approval recipient → HTTP client: submits answer
- Event systems → PR delivery: triggers delivery