owlen/TODO.md

Owlen Project Improvement Roadmap

Generated from codebase analysis on 2025-11-01

Overall Assessment

Grade: A (90/100) Status: Production-ready with minor enhancements needed Architecture: Excellent domain-driven design with clean separation of concerns

---

🔴 Critical Issues (Do First)

• Fix Integration Test Failure (crates/app/cli/tests/chat_stream.rs) ✅ COMPLETED

  • Fixed mock server to accept requests with tools parameter
  • Test now passes successfully
  • Location: crates/app/cli/tests/chat_stream.rs

• Remove Side Effects from Library Code (crates/core/agent/src/lib.rs:348-349) ✅ COMPLETED

  • Replaced println! with tracing crate
  • Added tracing = "0.1" dependency to agent-core
  • Changed to structured logging: tracing::debug! for tool calls, tracing::warn! for errors
  • Users can now control verbosity and route logs appropriately
  • Location: crates/core/agent/src/lib.rs:348, 352, 361

---

🟡 High-Priority Improvements

Permission System ✅

• Implement Proper Permission Selection in TUI ✅ COMPLETED
  • Added interactive permission popup with keyboard navigation
  • Implemented "Allow once", "Always allow", "Deny", and "Explain" options
  • Integrated permission requests into agent loop with async channels
  • Added runtime permission rule updates for "Always allow"
  • Permission popups pause execution and wait for user input
  • Location: crates/app/ui/src/app.rs, crates/app/ui/src/components/permission_popup.rs

Documentation

• Add User-Facing README.md

  • Quick start guide
  • Installation instructions
  • Usage examples
  • Feature overview
  • Links to detailed docs
  • Priority: HIGH

• Add Architecture Documentation

  • Crate dependency graph diagram
  • Agent loop flow diagram
  • Permission system flow diagram
  • Plugin/hook integration points diagram
  • Priority: MEDIUM

Feature Integration

• Integrate Plugin System

  • Wire plugin loading into crates/app/cli/src/main.rs
  • Load plugins at startup
  • Test with example plugins
  • Priority: HIGH

• Integrate MCP Client into Agent

  • Add MCP tools to agent's tool registry
  • Enable external tool servers (databases, APIs, etc.)
  • Document MCP server setup
  • Priority: HIGH

• Implement Real Web Search Provider

  • Add provider for DuckDuckGo, Brave Search, or SearXNG
  • Make the web tool functional
  • Add configuration for provider selection
  • Priority: MEDIUM

Error Handling & Reliability

• Add Retry Logic for Transient Failures

  • Exponential backoff for Ollama API calls
  • Configurable retry policies (max attempts, timeout)
  • Handle network failures gracefully
  • Priority: MEDIUM

• Enhance Error Messages

  • Add actionable suggestions for common errors
  • Example: "Ollama not running? Try: ollama serve"
  • Example: "Model not found? Try: ollama pull qwen3:8b"
  • Priority: MEDIUM

---

🟢 Medium-Priority Enhancements

Testing

• Add UI Component Testing

  • Snapshot tests for TUI components
  • Integration tests for user interactions
  • Use ratatui testing utilities
  • Priority: MEDIUM

• Add More Edge Case Tests

  • Glob patterns with special characters
  • Edit operations with Unicode
  • Very large file handling
  • Concurrent tool execution
  • Priority: MEDIUM

• Code Coverage Reporting

  • Integrate tarpaulin or cargo-llvm-cov
  • Set minimum coverage thresholds (aim for 80%+)
  • Track coverage trends over time
  • Priority: LOW

Documentation

• Module-Level Documentation

  • Add //! docs to key modules
  • Explain design decisions and patterns
  • Document internal APIs
  • Priority: MEDIUM

• Create Examples Directory

  • Simple CLI usage examples
  • Custom plugin development guide
  • Hook script examples
  • MCP server integration examples
  • Configuration templates
  • Priority: MEDIUM

Code Quality

• Fix Dead Code Warning (ui/src/app.rs:38)

  • Either use settings field or remove it
  • Remove #[allow(dead_code)]
  • Priority: LOW

• Improve Error Recovery

  • Checkpoint auto-save on crashes
  • Graceful degradation when tools fail
  • Better handling of partial tool results
  • Priority: MEDIUM

---

🔵 Low-Priority Nice-to-Haves

Project Infrastructure

• CI/CD Pipeline (GitHub Actions)

  • Automated testing on push
  • Clippy linting
  • Format checking with rustfmt
  • Security audits with cargo-audit
  • Cross-platform builds (Linux, macOS, Windows)
  • Priority: LOW

• Performance Benchmarking

  • Add benchmark suite using criterion crate
  • Track performance for glob, grep, large file ops
  • Track agent loop iteration performance
  • Priority: LOW

Code Organization

• Extract Reusable Crates
  • Publish mcp-client as standalone library
  • Publish llm-ollama as standalone library
  • Enable reuse by other projects
  • Consider publishing to crates.io
  • Priority: LOW

---

💡 Feature Enhancement Ideas

Session Management

• Session Persistence
  • Auto-save sessions across restarts
  • Resume previous conversations
  • Session history browser in TUI
  • Export/import session transcripts

Multi-Provider Support

• Multi-Model Support
  • Support Anthropic Claude API
  • Support OpenAI API
  • Provider abstraction layer
  • Fallback chains for reliability

Enhanced Permissions

• Advanced Permission System
  • Time-based permissions (expire after N minutes)
  • Scope-based permissions (allow within specific directories)
  • Permission profiles (dev, prod, strict)
  • Team permission policies

Collaboration

• Collaborative Features
  • Export sessions as shareable transcripts
  • Import/export checkpoints
  • Shared permission policies for teams
  • Session replay functionality

Observability

• Enhanced Observability
  • Token usage tracking per tool call
  • Cost estimation dashboard
  • Performance metrics export (JSON/CSV)
  • OpenTelemetry integration
  • Real-time stats in TUI

---

🚀 Quick Wins (Can Be Done Today)

• Add README.md to repository root
• Fix dead code warning in ui/src/app.rs:38
• Add tracing crate and replace println! calls
• Create .github/workflows/ci.yml for basic CI
• Add module-level docs to agent-core and config-agent

---

🌟 Long-Term Vision

• Plugin Marketplace: Curated registry of community plugins
• Interactive Tutorial: Built-in tutorial mode for new users
• VS Code Extension: Editor integration for inline assistance
• Collaborative Agents: Multi-agent workflows with role assignment
• Knowledge Base Integration: RAG capabilities for project-specific knowledge
• Web Dashboard: Browser-based interface for session management
• Cloud Sync: Sync configs and sessions across devices

---

Notes

• Test Status: 28+ tests, most passing. 1 integration test failure (mock server issue)
• Test Coverage: Strong coverage for core functionality (permissions, checkpoints, hooks)
• Architecture: Clean domain-driven workspace with 15 crates across 4 domains
• Code Quality: Excellent error handling, consistent patterns, minimal technical debt
• Innovation Highlights: Checkpoint/rewind system, three-tiered permissions, shell-based hooks

---

Priority Legend

• HIGH: Should be done soon, blocks other features or affects quality
• MEDIUM: Important but not urgent, improves user experience
• LOW: Nice to have, can be deferred

---

Last Updated: 2025-11-01