{"slug": "subagents-design-zerostack", "title": "Subagents design @ zerostack", "summary": "The developer behind the zerostack CLI coding agent detailed the design of its subagent architecture, which uses parallel read-only child agents with simple text input-output to explore codebases without polluting the main agent's context. The subagents are spawned via a task tool, run concurrently using tokio::spawn, and are restricted to read-only operations to avoid race conditions and safety issues. The design allows subagents to use cheaper or faster models than the main agent, improving efficiency for codebase exploration.", "body_md": "*tldr* Subagents architecture made of parallel read-only child agents with simple text input-output\n\n*context* [zerostack](https://github.com/gi-dellav/zerostack) is my lightweight CLI coding agent; give it a try!\n\nWhen an agent needs to understand a codebase, it has two choices: start probing files one by one (slow, burns tokens) or dump everything into context (impossible for large projects). Either way, the main agent's context fills up with exploration noise, decreasing coding performance.\n\nFollowing most mainstream coding agents, we decided to build subagents, but we needed to design subagents that follow the UNIX-like minimal philosphy of [zerostack](https://gi-dellav.github.io/zerostack/).\n\nSubagents are **read-only child agents** spawned by the main agent via a `task`\n\ntool. Each subagent receives a precise technical question and returns a focused answer. If multiple prompts are given, they run in **parallel** via `tokio::spawn`\n\n.\n\n```\nMain Agent                          Subagent(s)\n┌──────────────┐                   ┌─────────────────────┐\n│ read/write   │                   │ read                │\n│ edit/bash    │  calls \"task\"     │ grep                │\n│ task ────────│ ─────────────────→│ find_files          │\n│              │   with prompt(s)  │ list_dir            │\n│              │   spawns parallel │ todo                │\n│              │   tokio tasks     │ memory_read*        │\n│              │   returns findings│ memory_search*      │\n└──────────────┘                   └─────────────────────┘\n```\n\nKey constraints:\n\n`write`\n\n, `edit`\n\n, `bash`\n\n, `memory_write`\n\n, or `mcp_tool`\n\n`permission: None`\n\n(safe because they can only read)`subagents`\n\nCargo feature (enabled by default)This makes sure that no dangerous actions can be taken by a subagent, and than no condition race issues can happen between subagents, without needing to implement file locking.\n\nWhen you pass multiple prompts to the `task`\n\ntool, each spawns its own async task. `futures::future::join_all`\n\ngathers results. A failed subagent (panic or error) shows its error to the agent while the rest complete normally, allowing the agent to then either re-send the subagent or to complete the task with its own tools (ex. the task sent to the subagents required using the `git`\n\nbash command). Results are ordered by the original prompt index.\n\nThe idea shown in the system prompts that ship with zerostack is that subagents are to be treated by the main agents as subordinates that take high-level questions (ex. `How does Authentication work?`\n\n), and spit out low-level answers (ex. `In src/auth.rs, there is AuthManager, etc...`\n\n).\n\n| Field | Default | Description |\n|---|---|---|\n`task_max_turns` |\n`15` |\nMax agent turns per subagent |\n`task_enabled` |\n`true` |\nWhether the `task` tool is registered |\n`subagent_model` |\n`deepseek-v4-flash` |\nModel name or quick-model alias |\n`subagent_provider` |\n(same as main) | Provider for the subagent |\n\nSubagents can use a different model/provider than the main agent, with a separate API client created at startup, allowing for cheaper and faster models being used for codebase exploration (via subagent), while heavy models execute the real coding tasks.\n\nIn our system prompt we:\n\n`- **Subagent use:** The task tool spawns new LLM instances — it is slow and expensive. Use ONLY when answering requires searching 3+ distinct files and cross-referencing their contents (e.g. \\\"Where is MCP support implemented?\\\"). Do NOT use for: listing a directory, grepping one pattern, reading one known file, or any single-step operation. Call those tools directly instead. Do NOT use for wide/vague tasks (\\\"explore the codebase\\\"). If you already ran a subagent and got results, use those results — do not re-spawn.`\n\n`task`\n\ntool with: `- **task**: Delegate a MULTI-STEP read-only investigation to a subagent. Use ONLY when answering needs several file reads and cross-referencing. NOT for single operations (list_dir, grep, read a known file). Multiple prompts run in parallel. Subagent has read, grep, find_files, list_dir, memory access. Returns findings.`\n\nSubagents let the main agent delegate deep exploration without context bloat. A single turn can spawn 3-5 parallel investigations, each returning structured findings that the main agent incorporates into a coherent plan. This is especially powerful when combined with `ARCHITECTURE.md`\n\n— subagents receive the architecture context automatically, so they start exploring with design awareness, not from zero.\n\nTogether with our constrained read operations and faster I/O implementations, we managed to build a simpler and faster approach to subagents, that manage to resolve what opencode's subagent do with a 25% gain in code exploration time.\n\nThe entire implementation sits at 414 lines of code (written in Rust).\n\nFollow us [on Github](https://github.com/gi-dellav/zerostack/).", "url": "https://wpnews.pro/news/subagents-design-zerostack", "canonical_source": "https://dev.to/gi-dellav/subagents-design-zerostack-16e7", "published_at": "2026-09-03 21:10:24+00:00", "updated_at": "2026-09-03 21:24:47.146882+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-infrastructure"], "entities": ["zerostack", "tokio", "futures", "deepseek-v4-flash"], "alternates": {"html": "https://wpnews.pro/news/subagents-design-zerostack", "markdown": "https://wpnews.pro/news/subagents-design-zerostack.md", "text": "https://wpnews.pro/news/subagents-design-zerostack.txt", "jsonld": "https://wpnews.pro/news/subagents-design-zerostack.jsonld"}}