Crow

An Agent Development Environment (ADE) for building, running, and improving autonomous coding agents.

Status: In active development. Phase 0 complete (ACP server, iterative refinement, task pipeline). See ROADMAP.md for what's next.

What is Crow?

Crow is NOT just an ACP server, NOT just an IDE. It's a complete environment where:

• Humans plan in a journal (Logseq-inspired knowledge base)
• Humans + agents prime the environment together (pair programming)
• Autonomous agents work in the primed environment (read journal → write code → document decisions)
• Humans review in the journal and provide feedback
• Knowledge accumulates and agents get better over time

Quick Start

Installation

Install the Crow CLI globally:

cd /home/thomas/src/projects/orchestrator-project/crow
uv build
uv tool install dist/crow_ai-0.1.2-py3-none-any.whl --python 3.12

This installs the crow command globally, available from any directory.

Configuration:

• API keys and secrets: ~/.crow/.env
• User settings: ~/.crow/config.yaml
• Sessions: ~/.crow/sessions/
• Logs: ~/.crow/logs/

Usage

Start the ACP server:

crow acp

Using with ACP clients:

uv --project /path/to/acp-python-sdk run python acp-python-sdk/examples/client.py crow acp

Other commands:

crow              # Show help
crow --version    # Show version

Reinstalling After Changes

cd /home/thomas/src/projects/orchestrator-project/crow
uv build
uv tool install dist/crow_ai-0.1.2-py3-none-any.whl --python 3.12

Development Setup

For development work on Crow itself:

cd /home/thomas/src/projects/orchestrator-project/crow
uv --project crow sync

See AGENTS.md for detailed development workflow instructions.

Documentation

• INSTALLATION.md - Installation and configuration guide
• DESIGN.md - Vision, architecture, and design decisions
• CURRENT_STATE.md - Analysis of current code and what needs fixing
• ROADMAP.md - Development phases and timeline
• AGENTS.md - Project-specific knowledge for agents
• REFACTOR_PLAN.md - Original refactor plan (superseded by ROADMAP.md)

Features

Current (Phase 0 - Complete)

• ✅ ACP Server - Streaming ACP server wrapping OpenHands SDK
• ✅ Iterative Refinement - Planning → Implementation → Critique → Documentation loop
• ✅ Task Pipeline - Split PLAN.md into tasks, run sequentially
• ✅ MCP Integration - playwright, zai-vision, fetch, web_search
• ✅ Session Management - Multiple concurrent sessions with persistence
• ✅ Slash Commands - /help, /clear, /status

In Progress (Phase 1-3)

• 🚧 Restructure - Moving files from root to src/crow/
• 📋 Jinja2 Templates - Replace hardcoded prompts with templates
• 📋 Environment Priming - Human + agent pair programming before autonomous phase

Planned (Phase 4-8)

• 📋 Project Management - /projects/ directory, git repos, journals
• 📋 Journal Page - Logseq-inspired knowledge base
• 📋 Web UI - CodeBlitz/Monaco integration
• 📋 Feedback Loops - Capture human feedback, feed to agents
• 📋 Telemetry - Self-hosted Laminar/Langfuse

Architecture

Crow
├── ACP Server (src/crow/agent/)
│   └── Streaming ACP protocol implementation
├── Orchestration (src/crow/orchestration/)
│   ├── Environment priming
│   ├── Task splitting
│   ├── Iterative refinement
│   └── Task pipeline
├── Web UI (Future)
│   ├── CodeBlitz/Monaco editor
│   ├── Journal page
│   ├── Project browser
│   └── Terminal
└── Projects (/projects/)
    └── Each project = git repo + journal

The Problem We're Solving

Current AI coding tools:

• ❌ Drop agents into empty workspaces (no context)
• ❌ Lose agent decisions in markdown files ("lost like tears in rain")
• ❌ No feedback loop (human review not captured)
• ❌ No knowledge accumulation

Our solution:

• ✅ Environment priming - Human + agent set up context first
• ✅ Journal - All decisions documented and linked
• ✅ Feedback loops - Human review captured and fed back
• ✅ Knowledge accumulation - Agents get better over time

Contributing

This is a personal project, but feedback and ideas are welcome!

License

MIT

Acknowledgments

• Agent Client Protocol
• OpenHands SDK
• Model Context Protocol
• Trae Solo - Autonomous development inspiration
• Google Antigravity - Agent-first IDE inspiration
• Logseq - Knowledge management inspiration
• CodeBlitz - Web IDE foundation

---

"The agent is the primary developer, humans are the critics/product managers."

Modified with Crow ADE