catowabisabi/task-hounds
Task Hounds is a local-first, inspectable multi-agent development workspace. Give it a goal; the Manager plans, the Worker implements, and the Reviewer checks the result. Directives, todos, reports...
0 stars · 0 forks · 0 watchers
README
English · 繁體中文
Task Hounds
Work like a dog. Ship like a pack. A local, inspectable multi-agent development workspace powered by OpenCode.
Website · GitHub · Demo · Issues
What is Task Hounds? Task Hounds turns one human goal into a visible development loop. Give the pack a Human Directive; the Manager plans, the Worker implements, and the Reviewer checks the result before the next task begins. Unlike a black-box coding assistant, Task Hounds keeps the work inspectable. Directives, plans, todos, reports, agent state, and reusable OpenCode sessions are stored locally, while the dashboard shows what every agent is doing in real time. It is designed for developers who want agent autonomy without giving up control or context. The pack
Role Responsibility
You Set the durable project mission, add ideas, and redirect the work at any time.
Manager Understand context, maintain the plan, and assign one concrete task at a time.
Worker Implement the selected task and report files changed, tests, and known issues.
Reviewer Inspect the result for bugs, UX problems, edge cases, and safety risks.
Chat Let you discuss the project and interact with the system directly.
flowchart LR H["Human Directive"] --> M["Manager<br>Plan & delegate"] M --> W["Worker<br>Implement"] W --> R["Reviewer<br>Verify"] R --> M M --> D["Live dashboard<br>Todos, reports & state"] W --> D R --> D
Loading
Detailed workflow Human input contract
Input Meaning Lifecycle
HUMAN_DIRECTIVE The durable project or session mission. Copied into each new session in the same project. The agent loop never edits or deletes it; only a human can change it.
HUMAN_NEW_THOUGHT_AND_SUGGESTION Direction, questions, product taste, concerns, or ideas. The Manager digests it, may turn it into todo items, then marks it processed while preserving its history.
HUMAN_SUGGESTED_NEW_TASK_OR_ITEM An explicit feature or work item. The Manager adds it to the plan and todo system when appropriate, then marks it processed while preserving its history.
The loop runs on an explicit message contract: the Manager digests input, decides, plans, and releases exactly one task; the Worker implements and files a structured report; the Reviewer verifies and routes feedback back to the Manager. Machine-readable todo JSON is validated (and repaired) before any work is released. Full specification — complete loop, role/data-flow diagram, time sequence, and hard rules: docs/architecture/agent-loop-contract.md Why Task Hounds?
Local first — your workspace, database, runtime state, and logs stay on your machine. Inspectable by design — follow live thinking, tool activity, todos, reports, and review feedback. Persistent context — SQLite-backed project state and reusable role sessions survive across loops. Clear responsibilities — planning, implementation, and review are handled by separate agents. Human steerable — change direction with durable directives, thoughts, and suggested tasks. Multiple ways to run — web dashboard, Windows desktop app, Docker, and an experimental Android client. Open source — MIT licensed and ready to adapt.
See it in action
Quick start Fastest way: Docker Compose (any platform) git clone https://github.com/catowabisabi/task-hounds.git cd task-hounds docker compose up Then open http://localhost:8765. The image builds the dashboard for you — no Python or Node setup required. Project data persists in ./data. From source (Windows, recommended for the managed runtime) Requirements
Windows (recommended for the managed runtime and desktop build) Python 3.11+ Node.js 20+ npm
1. Clone and install git clone https://github.com/catowabisabi/task-hounds.git cd task-hounds
.\installation.cmd pip install -r requirements.txt pip install . installation.cmd installs the pinned, managed OpenCode runtime used by Task Hounds. 2. Build the dashboard cd ui/web npm ci npm run build cd ../.. 3. Configure Copy-Item .env.example .env Task Hounds keeps the legacy POWER_TEAMS_ environment-variable prefix for compatibility. Review .env.example before adding provider keys or exposing the API beyond localhost. 4. Run task-hounds-serve --port 8765 (Equivalent: python -m task_hounds_api --port 8765.) Open http://localhost:8765, create or select a workspace, write a Human Directive, then choose Start Loop or Run Once. By default, projects are created under ~/task-hounds-projects. Override with the TASK_HOUNDS_PROJECTS_DIR environment variable. Existing installs that already use C:\task-hounds-projects keep working unchanged.
Task Hounds will not begin autonomous work without a pending Human Directive.
For more detail, see the Getting Started guide. Model providers Task Hounds talks to models through OpenCode's Anthropic-compatible providers. Three are bundled — bring any one key and the pack runs:
Provider Models Env key
MiniMax (default) MiniMax-M2.7 OPENCODE_API_KEY_MINIMAX
Moonshot Kimi kimi-k3 (1M context), kimi-k2.7-code, kimi-k2.7-code-highspeed OPENCODE_API_KEY_KIMI
Alibaba Bailian Qwen3.x, GLM, Kimi K2.5 OPENCODE_API_KEY_BAILIAN
The default model for every role is minimax-coding-plan/MiniMax-M2.7. Switch the whole pack to Kimi K3 Kimi K3 ships with a 1M-token context window and thinking on by default — a great fit for long agent loops. Get a key from the Kimi Open Platform, then in .env: OPENCODE_API_KEY_KIMI=your_kimi_api_key TASK_HOUNDS_OPENCODE_MODEL=kimi-coding-plan/kimi-k3 Restart, and Manager, Worker, and Reviewer all run on Kimi K3. You can also paste the key in the dashboard's Runtime panel, or pick the model per role in the binding editor. Mix models per role Each role resolves its model independently, so you can put the strongest reasoner where it matters: TASK_HOUNDS_MANAGER_OPENCODE_MODEL=kimi-coding-plan/kimi-k3 TASK_HOUNDS_REVIEWER_OPENCODE_MODEL=kimi-coding-plan/kimi-k3