How spandan7724/songbird works
Project type and purpose
• Songbird is a terminal-first AI coding companion CLI tool written in Python. It orchestrates user conversations, invokes LLM providers, runs “professional” development tools (file operations, search, shell, todos), and persists session memory.
Top-level components (per the file tree and README)
• CLI Layer (songbird/cli.py, songbird/commands/…, songbird/cli_utils.py)
• Core Orchestrator (songbird/orchestrator.py, songbird/core/…)
• Agent & Planning (songbird/agent/…)
• LLM Adapter & Providers (songbird/llm/…)
• Tools Framework (songbird/tools/…)
• Memory & Persistence (songbird/memory/…)
• Configuration (songbird/config/…)
• UI Layer (songbird/ui/…)
• Prompts (songbird/prompts/agent.txt)
• Model Discovery (songbird/discovery/…)
Key interactions and data flows
• User types a command or natural-language prompt → CLI Layer parses & dispatches to Orchestrator.
• Orchestrator invokes the Agent Core, which:
• Classifies the message (message_classifier.py)
• Updates the conversation plan (plan_manager.py, planning.py)
• Possibly calls external Tools via the Tool Runner.
• When a natural-language turn requires LLM intelligence:
• Agent calls the unified LLM interface (llm/unified_interface.py)
• LLM interface selects an active provider (OpenAI, Gemini, Copilot, Ollama, etc.) using session managers (aiohttp_session_manager.py, http_session_manager.py) and provider adapters (copilot_provider.py, litellm_adapter.py).
• The external LLM returns a response.
• Tool invocation:
• Agent or CLI issues a tool call → Tool Registry (tool_registry.py) → Tool Runner (tool_runner.py) → Specific tool modules (file_operations.py, grep_tool.py, shell_exec.py, todo_manager.py, etc.)
• Tools operate on the local filesystem or shell and return results.
• Memory system:
• Every turn is recorded in History Manager (memory/history_manager.py).
• Memory Manager (memory/manager.py, optimized_manager.py) persists sessions per repository.
• UI Layer (ui/ui_layer.py) formats and streams output back to the terminal using Rich.
Architectural patterns and principles
• Layered modular architecture separating:
• Presentation (CLI/UI)
• Orchestration & Agent logic
• LLM abstraction
• Tools execution
• Memory persistence
• Configuration & discovery
• Plugin-style tool registry for extensibility.
• Unified adapter pattern for multiple LLM providers.
• Transactional/atomic multi-file operations with rollback.
• Event loop & signal handling for responsive CLI interactions.
Detailed capture of essential elements
• Interactions between sub-components (e.g., Agent → Plan Manager → Message Classifier).
• That tool calls are mediated via the Tool Registry and Runner.