CoStaff v0.1.0 — a self-hosted AI staff, first stable release

CoStaff is the system I built for that stretch. One Manager Agent plus a set of specialists, communicating over A2A protocol, integrating tools through MCP, each running in its own Docker container. Today it goes to v0.1.0, the first stable release.

I. Why delivery is the part that goes missing

Take one request — "give me the Q3 sales report for the southern region" — and it spans three separate competencies: knowing which tables hold the data, turning a result set into the right chart, and assembling charts and narrative into a properly typeset PDF. Ask a single agent to hold all three and the instruction balloons while the tool sets start interfering with each other.

Splitting into specialists is the obvious answer, and it immediately raises two questions: where each specialist's tools come from, and how they pass finished artifacts between themselves. Those two answers decide whether the system can really deliver, and they're the main architectural trade-offs in CoStaff.

II. Agent ↔ MCP ↔ tools: what each layer owns

For an agent to actually do anything, it needs tools. Where those tools come from, and who defines them, shapes the whole system. CoStaff splits it into three layers.

The tool layer is the functions that genuinely touch files, databases and commands. The open-source database agent has four: get_connected_databases, inspect_database, inspect_table, query — see what's connected, read the schema, then run the query. The coding agent has 56, covering file read/write, git, execution, linting and environment management.

The MCP layer exposes them. The coding agent's MCP server registers tools automatically: it walks every module under tools/ and registers each public function that doesn't start with an underscore. Adding a capability means adding a function to tools/ — no server changes, no edits to the agent's instruction.

The agent layer only reasons. It points at a set of MCP endpoints through an environment variable (such as BUSINESS_ANALYSIS_AGENT_MCP_URLS), and what it can do is entirely what those endpoints expose. Above it sits the Manager Agent, dispatching over A2A protocol to whichever specialist fits.

Why the split matters

1. New capabilities don't touch the model. Tools are ordinary Python functions; write one, drop it in tools/, done. No retraining, no prompt surgery — the agent picks it up next run.

2. Specialists actually act, they don't just reply. The coding agent's tools include write_file, patch_file, git_commit and run_pytest; the database agent has query. It edits the file and runs the tests, rather than telling you how you could.

3. Someone owns the delivery step. Half of the business-analysis agent's eleven tools are about output: create_report_from_markdown, create_html_report, export_pdf — and inject_noto_font, which exists purely so CJK text doesn't come out of a PDF as tofu boxes. Unglamorous, but without it the final file isn't something you can send.

III. Specialists hand each other files

The second problem is more practical: when one job passes through three specialists, how do the intermediate files travel? Stuffing a whole CSV through the messaging layer isn't reasonable.

Every container mounts a shared costaff_data volume at /app/data, and each specialist gets its own working directory at /app/data/agent-{id}/.

Isolation and sharing hold at the same time: specialists write to their own directories without stepping on each other, but when it's needed the business-analysis agent can read the coding agent's output directly, instead of base64-ing files through A2A messages. Across a chain of "query the database → reconcile in code → produce the report", what moves between agents is a path, not the contents.

IV. Why it has to be self-hosted

The whole thing runs on your own machine, in Docker. That's a deliberate premise, not a cloud version I haven't got around to.

V. What v0.1.0 ships

• Manager Agent — the conversational entry point; decomposes and routes.
• Specialists — business-analysis (analysis and report output), coding (files, git, tests), database (schema exploration and queries), plus twinkle-hub and wrenai-oss.
• Agent template — the starting point for writing your own specialist.
• Channels — Telegram and WebChat (the OSS build takes async pushes over SSE, so long-running tasks report back on completion).
• The CLI — costaff start, costaff agent add, costaff channel add, costaff update.

VI. Install and start

Python 3.10+ and Docker are the prerequisites:

curl -fsSL https://raw.githubusercontent.com/costaff-ai/costaff/main/install.sh | bash

onboard is an interactive wizard — model, channel, the matching token — writing straight to .env. start brings up Postgres, agents, Manager and channels in order:

costaff onboard
costaff start

Adding a specialist or a channel, pinned to a tag:

costaff agent add business-analysis \
  --github https://github.com/costaff-ai/costaff-agent-business-analysis --tag v0.1.0
costaff channel add telegram --tag v0.1.0

The quickstart covers the flow in full; agents, channels and the CLI are in the docs.

Wrapping up

CoStaff isn't positioned at the orchestration layer itself, but at getting what orchestration produces actually delivered. Tools are ordinary Python functions, MCP registers them automatically, and the agent only reasons — so a new capability is one more function, and specialists genuinely edit the file, run the tests and produce the PDF rather than advising you to. Add the shared volume, where specialists hand each other files instead of strings, and the whole chain completes inside your own data boundary.

v0.1.0 is the first release I'm willing to tell people to go install. If something isn't right once you've installed it, open an issue — right after a release, that feedback is worth the most.