How h4fizwasabie/crow-agent works
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: run_agent.py Agent loop · context_assembler.py Context build · server.py Web UI · tool_executor.py Tool exec
Components 31
Front doors
Ways into the shared agent runtime
- Web app · Web-facing server and browser streaming entrypoint
app.py - CLI entry · Terminal/daemon startup path
crow_agent/__main__.py - Telegram bot · Telegram front door to the shared agent core
crow_agent/telegram_bot.py
Agent runtime
Core orchestration and turn handling
- Agent loop · State-machine turn loop coordinating recall, assemble, model, tools, and respond
crow_agent/run_agent.py - Context build · Collects and shapes inputs before a model turn
crow_agent/context_assembler.py - Prompt shape · Builds the model prompt and conversation framing
crow_agent/prompt_builder.py - Finalize turn · Cleans up and emits the final user-facing turn output
crow_agent/turn_finalizer.py - Failure handling · Classifies failures and steers recovery behavior
crow_agent/failure_classifier.py
Memory and state
Persistence, recall, and conversation state
- State store · Persistent agent/session state boundary
crow_agent/crow_state.py - Memory recall · Tracks remembered context and retrieval signals
crow_agent/memory_tracker.py - Recall sources · Sources that feed prior context into the assembler
crow_agent/context_sources.py
Model layer
Provider abstraction and model-facing utilities
- Providers · Backend-specific model adapters and configuration
crow_agent/providers.py - Provider mgr · Selects providers and handles fallback behavior
crow_agent/provider_manager.py - Model tools · Helpers for model selection and provider-facing operations
crow_agent/model_tools.py
Tools
Capability execution and safety boundaries
- Tool exec · Dispatches and mediates tool calls from the agent loop
crow_agent/tool_executor.py - File tools · File and workspace operations
crow_agent/tools_file.py - Web tools · Web retrieval and browsing integrations
crow_agent/tools_web.py - File safety · Filesystem access checks and safety boundary
crow_agent/file_safety.py
Background work
Autonomous schedulers and follow-up engines
- Cron engine · Scheduled autonomous task execution
crow_agent/cron_engine.py - Heartbeat · Continues work and surfaces proactive follow-through
crow_agent/heartbeat_engine.py - Reminders · Creates proactive reminders and callback work
crow_agent/reminder_engine.py
Web UI
Server-rendered browser interface
- Web UI · Optional web interface built on shared backend state
extensions/web_ui/server.py - Templates · Server-rendered HTML templates for the browser UI
templates - Static assets · Styles and other browser assets
static
Extensions
Optional add-on integrations
- Extensions · Optional integrations layered onto the core runtime
extensions - Project memory · Optional project-scoped memory integration
extensions/project_memory - YouTube transcribe · Optional transcription integration
extensions/youtube_transcribe
Team and skills
Structured delegation and reusable workflows
- Crew · Internal multi-agent team model
crow_agent/crew.py - Skills · Reusable skill assets and skill execution patterns
crow_agent/skills_system.py - Task registry · Named task patterns and specialist behaviors
crow_agent/task_registry.py - Profiles · Agent and specialist role definitions
crow_agent/agent_profiles.py
Connections 30
- 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