Project Overview
A toy project that reconstructs the supervisor-led multi-agent harness pattern seen in tools like OpenAI Codex CLI and Anthropic Claude Code. It keeps planning, execution, review, tool calls, and event channels explicit so the whole architecture stays readable and easy to experiment with.
Problem Definition & Goals
- Problem: Many agentic coding tools hide orchestration details behind frameworks, which makes it hard to inspect or modify the actual control loop and tool boundaries.
- Goal 1: Recreate a supervisor that can repeatedly delegate to planner, worker, and reviewer agents in a compact codebase.
- Goal 2: Keep role-specific schemas, tool permissions, and event flow explicit so each layer is easy to trace.
- Goal 3: Support both interactive CLI usage and programmatic embedding for fast experiments and extensions.
Key Features & Contributions
- Supervisor-Led Loop: Instead of a fixed planner-to-worker-to-reviewer chain, the supervisor dynamically chooses the next subagent and can revisit the same role multiple times.
- Explicit Role Boundaries: Planner focuses on read-only analysis, worker handles edits and commands, and reviewer validates outputs with separate schemas and tool scopes.
- YAML Configuration: Provider, per-role models, allowed tools, and retry limits are configurable without touching the code.
- Channel/Event Architecture: Events such as `run_started`, `tool_call_finished`, and `run_result` flow through listener and output channels, separating execution from presentation.
- Installable Package: Ships a `tiny-agent` CLI entrypoint and can be installed directly from GitHub for immediate local-workspace experiments.
Results & Learnings
- Result: Condensed the core architecture of modern coding-agent products into a small, inspectable harness suited for learning and experimentation.
- Result: The same codebase supports both interactive terminal runs and embedded library-style usage.
- Result: Pytest coverage spans supervisor, planner, worker, reviewer, and CLI behavior to catch regressions in the core loop.
- Learning: Agent reliability depends heavily on orchestration design choices like structured outputs, permission boundaries, and event visibility, not just on model quality.