# h4fizwasabie/crow-agent architecture

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

- Interactive diagram: https://gitdiagram.com/h4fizwasabie/crow-agent
- Repository: https://github.com/h4fizwasabie/crow-agent

## Overview

1. **Overall shape**
   Crow Agent is a single-process Python assistant platform, not a distributed system. The core runtime is centered on one agent engine that can be reached from three front doors: the web UI, the CLI, and Telegram.

2. **Primary entrypoints**
   `app.py` is the web-facing server, providing the FastAPI app and streaming responses to the browser. `crow_agent/__main__.py` and `crow_agent/run_agent.py` support terminal/daemon-style execution. `crow_agent/telegram_bot.py` connects the same agent core to Telegram.

3. **Core agent loop**
   The main control flow is a state machine: **RECALL → ASSEMBLE → LLM → TOOLS → RESPOND**. That loop is orchestrated in `run_agent.py` and supported by modules for context building, prompt construction, tool execution, output finalization, and failure handling.

4. **Conversation and memory layer**
   `crow_state.py`, `memory_tracker.py`, and `context_sources.py` form the persistence and recall boundary. The README and tests indicate SQLite-backed storage with FTS5 full-text search, used to retrieve prior conversation context and memory vault content before each model turn.

5. **Model/provider abstraction**
   `providers.py`, `provider_manager.py`, and `model_tools.py` abstract over OpenAI-compatible LLM backends and provider failover. This is where API-key configuration, model selection, and fallback behavior live, so the rest of the agent can stay provider-agnostic.

6. **Context assembly and prompt shaping**
   `context_assembler.py`, `prompt_builder.py`, `output_compressor.py`, and `self_model.py` govern how much information gets sent to the model and how it is framed. The repository explicitly uses a token budget and tiered context strategy, with internal monologue treated differently from final user-facing output.

7. **Tooling boundary**
   Tools are separated from orchestration. `tool_executor.py` dispatches tool calls, while modules like `tools_file.py`, `tools_git.py`, `tools_web.py`, `tools_process.py`, `tools_ssh.py`, `tools_lsp.py`, `tools_mcp.py`, `tools_media.py`, `tools_tasks.py`, `tools_cron.py`, and `tools_comms.py` implement capability-specific integrations. `file_safety.py` and related checks provide a safety boundary for filesystem access.

8. **Autonomous background work**
   `cron_engine.py`, `heartbeat_engine.py`, and `reminder_engine.py` are the “runs without a user waiting” subsystems. They let Crow schedule tasks, continue long-running work, and proactively surface follow-ups. This is the main path for “research X and report back” style delegation.

9. **Multi-agent and role system**
   The repository includes a lightweight internal team model via `crew.py`, `team/`, and `agent_profiles.py`. Skills in `skills/` are reusable workflows/prompt assets, while `task_registry.py` and `skills_system.py` organize named task patterns and specialist behavior. This supports structured delegation without introducing separate services.

10. **Extensions and optional integrations**
   `extensions/` contains optional plug-ins such as the web UI extension, project memory, and YouTube transcription. `web_launcher.py` and `telegram_rich.py` suggest UI/transport-specific adapters that sit on top of the shared core rather than duplicating logic.

11. **UI and presentation layer**
   The browser interface is server-rendered with Jinja2 templates in `templates/` and static assets in `static/`. The web UI is a thin presentation shell over the same agent, sessions, providers, cron, tasks, and memory data exposed by the backend.

12. **Operational and verification boundaries**
   The repo includes a broad test suite under `tests/` plus end-to-end and provider tests at the top level. The `docs/adr/` directory documents architectural decisions such as background execution, the crew system, and the initiative/state-machine approach, indicating architecture is intentionally codified rather than incidental.

13. **Important architectural takeaway**
   Crow is best understood as a local AI agent runtime with a persistent memory store, a provider failover layer, a tool execution subsystem, and several front ends. The main diagram should center on the agent loop and show web/CLI/Telegram inputs feeding the same orchestration core, with background schedulers and extensions attached as secondary paths.

Main entry points: [`crow_agent/run_agent.py`](https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/run_agent.py) (Agent loop), [`crow_agent/context_assembler.py`](https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/context_assembler.py) (Context build), [`extensions/web_ui/server.py`](https://github.com/h4fizwasabie/crow-agent/blob/master/extensions/web_ui/server.py) (Web UI), [`crow_agent/tool_executor.py`](https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/tool_executor.py) (Tool exec)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Front doors"]
  node_app_py["Web app<br/>FastAPI entrypoint<br/>[app.py]"]
  node_main_py["CLI entry<br/>Python module entrypoint<br/>[__main__.py]"]
  node_telegram_bot["Telegram bot<br/>chat transport<br/>[telegram_bot.py]"]
end

subgraph group_runtime["Agent runtime"]
  node_run_agent{{"Agent loop<br/>orchestrator<br/>[run_agent.py]"}}
  node_context_assembler["Context build<br/>context orchestration"]
  node_prompt_builder["Prompt shape<br/>prompting<br/>[prompt_builder.py]"]
  node_turn_finalizer["Finalize turn<br/>response postprocess<br/>[turn_finalizer.py]"]
  node_failure_classifier["Failure handling<br/>error policy"]
end

subgraph group_state["Memory and state"]
  node_crow_state[("State store<br/>conversation state<br/>[crow_state.py]")]
  node_memory_tracker["Memory recall<br/>memory index<br/>[memory_tracker.py]"]
  node_context_sources["Recall sources<br/>retrieval adapters<br/>[context_sources.py]"]
end

subgraph group_models["Model layer"]
  node_providers["Providers<br/>LLM backends<br/>[providers.py]"]
  node_provider_manager["Provider mgr<br/>routing and failover"]
  node_model_tools["Model tools<br/>model utilities<br/>[model_tools.py]"]
end

subgraph group_tools["Tools"]
  node_tool_executor{{"Tool exec<br/>dispatcher<br/>[tool_executor.py]"}}
  node_tools_file["File tools<br/>filesystem tools<br/>[tools_file.py]"]
  node_tools_web["Web tools<br/>network tools<br/>[tools_web.py]"]
  node_file_safety["File safety<br/>guardrail<br/>[file_safety.py]"]
end

subgraph group_background["Background work"]
  node_cron_engine["Cron engine<br/>scheduler<br/>[cron_engine.py]"]
  node_heartbeat_engine["Heartbeat<br/>background loop"]
  node_reminder_engine["Reminders<br/>follow-up engine<br/>[reminder_engine.py]"]
end

subgraph group_presentation["Web UI"]
  node_web_ui_server["Web UI<br/>server-rendered UI<br/>[server.py]"]
  node_templates_dir["Templates<br/>Jinja2 views"]
  node_static_dir["Static assets<br/>frontend assets"]
end

subgraph group_extensions["Extensions"]
  node_extensions_dir["Extensions<br/>plugin area"]
  node_project_memory["Project memory<br/>extension"]
  node_youtube_transcribe["YouTube transcribe<br/>extension"]
end

subgraph group_coordination["Team and skills"]
  node_crew["Crew<br/>team coordination<br/>[crew.py]"]
  node_skills_system["Skills<br/>workflow system<br/>[skills_system.py]"]
  node_task_registry["Task registry<br/>task catalog<br/>[task_registry.py]"]
  node_agent_profiles["Profiles<br/>role definitions<br/>[agent_profiles.py]"]
end

node_app_py -->|"submit turn"| node_run_agent
node_main_py -->|"start loop"| node_run_agent
node_telegram_bot -->|"message turn"| node_run_agent
node_run_agent -->|"assemble context"| node_context_assembler
node_context_assembler -->|"read state"| node_crow_state
node_context_assembler -->|"recall memory"| node_memory_tracker
node_context_assembler -->|"pull sources"| node_context_sources
node_context_assembler -->|"shape prompt"| node_prompt_builder
node_prompt_builder -->|"invoke model"| node_providers
node_providers -->|"select backend"| node_provider_manager
node_provider_manager -->|"model ops"| node_model_tools
node_run_agent -->|"tool call"| node_tool_executor
node_tool_executor -->|"filesystem"| node_tools_file
node_tool_executor -->|"web access"| node_tools_web
node_tools_file -->|"guardrail"| node_file_safety
node_run_agent -->|"finalize response"| node_turn_finalizer
node_run_agent -->|"handle failure"| node_failure_classifier
node_cron_engine -->|"scheduled turn"| node_run_agent
node_heartbeat_engine -->|"continue work"| node_run_agent
node_reminder_engine -->|"follow up"| node_run_agent
node_web_ui_server -->|"render views"| node_templates_dir
node_web_ui_server -->|"serve assets"| node_static_dir
node_web_ui_server -->|"read sessions"| node_crow_state
node_extensions_dir -->|"contains"| node_project_memory
node_extensions_dir -->|"contains"| node_youtube_transcribe
node_crew -->|"roles"| node_agent_profiles
node_crew -->|"use skills"| node_skills_system
node_skills_system -->|"register tasks"| node_task_registry
node_run_agent -.->|"delegate"| node_crew
node_run_agent -.->|"apply skill"| node_skills_system

click node_app_py "https://github.com/h4fizwasabie/crow-agent/blob/master/app.py"
click node_main_py "https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/__main__.py"
click node_telegram_bot "https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/telegram_bot.py"
click node_run_agent "https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/run_agent.py"
click node_context_assembler "https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/context_assembler.py"
click node_prompt_builder "https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/prompt_builder.py"
click node_turn_finalizer "https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/turn_finalizer.py"
click node_failure_classifier "https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/failure_classifier.py"
click node_crow_state "https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/crow_state.py"
click node_memory_tracker "https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/memory_tracker.py"
click node_context_sources "https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/context_sources.py"
click node_providers "https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/providers.py"
click node_provider_manager "https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/provider_manager.py"
click node_model_tools "https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/model_tools.py"
click node_tool_executor "https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/tool_executor.py"
click node_tools_file "https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/tools_file.py"
click node_tools_web "https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/tools_web.py"
click node_file_safety "https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/file_safety.py"
click node_cron_engine "https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/cron_engine.py"
click node_heartbeat_engine "https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/heartbeat_engine.py"
click node_reminder_engine "https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/reminder_engine.py"
click node_web_ui_server "https://github.com/h4fizwasabie/crow-agent/blob/master/extensions/web_ui/server.py"
click node_templates_dir "https://github.com/h4fizwasabie/crow-agent/tree/master/templates"
click node_static_dir "https://github.com/h4fizwasabie/crow-agent/tree/master/static"
click node_extensions_dir "https://github.com/h4fizwasabie/crow-agent/tree/master/extensions"
click node_project_memory "https://github.com/h4fizwasabie/crow-agent/tree/master/extensions/project_memory"
click node_youtube_transcribe "https://github.com/h4fizwasabie/crow-agent/tree/master/extensions/youtube_transcribe"
click node_crew "https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/crew.py"
click node_skills_system "https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/skills_system.py"
click node_task_registry "https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/task_registry.py"
click node_agent_profiles "https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/agent_profiles.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_app_py,node_main_py,node_telegram_bot,node_web_ui_server,node_templates_dir,node_static_dir toneBlue
class node_run_agent,node_context_assembler,node_prompt_builder,node_turn_finalizer,node_failure_classifier,node_extensions_dir,node_project_memory,node_youtube_transcribe toneAmber
class node_crow_state,node_memory_tracker,node_context_sources,node_crew,node_skills_system,node_task_registry,node_agent_profiles toneMint
class node_providers,node_provider_manager,node_model_tools toneRose
class node_tool_executor,node_tools_file,node_tools_web,node_file_safety toneIndigo
class node_cron_engine,node_heartbeat_engine,node_reminder_engine toneTeal
```

## Components

### Front doors

Ways into the shared agent runtime

- [Web app](https://github.com/h4fizwasabie/crow-agent/blob/master/app.py): FastAPI entrypoint · Web-facing server and browser streaming entrypoint · `app.py`
- [CLI entry](https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/__main__.py): Python module entrypoint · Terminal/daemon startup path · `crow_agent/__main__.py`
- [Telegram bot](https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/telegram_bot.py): chat transport · Telegram front door to the shared agent core · `crow_agent/telegram_bot.py`

### Agent runtime

Core orchestration and turn handling

- [Agent loop](https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/run_agent.py): orchestrator · State-machine turn loop coordinating recall, assemble, model, tools, and respond · `crow_agent/run_agent.py`
- [Context build](https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/context_assembler.py): context orchestration · Collects and shapes inputs before a model turn · `crow_agent/context_assembler.py`
- [Prompt shape](https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/prompt_builder.py): prompting · Builds the model prompt and conversation framing · `crow_agent/prompt_builder.py`
- [Finalize turn](https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/turn_finalizer.py): response postprocess · Cleans up and emits the final user-facing turn output · `crow_agent/turn_finalizer.py`
- [Failure handling](https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/failure_classifier.py): error policy · Classifies failures and steers recovery behavior · `crow_agent/failure_classifier.py`

### Memory and state

Persistence, recall, and conversation state

- [State store](https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/crow_state.py): conversation state · Persistent agent/session state boundary · `crow_agent/crow_state.py`
- [Memory recall](https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/memory_tracker.py): memory index · Tracks remembered context and retrieval signals · `crow_agent/memory_tracker.py`
- [Recall sources](https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/context_sources.py): retrieval adapters · Sources that feed prior context into the assembler · `crow_agent/context_sources.py`

### Model layer

Provider abstraction and model-facing utilities

- [Providers](https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/providers.py): LLM backends · Backend-specific model adapters and configuration · `crow_agent/providers.py`
- [Provider mgr](https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/provider_manager.py): routing and failover · Selects providers and handles fallback behavior · `crow_agent/provider_manager.py`
- [Model tools](https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/model_tools.py): model utilities · Helpers for model selection and provider-facing operations · `crow_agent/model_tools.py`

### Tools

Capability execution and safety boundaries

- [Tool exec](https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/tool_executor.py): dispatcher · Dispatches and mediates tool calls from the agent loop · `crow_agent/tool_executor.py`
- [File tools](https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/tools_file.py): filesystem tools · File and workspace operations · `crow_agent/tools_file.py`
- [Web tools](https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/tools_web.py): network tools · Web retrieval and browsing integrations · `crow_agent/tools_web.py`
- [File safety](https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/file_safety.py): guardrail · Filesystem access checks and safety boundary · `crow_agent/file_safety.py`

### Background work

Autonomous schedulers and follow-up engines

- [Cron engine](https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/cron_engine.py): scheduler · Scheduled autonomous task execution · `crow_agent/cron_engine.py`
- [Heartbeat](https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/heartbeat_engine.py): background loop · Continues work and surfaces proactive follow-through · `crow_agent/heartbeat_engine.py`
- [Reminders](https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/reminder_engine.py): follow-up engine · Creates proactive reminders and callback work · `crow_agent/reminder_engine.py`

### Web UI

Server-rendered browser interface

- [Web UI](https://github.com/h4fizwasabie/crow-agent/blob/master/extensions/web_ui/server.py): server-rendered UI · Optional web interface built on shared backend state · `extensions/web_ui/server.py`
- [Templates](https://github.com/h4fizwasabie/crow-agent/tree/master/templates): Jinja2 views · Server-rendered HTML templates for the browser UI · `templates`
- [Static assets](https://github.com/h4fizwasabie/crow-agent/tree/master/static): frontend assets · Styles and other browser assets · `static`

### Extensions

Optional add-on integrations

- [Extensions](https://github.com/h4fizwasabie/crow-agent/tree/master/extensions): plugin area · Optional integrations layered onto the core runtime · `extensions`
- [Project memory](https://github.com/h4fizwasabie/crow-agent/tree/master/extensions/project_memory): extension · Optional project-scoped memory integration · `extensions/project_memory`
- [YouTube transcribe](https://github.com/h4fizwasabie/crow-agent/tree/master/extensions/youtube_transcribe): extension · Optional transcription integration · `extensions/youtube_transcribe`

### Team and skills

Structured delegation and reusable workflows

- [Crew](https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/crew.py): team coordination · Internal multi-agent team model · `crow_agent/crew.py`
- [Skills](https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/skills_system.py): workflow system · Reusable skill assets and skill execution patterns · `crow_agent/skills_system.py`
- [Task registry](https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/task_registry.py): task catalog · Named task patterns and specialist behaviors · `crow_agent/task_registry.py`
- [Profiles](https://github.com/h4fizwasabie/crow-agent/blob/master/crow_agent/agent_profiles.py): role definitions · Agent and specialist role definitions · `crow_agent/agent_profiles.py`

## Connections

- Web app → Agent loop: submit turn · Web requests are routed into the same agent loop
- CLI entry → Agent loop: start loop · CLI execution starts the core runtime
- Telegram bot → Agent loop: message turn · Telegram messages feed the shared orchestration core
- Agent loop → Context build: assemble context · Prepares recall and prompt inputs for the next model turn
- Context build → State store: read state · Loads persistent conversation and session state
- Context build → Memory recall: recall memory · Retrieves relevant stored memory and prior context
- Context build → Recall sources: pull sources · Gathers recall material from configured sources
- Context build → Prompt shape: shape prompt · Frames assembled context for the model
- Prompt shape → Providers: invoke model · Sends prompt to a backend provider
- Providers → Provider mgr: select backend · Routes and falls back across providers
- Provider mgr → Model tools: model ops · Shared model-selection and provider utilities
- Agent loop → Tool exec: tool call · Executes tool requests from the agent loop
- Tool exec → File tools: filesystem · Delegates file-oriented capabilities
- Tool exec → Web tools: web access · Delegates web-oriented capabilities
- File tools → File safety: guardrail · Filesystem access is checked before execution
- Agent loop → Finalize turn: finalize response · Converts model and tool results into the final reply
- Agent loop → Failure handling: handle failure · Classifies errors and recovery paths
- Cron engine → Agent loop: scheduled turn · Background jobs can launch the shared loop
- Heartbeat → Agent loop: continue work · Long-running work can resume through the core runtime
- Reminders → Agent loop: follow up · Proactive reminders re-enter the agent loop
- Web UI → Templates: render views · Browser UI is server-rendered from templates
- Web UI → Static assets: serve assets · Static browser assets support the UI
- Web UI → State store: read sessions · UI reflects the same underlying agent state
- Extensions → Project memory: contains · Optional project memory extension lives under the extensions area
- Extensions → YouTube transcribe: contains · Optional transcription extension lives under the extensions area
- Crew → Profiles: roles · Crew behavior is shaped by profile definitions
- Crew → Skills: use skills · Specialists reuse shared skill workflows
- Skills → Task registry: register tasks · Named tasks organize reusable specialist behavior
- Agent loop → Crew: delegate · The agent loop can hand work to the internal team model
- Agent loop → Skills: apply skill · Skill assets influence turn execution and delegation