dostuff 0.2.5__tar.gz → 0.2.6__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {dostuff-0.2.5 → dostuff-0.2.6}/PKG-INFO +132 -11
- {dostuff-0.2.5 → dostuff-0.2.6}/README.md +131 -10
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/agent/instructions.py +31 -9
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/agent/loop.py +44 -20
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/agent/permissions.py +3 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/agent/run_tool.py +11 -1
- dostuff-0.2.6/dostuff/agent/subagents/__init__.py +32 -0
- dostuff-0.2.6/dostuff/agent/subagents/adapter.py +103 -0
- dostuff-0.2.6/dostuff/agent/subagents/definitions.py +373 -0
- dostuff-0.2.6/dostuff/agent/subagents/fork.py +43 -0
- dostuff-0.2.6/dostuff/agent/subagents/prompt.py +53 -0
- dostuff-0.2.6/dostuff/agent/subagents/registry.py +576 -0
- dostuff-0.2.6/dostuff/agent/subagents/run.py +148 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/cli_tui.py +530 -89
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/config.py +18 -2
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/headless.py +122 -20
- dostuff-0.2.6/dostuff/helpers/agent/append_step.py +13 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/agent/constants.py +53 -4
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/agent/get_model_token_limit.py +4 -4
- dostuff-0.2.6/dostuff/helpers/agent/notices.py +132 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/agent/slash_suggestion.py +21 -1
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/hooks/dispatch.py +5 -3
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/hooks/events.py +26 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/hooks/load_hooks.py +2 -1
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/hooks/run_hook.py +10 -1
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/skills/discover_skills.py +17 -3
- dostuff-0.2.6/dostuff/helpers/ui/tools_listing.py +61 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/lib/memory/session_store.py +99 -5
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/lib/model.py +23 -5
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/templates/config.example.yaml +17 -2
- dostuff-0.2.6/dostuff/tools/agent.py +102 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/tools/bash/jobs.py +15 -11
- dostuff-0.2.6/dostuff/tools/create_agent_type.py +138 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/tools/definitions.py +15 -9
- dostuff-0.2.6/dostuff/tools/names.py +16 -0
- dostuff-0.2.6/dostuff/tools/send_message.py +53 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/tools/settings.py +6 -3
- dostuff-0.2.6/dostuff/tools/stop_agent.py +21 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff.egg-info/PKG-INFO +132 -11
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff.egg-info/SOURCES.txt +22 -1
- {dostuff-0.2.5 → dostuff-0.2.6}/pyproject.toml +1 -1
- {dostuff-0.2.5 → dostuff-0.2.6}/tests/test_bash_command.py +4 -2
- {dostuff-0.2.5 → dostuff-0.2.6}/tests/test_checkpoints_todos_caching.py +1 -1
- {dostuff-0.2.5 → dostuff-0.2.6}/tests/test_cli_commands.py +146 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/tests/test_config_memory_mcp.py +55 -1
- dostuff-0.2.6/tests/test_create_agent_type.py +93 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/tests/test_hooks.py +119 -5
- {dostuff-0.2.5 → dostuff-0.2.6}/tests/test_jobs.py +7 -5
- {dostuff-0.2.5 → dostuff-0.2.6}/tests/test_loop.py +2 -2
- {dostuff-0.2.5 → dostuff-0.2.6}/tests/test_permissions.py +3 -2
- dostuff-0.2.6/tests/test_session_store.py +440 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/tests/test_settings_tools.py +1 -1
- dostuff-0.2.6/tests/test_skills_discovery.py +37 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/tests/test_slash_suggestion.py +18 -0
- dostuff-0.2.6/tests/test_subagent.py +174 -0
- dostuff-0.2.6/tests/test_subagents_background.py +510 -0
- dostuff-0.2.6/tests/test_subagents_fork.py +241 -0
- dostuff-0.2.6/tests/test_subagents_run.py +499 -0
- dostuff-0.2.6/tests/test_subagents_store.py +324 -0
- dostuff-0.2.6/tests/test_subagents_types.py +485 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/tests/test_tool_schemas.py +10 -1
- dostuff-0.2.6/tests/test_tools_listing.py +35 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/tests/test_tui.py +750 -11
- {dostuff-0.2.5 → dostuff-0.2.6}/tests/test_worktree.py +26 -25
- dostuff-0.2.5/dostuff/helpers/agent/append_step.py +0 -11
- dostuff-0.2.5/dostuff/tools/delegate_to_subagent.py +0 -266
- dostuff-0.2.5/tests/test_session_store.py +0 -179
- dostuff-0.2.5/tests/test_subagent.py +0 -164
- {dostuff-0.2.5 → dostuff-0.2.6}/LICENSE +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/__init__.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/__main__.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/agent/call_agent.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/cli.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/agent/consume_stream.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/agent/context_usage.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/agent/environment_context.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/agent/file_mentions.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/agent/load_identity.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/agent/load_project_instructions.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/agent/loop_check_cancelled.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/agent/loop_emit.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/agent/manage_context.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/agent/model_cost.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/agent/pastes.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/agent/quick_memory.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/agent/tool_output.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/hooks/__init__.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/hooks/trust.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/mcp/load_mcp_config.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/mcp/mcp_oauth.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/mcp/server_config.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/mcp/token_store.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/memory/export_session.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/memory/resolve_memory_operation.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/memory/shell_step.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/models/add_model_entry.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/models/list_models.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/models/opencode.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/skills/custom_commands.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/skills/skill_command.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/tools/diff.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/tools/generate_tool_schema.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/tools/project_root.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/tools/resolve_safe_path.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/ui/__init__.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/ui/doctor.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/ui/emit.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/ui/prompt_history.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/helpers/ui/terminal_signals.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/lib/checkpoints.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/lib/exceptions.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/lib/mcp/mcp_client.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/lib/mcp/mcp_client_registration_store.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/lib/mcp/mcp_tool_registry_store.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/lib/memory/chroma.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/lib/memory/episodic_memory_store.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/lib/memory/semantic_memory_store.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/lib/memory/stores.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/lib/memory/types.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/lib/tracing.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/lib/worktree.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/memory/__init__.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/setup_wizard.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/skills.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/templates/env.example +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/tools/__init__.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/tools/bash/bash_command.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/tools/bash/bash_output.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/tools/bash/kill_shell.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/tools/files/delete_file.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/tools/files/edit_file.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/tools/files/list_files.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/tools/files/read_file.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/tools/files/write_file.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/tools/get_current_datetime.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/tools/mcp/call_mcp_tool.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/tools/mcp/get_mcp_tool_details.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/tools/mcp/search_mcp_tools.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/tools/memory/save_episode.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/tools/memory/save_memory.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/tools/search/glob.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/tools/search/grep.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/tools/search/walk.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/tools/todo_write.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/tools/web_fetch.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff/tools/web_search.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff.egg-info/dependency_links.txt +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff.egg-info/entry_points.txt +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff.egg-info/requires.txt +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/dostuff.egg-info/top_level.txt +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/setup.cfg +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/tests/test_file_mentions.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/tests/test_file_tools.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/tests/test_mcp_e2e.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/tests/test_mcp_oauth.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/tests/test_opencode.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/tests/test_optional_memory_and_instructions.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/tests/test_pastes.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/tests/test_roadmap_021.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/tests/test_setup_wizard.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/tests/test_skill_command.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/tests/test_terminal_signals.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/tests/test_web_fetch.py +0 -0
- {dostuff-0.2.5 → dostuff-0.2.6}/tests/test_web_search.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: dostuff
|
|
3
|
-
Version: 0.2.
|
|
3
|
+
Version: 0.2.6
|
|
4
4
|
Summary: DoStuff - a terminal coding agent for any LLM: TUI and headless mode, permissions, MCP, skills, web tools, sessions and git worktrees
|
|
5
5
|
Author-email: Varun Kumawat <varunkumawatleap2@gmail.com>
|
|
6
6
|
License-Expression: MIT
|
|
@@ -84,11 +84,11 @@ DoStuff is a terminal AI agent that runs anywhere `pip` runs. It gives you a ful
|
|
|
84
84
|
- **Project instructions** — `AGENTS.md` / `CLAUDE.md` from `~/.dostuff/`, the repo root and every folder down to the current one, combined
|
|
85
85
|
- **Coding tools** — `read_file` (line numbers, offset/limit), `edit_file` (exact replacement), `write_file`, `grep`, `glob`, `list_files`, `delete_file`, `bash_command`, `web_fetch` (read a URL as text), `web_search` (free, no API key)
|
|
86
86
|
- **Permission layer** — mutating tool calls ask for approval (allow once / always this session / deny with a note); read-only shell commands run without asking; modes `ask` / `allowlist` / `auto`; `/undo` reverts the agent's file changes
|
|
87
|
-
- **Hooks** — shell commands on `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop` and `SubagentStop` that can block a tool call or prompt, feed a formatter's output back to the model, or keep the turn going; Claude Code's hook I/O contract, and project hooks run only once you trust them. See [Hooks](#hooks)
|
|
87
|
+
- **Hooks** — shell commands on `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`, `SubagentStart` and `SubagentStop` that can block a tool call or prompt, feed a formatter's output back to the model, or keep the turn going; Claude Code's hook I/O contract, and project hooks run only once you trust them. See [Hooks](#hooks)
|
|
88
88
|
- **Background jobs** — `bash_command(run_in_background=true)` starts dev servers, watchers and long test runs as jobs the agent reads with `bash_output` (`wait_for` a ready line) and stops with `kill_shell`; it hears when one ends. `Ctrl+B` moves a running command to the background, `/jobs` lists them, and none outlives the session. See [Background jobs](#background-jobs)
|
|
89
89
|
- **File sandbox** — file tools stay inside the project directory and never read `.env*` files or `~/.dostuff/`
|
|
90
90
|
- **Skills loader** — drop a `SKILL.md` in the right folder, restart, done; run one with `/<skill-name> [args]`
|
|
91
|
-
- **Subagents** — `
|
|
91
|
+
- **Subagents** — the `agent` tool starts agents in parallel, in the foreground or the background, from built-in types (`explore`, `plan`, `general-purpose`), your own Markdown agent files (Claude Code's `.claude/agents/` work too) or a `fork` of the conversation; continue one with `send_message`, stop it with `stop_agent`, see them all in `/agents`. See [Subagents](#subagents)
|
|
92
92
|
- **Per-tool timeout** (120s) to prevent hung servers; long tool output is truncated (head + tail) before it reaches the model
|
|
93
93
|
- **Retries with backoff** for rate limits, timeouts and 5xx errors (6 by default, exponential with jitter, honors `Retry-After`; `loop.max_retries` / `loop.retry_max_delay`); auth / bad-request errors fail fast
|
|
94
94
|
- **Token and cost tracking** — per-turn and cumulative totals in `/status` and the line after each turn (`✻ Worked for 1m 5s · $0.01`); cost in USD from litellm's price table (hidden when the model has no known price). The table bundled with litellm is used, so startup doesn't wait on a download; set `LITELLM_LOCAL_MODEL_COST_MAP=False` to fetch the latest one from GitHub instead
|
|
@@ -230,9 +230,10 @@ In the TUI:
|
|
|
230
230
|
| `Ctrl+R` | Search the prompts typed in this directory (type to filter, `Enter` puts the prompt in the input) |
|
|
231
231
|
| `Esc` `Esc` | With an empty input: take back your last prompt. It and everything after it (answer, tool calls) leave the conversation and the prompt goes back in the input to edit and resend. Files that turn changed stay as they are; `/undo` restores them |
|
|
232
232
|
| `Ctrl+O` | Expand / collapse every truncated tool and shell result (click one to toggle just that one) |
|
|
233
|
-
| `Ctrl+B` | While the agent waits on a shell command (the loader says `Ctrl+B to background`): move
|
|
233
|
+
| `Ctrl+B` | While the agent waits on a shell command or a foreground subagent (the loader says `Ctrl+B to background`): move them to the background; the agent gets what a command printed so far and carries on, and hears from the agent when it ends. Not for `!command`s. See [Background jobs](#background-jobs) and [Subagents](#subagents) |
|
|
234
234
|
| `Shift+Tab` | Cycle the permission mode for this session: ask → auto → plan → allowlist (shown in the status bar) |
|
|
235
235
|
| `Ctrl+Backspace` / `Ctrl+W` / `Alt+Backspace` | Delete the previous word; `Ctrl+Delete` / `Alt+Delete` the next one |
|
|
236
|
+
| `/agents` / `/agents types` / `/agents reload` | This session's agents (running first): pick one to read its transcript, answer its approval prompt or stop it / the agent types with their source, model and tools (`/agents types <name>`: one type's system prompt and config) / re-read the agent files |
|
|
236
237
|
| `/exit` | Save the session and quit |
|
|
237
238
|
| `/clear` | Start a new session; the old one stays resumable |
|
|
238
239
|
| `/resume [<id>]` | Pick another session from this directory (or switch to the given one) |
|
|
@@ -247,6 +248,7 @@ In the TUI:
|
|
|
247
248
|
| `/context` | What fills the context window: system prompt, tools, MCP tools, project instructions, compaction summary and messages, with tokens, % and a bar |
|
|
248
249
|
| `/memory [project\|global]` | Edit `AGENTS.md` (this project's or `~/.dostuff/AGENTS.md`) in the same editor as `/config`; `Ctrl+S` saves and the agent follows it from the next message |
|
|
249
250
|
| `/doctor` | The `dostuff doctor` checks (config, API key, MCP config, memory, hooks), with a fix for each problem |
|
|
251
|
+
| `/tools` | Every tool the agent has: when it asks (in `ask` mode), whether subagents get it and what it does, then each connected MCP server's tools (reached through `call_mcp_tool`) |
|
|
250
252
|
| `/hooks [r]` | List the configured hooks per event: file, matcher, timeout, `fail_closed`, and whether each runs (`user` / `trusted` / `untrusted` / `disabled` / `broken`). `/hooks r` re-reads the config files. See [Hooks](#hooks) |
|
|
251
253
|
| `/queue` / `/queue clear` | List the prompts waiting for the current turn: edit one (back into the input), run it next or remove it / drop them all |
|
|
252
254
|
| `/jobs [<id>]` / `/jobs kill <id>` | List this session's background jobs (id, owner, status, runtime, command) / show a job's last 40 lines of output and its log files / stop one (the agent is told). See [Background jobs](#background-jobs) |
|
|
@@ -281,6 +283,8 @@ In the TUI:
|
|
|
281
283
|
|
|
282
284
|
## Tools and permissions
|
|
283
285
|
|
|
286
|
+
`/tools` lists these in the TUI, plus the tools of the connected MCP servers.
|
|
287
|
+
|
|
284
288
|
| Tool | Kind | Asks? |
|
|
285
289
|
| ---- | ---- | ----- |
|
|
286
290
|
| `read_file`, `list_files`, `grep`, `glob`, `get_current_datetime`, `search_mcp_tools`, `get_mcp_tool_details` | read | never |
|
|
@@ -290,9 +294,9 @@ In the TUI:
|
|
|
290
294
|
| `call_mcp_tool` | mcp | yes |
|
|
291
295
|
| `web_fetch` | network | yes; `a` (always) allows that domain for the session |
|
|
292
296
|
| `web_search` | network | yes; `a` (always) allows every search for the session. Free: DuckDuckGo by default, the `ddgs` package if installed (`pip install "dostuff[search]"`), or your own SearXNG via `search.searxng_url` |
|
|
293
|
-
| `
|
|
297
|
+
| `agent`, `send_message`, `stop_agent` | — | no; each subagent's own calls ask, titled with the agent |
|
|
294
298
|
| `read_settings` | read | never (MCP `env` / header values are shown as `<redacted>`) |
|
|
295
|
-
| `edit_config`, `set_mcp_server`, `remove_mcp_server` | settings | **always, in every mode, with no "always" option** (shows the diff or the server's command) |
|
|
299
|
+
| `edit_config`, `set_mcp_server`, `remove_mcp_server`, `create_agent_type` | settings | **always, in every mode, with no "always" option** (shows the diff or the server's command) |
|
|
296
300
|
|
|
297
301
|
File tools writing under a `.dostuff` directory, and `bash_command` calls whose command or `cwd` names `.dostuff`, are
|
|
298
302
|
settings changes too, so they always ask. That way auto mode can't quietly add a hook to `~/.dostuff/config.yaml`. Paths
|
|
@@ -392,6 +396,112 @@ paths). Directories older than 7 days are removed at startup.
|
|
|
392
396
|
|
|
393
397
|
---
|
|
394
398
|
|
|
399
|
+
## Subagents
|
|
400
|
+
|
|
401
|
+
A subagent is a separate agent with its own context, system prompt and tools. The main agent hands it a task with the
|
|
402
|
+
`agent` tool and gets one report back, so the searching, reading and trial and error stay out of the main
|
|
403
|
+
conversation. Several `agent` calls in one response run in parallel. The main agent follows up with `send_message`
|
|
404
|
+
and can stop one with `stop_agent`.
|
|
405
|
+
|
|
406
|
+
| Tool | What it does |
|
|
407
|
+
|---|---|
|
|
408
|
+
| `agent(description, prompt, subagent_type, model, run_in_background, isolation)` | Start an agent. `description` is 3–5 words for the UI; `prompt` is the whole task (the agent sees nothing else); `subagent_type` picks the type (default `general-purpose`); `model` overrides the type's; `isolation="worktree"` runs it in its own git worktree. The result is its report, ending with `agent_id: <id>` |
|
|
409
|
+
| `send_message(to, message, run_in_background)` | Continue an agent. One that has ended runs again with its whole history plus the message; one still running reads it before its next step |
|
|
410
|
+
| `stop_agent(agent_id)` | Stop a running agent; its shell jobs are killed and its worktree is closed out |
|
|
411
|
+
|
|
412
|
+
A subagent can never start, message or stop agents, delete files, save memories, write the todo list or change
|
|
413
|
+
settings, whatever its type asks for. At most `agents.max_concurrent` (4) run at once; more are queued.
|
|
414
|
+
|
|
415
|
+
### Agent types
|
|
416
|
+
|
|
417
|
+
| Type | Tools | For |
|
|
418
|
+
|---|---|---|
|
|
419
|
+
| `general-purpose` | every subagent tool | research and multi-step tasks, including changing files. The default |
|
|
420
|
+
| `explore` | read-only (its `bash_command` only runs read-only commands) | finding code and answering where things are; model: `agents.explore_model` |
|
|
421
|
+
| `plan` | read-only | investigating and returning a step-by-step plan |
|
|
422
|
+
| `fork` | the main agent's | a copy of the main agent that inherits the whole conversation (same system prompt, so a Claude model reuses the prompt cache). Costly: only when the task needs the conversation. Always the main model |
|
|
423
|
+
|
|
424
|
+
Your own types are Markdown files with YAML frontmatter. They are searched in this order, and the first file with a
|
|
425
|
+
given `name` wins: `.dostuff/agents/` and `.claude/agents/` in the project, then `~/.dostuff/agents/` and
|
|
426
|
+
`~/.claude/agents/`. `agents.read_claude_agents: false` skips both `.claude` folders. A file can replace a built-in
|
|
427
|
+
type, except `fork`. Files are re-read when they change; `/agents reload` forces it.
|
|
428
|
+
|
|
429
|
+
You can also ask the agent for one ("make a code-reviewer agent"): its `create_agent_type(name, description, prompt,
|
|
430
|
+
tools, model, max_iterations, scope, replace)` tool writes the file to `.dostuff/agents/` (`scope="user"`:
|
|
431
|
+
`~/.dostuff/agents/`) after showing it to you. Like the settings tools, it asks in every mode. The new type can be
|
|
432
|
+
started at once.
|
|
433
|
+
|
|
434
|
+
```markdown
|
|
435
|
+
---
|
|
436
|
+
name: code-reviewer
|
|
437
|
+
description: Reviews a diff for bugs and missing tests. Use after a change.
|
|
438
|
+
tools: Read, Grep, Glob, Bash # omit for every subagent tool
|
|
439
|
+
model: fast # inherit (default), an alias from agents.models, or a litellm model string
|
|
440
|
+
max_iterations: 30 # optional; default agents.max_iterations
|
|
441
|
+
---
|
|
442
|
+
You are a code reviewer. Report findings as a list, most severe first.
|
|
443
|
+
```
|
|
444
|
+
|
|
445
|
+
`tools:` takes DoStuff names or Claude Code's, so Claude Code agent files work unchanged:
|
|
446
|
+
|
|
447
|
+
| Claude Code | DoStuff |
|
|
448
|
+
|---|---|
|
|
449
|
+
| `Read` | `read_file` |
|
|
450
|
+
| `Write` | `write_file` |
|
|
451
|
+
| `Edit`, `MultiEdit` | `edit_file` |
|
|
452
|
+
| `Glob` / `Grep` / `LS` | `glob` / `grep` / `list_files` |
|
|
453
|
+
| `Bash` | `bash_command` (plus `bash_output`, `kill_shell`) |
|
|
454
|
+
| `WebFetch` / `WebSearch` | `web_fetch` / `web_search` |
|
|
455
|
+
| `mcp__*` | `search_mcp_tools`, `get_mcp_tool_details`, `call_mcp_tool` |
|
|
456
|
+
|
|
457
|
+
Unknown and forbidden names are dropped with a warning naming the file; `/agents types` lists each type with its
|
|
458
|
+
source, resolved model, tools and any warnings, and `/agents types <name>` shows one type's whole config: its
|
|
459
|
+
system prompt, model, tools and max iterations (for `fork`, the task message it gets). `model:` aliases come from `agents.models`; Claude Code's `sonnet`,
|
|
460
|
+
`opus` and `haiku` are looked up there too and fall back to the main model (with a warning in the report) when they
|
|
461
|
+
aren't defined. The call's `model=` wins over the type's `model:`.
|
|
462
|
+
|
|
463
|
+
### Background agents
|
|
464
|
+
|
|
465
|
+
With `run_in_background=true` the call returns the `agent_id` at once and the main agent keeps working. When the agent
|
|
466
|
+
ends, its report arrives as a `<background-agent id=… status=…>` message before the main agent's next model call, and
|
|
467
|
+
the TUI shows `⚙ agent "<description>" (<type>) finished after 2m 10s`. If the TUI is idle it starts a turn for it
|
|
468
|
+
(`agents.wake_on_end`, at most 3 automatic turns in a row together with background jobs). `Ctrl+B` moves running
|
|
469
|
+
foreground agents to the background. Approval prompts from a background agent are titled
|
|
470
|
+
`[agent: <description> · <type>]` and wait while you type. The status line shows `⚙ 2 agents` (or
|
|
471
|
+
`⚠ 1 agent waiting` for approval); click it for `/agents`.
|
|
472
|
+
|
|
473
|
+
`dostuff -p` waits for background agents and runs a turn on their reports before it prints the answer, for at most 3
|
|
474
|
+
such turns; agents still running then are stopped and named on stderr. `--output-format stream-json` prints an
|
|
475
|
+
`{"type": "agent", …}` event when an agent starts and when it ends.
|
|
476
|
+
|
|
477
|
+
Quitting asks before it stops running agents. `/clear` and `/resume` keep background agents running in the new
|
|
478
|
+
session.
|
|
479
|
+
|
|
480
|
+
### Transcripts and `/agents`
|
|
481
|
+
|
|
482
|
+
Every agent's steps are saved in the session database, apart from the main conversation. `/agents` lists this
|
|
483
|
+
session's agents (id, status, runtime, description and type, tokens, cost); pick one to read its whole transcript,
|
|
484
|
+
answer its approval prompt, stop it or show its type's system prompt and config. After a restart or `/resume` the agents come back as records (a run that was
|
|
485
|
+
going is `interrupted`) that `send_message` can continue.
|
|
486
|
+
|
|
487
|
+
### Hooks and config
|
|
488
|
+
|
|
489
|
+
`SubagentStart` fires when a run starts and can add context to its task; `SubagentStop` fires on its final answer.
|
|
490
|
+
Both match the agent type, and tool hooks inside an agent see `agent_id` and `agent_type`. See [Hooks](#hooks).
|
|
491
|
+
|
|
492
|
+
```yaml
|
|
493
|
+
agents:
|
|
494
|
+
max_iterations: 100 # model calls per run; default: the main agent's loop.max_iterations
|
|
495
|
+
max_concurrent: 4 # running or waiting for approval; more are queued
|
|
496
|
+
wake_on_end: true # a finished background agent resumes the idle TUI
|
|
497
|
+
read_claude_agents: true # also load .claude/agents/
|
|
498
|
+
explore_model: inherit # model of the built-in explore type
|
|
499
|
+
models: # aliases for model: and model=
|
|
500
|
+
fast: anthropic/claude-haiku-5-5
|
|
501
|
+
```
|
|
502
|
+
|
|
503
|
+
---
|
|
504
|
+
|
|
395
505
|
## Hooks
|
|
396
506
|
|
|
397
507
|
Hooks are shell commands DoStuff runs at fixed points of a session: block a tool call, feed a formatter's output back
|
|
@@ -410,7 +520,8 @@ matcher and tool argument names are renamed (see [the table below](#coming-from-
|
|
|
410
520
|
| `PreToolUse` | Before each tool call, before any approval prompt | the tool name | `allow`, `deny` or `ask`; rewrite the arguments |
|
|
411
521
|
| `PostToolUse` | After a tool call ran | the tool name | Append text to the result the model sees |
|
|
412
522
|
| `Stop` | When the agent is about to give its final answer | — | Block, so the turn continues with your reason |
|
|
413
|
-
| `
|
|
523
|
+
| `SubagentStart` | When a subagent run starts (an `agent` call, or a `send_message` that continues one) | the agent type | Add context to the run's task. Can't block |
|
|
524
|
+
| `SubagentStop` | Same as `Stop`, for a subagent's final answer | the agent type | Same as `Stop` |
|
|
414
525
|
|
|
415
526
|
### Config
|
|
416
527
|
|
|
@@ -515,6 +626,9 @@ worktree), with no terminal. stdin is one JSON object:
|
|
|
515
626
|
| `UserPromptSubmit` | `prompt` |
|
|
516
627
|
| `SessionStart` | `source` |
|
|
517
628
|
| `Stop`, `SubagentStop` | `last_assistant_message`, `stop_hook_active` (true once a Stop hook already continued this turn) |
|
|
629
|
+
| `SubagentStart` | `agent_id`, `agent_type`, `background`, `prompt` |
|
|
630
|
+
|
|
631
|
+
Inside a subagent, `PreToolUse`, `PostToolUse` and `SubagentStop` payloads also carry `agent_id` and `agent_type`.
|
|
518
632
|
|
|
519
633
|
The environment adds `DOSTUFF_HOOK_EVENT`, `DOSTUFF_SESSION_ID`, `DOSTUFF_TURN_ID`, `DOSTUFF_PROJECT_ROOT` and
|
|
520
634
|
`DOSTUFF_TURN_TYPE`. Output is capped at `loop.max_tool_output_chars`.
|
|
@@ -574,8 +688,8 @@ nesting are the same. Tool names and some argument names differ, so rename the m
|
|
|
574
688
|
| `Grep` / `Glob` | `grep` / `glob` | per tool |
|
|
575
689
|
| `mcp__<server>__<tool>` | `call_mcp_tool` | server and tool are inside `tool_input` |
|
|
576
690
|
|
|
577
|
-
Not supported yet: `http`, `prompt` and `agent` hook types, and the `Notification`, `PreCompact
|
|
578
|
-
|
|
691
|
+
Not supported yet: `http`, `prompt` and `agent` hook types, and the `Notification`, `PreCompact` and `SessionEnd`
|
|
692
|
+
events.
|
|
579
693
|
|
|
580
694
|
---
|
|
581
695
|
|
|
@@ -610,7 +724,6 @@ models:
|
|
|
610
724
|
|
|
611
725
|
loop:
|
|
612
726
|
max_iterations: 100
|
|
613
|
-
subagent_max_iterations: 25
|
|
614
727
|
# context_window: 128000 # override when dostuff/litellm don't know the model
|
|
615
728
|
max_tool_output_chars: 30000 # longer tool results keep head + tail
|
|
616
729
|
max_retries: 6 # retries on rate limits, timeouts, 5xx (0 = none)
|
|
@@ -622,6 +735,12 @@ memory:
|
|
|
622
735
|
permissions:
|
|
623
736
|
mode: ask # ask | allowlist | auto | plan
|
|
624
737
|
allow: []
|
|
738
|
+
|
|
739
|
+
agents: # see Subagents
|
|
740
|
+
max_iterations: 100 # model calls per run; default: loop.max_iterations (older: loop.subagent_max_iterations)
|
|
741
|
+
max_concurrent: 4
|
|
742
|
+
models:
|
|
743
|
+
fast: anthropic/claude-haiku-5-5
|
|
625
744
|
```
|
|
626
745
|
|
|
627
746
|
See [`config.example.yaml`](https://github.com/kVarunkk/DoStuff/blob/package-structure/dostuff/templates/config.example.yaml) for a full template. `dostuff setup` writes it for you.
|
|
@@ -933,7 +1052,9 @@ dostuff/
|
|
|
933
1052
|
│ ├── web_fetch.py # read a URL as text
|
|
934
1053
|
│ ├── web_search.py # free web search (SearXNG / ddgs / DuckDuckGo)
|
|
935
1054
|
│ ├── todo_write.py # visible task list
|
|
936
|
-
│
|
|
1055
|
+
│ ├── agent.py # the agent tool (subagents: dostuff/agent/subagents/)
|
|
1056
|
+
│ ├── create_agent_type.py # write a new agent type file
|
|
1057
|
+
│ └── send_message.py, stop_agent.py # continue or stop an agent
|
|
937
1058
|
├── cli.py # CLI typer entrypoints and doctor checkup utilities
|
|
938
1059
|
├── cli_tui.py # Textual TUI Application and adapter translates state
|
|
939
1060
|
├── config.py # layered config loader supporting project/global yaml and multi-model configuration
|
|
@@ -36,11 +36,11 @@ DoStuff is a terminal AI agent that runs anywhere `pip` runs. It gives you a ful
|
|
|
36
36
|
- **Project instructions** — `AGENTS.md` / `CLAUDE.md` from `~/.dostuff/`, the repo root and every folder down to the current one, combined
|
|
37
37
|
- **Coding tools** — `read_file` (line numbers, offset/limit), `edit_file` (exact replacement), `write_file`, `grep`, `glob`, `list_files`, `delete_file`, `bash_command`, `web_fetch` (read a URL as text), `web_search` (free, no API key)
|
|
38
38
|
- **Permission layer** — mutating tool calls ask for approval (allow once / always this session / deny with a note); read-only shell commands run without asking; modes `ask` / `allowlist` / `auto`; `/undo` reverts the agent's file changes
|
|
39
|
-
- **Hooks** — shell commands on `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop` and `SubagentStop` that can block a tool call or prompt, feed a formatter's output back to the model, or keep the turn going; Claude Code's hook I/O contract, and project hooks run only once you trust them. See [Hooks](#hooks)
|
|
39
|
+
- **Hooks** — shell commands on `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`, `SubagentStart` and `SubagentStop` that can block a tool call or prompt, feed a formatter's output back to the model, or keep the turn going; Claude Code's hook I/O contract, and project hooks run only once you trust them. See [Hooks](#hooks)
|
|
40
40
|
- **Background jobs** — `bash_command(run_in_background=true)` starts dev servers, watchers and long test runs as jobs the agent reads with `bash_output` (`wait_for` a ready line) and stops with `kill_shell`; it hears when one ends. `Ctrl+B` moves a running command to the background, `/jobs` lists them, and none outlives the session. See [Background jobs](#background-jobs)
|
|
41
41
|
- **File sandbox** — file tools stay inside the project directory and never read `.env*` files or `~/.dostuff/`
|
|
42
42
|
- **Skills loader** — drop a `SKILL.md` in the right folder, restart, done; run one with `/<skill-name> [args]`
|
|
43
|
-
- **Subagents** — `
|
|
43
|
+
- **Subagents** — the `agent` tool starts agents in parallel, in the foreground or the background, from built-in types (`explore`, `plan`, `general-purpose`), your own Markdown agent files (Claude Code's `.claude/agents/` work too) or a `fork` of the conversation; continue one with `send_message`, stop it with `stop_agent`, see them all in `/agents`. See [Subagents](#subagents)
|
|
44
44
|
- **Per-tool timeout** (120s) to prevent hung servers; long tool output is truncated (head + tail) before it reaches the model
|
|
45
45
|
- **Retries with backoff** for rate limits, timeouts and 5xx errors (6 by default, exponential with jitter, honors `Retry-After`; `loop.max_retries` / `loop.retry_max_delay`); auth / bad-request errors fail fast
|
|
46
46
|
- **Token and cost tracking** — per-turn and cumulative totals in `/status` and the line after each turn (`✻ Worked for 1m 5s · $0.01`); cost in USD from litellm's price table (hidden when the model has no known price). The table bundled with litellm is used, so startup doesn't wait on a download; set `LITELLM_LOCAL_MODEL_COST_MAP=False` to fetch the latest one from GitHub instead
|
|
@@ -182,9 +182,10 @@ In the TUI:
|
|
|
182
182
|
| `Ctrl+R` | Search the prompts typed in this directory (type to filter, `Enter` puts the prompt in the input) |
|
|
183
183
|
| `Esc` `Esc` | With an empty input: take back your last prompt. It and everything after it (answer, tool calls) leave the conversation and the prompt goes back in the input to edit and resend. Files that turn changed stay as they are; `/undo` restores them |
|
|
184
184
|
| `Ctrl+O` | Expand / collapse every truncated tool and shell result (click one to toggle just that one) |
|
|
185
|
-
| `Ctrl+B` | While the agent waits on a shell command (the loader says `Ctrl+B to background`): move
|
|
185
|
+
| `Ctrl+B` | While the agent waits on a shell command or a foreground subagent (the loader says `Ctrl+B to background`): move them to the background; the agent gets what a command printed so far and carries on, and hears from the agent when it ends. Not for `!command`s. See [Background jobs](#background-jobs) and [Subagents](#subagents) |
|
|
186
186
|
| `Shift+Tab` | Cycle the permission mode for this session: ask → auto → plan → allowlist (shown in the status bar) |
|
|
187
187
|
| `Ctrl+Backspace` / `Ctrl+W` / `Alt+Backspace` | Delete the previous word; `Ctrl+Delete` / `Alt+Delete` the next one |
|
|
188
|
+
| `/agents` / `/agents types` / `/agents reload` | This session's agents (running first): pick one to read its transcript, answer its approval prompt or stop it / the agent types with their source, model and tools (`/agents types <name>`: one type's system prompt and config) / re-read the agent files |
|
|
188
189
|
| `/exit` | Save the session and quit |
|
|
189
190
|
| `/clear` | Start a new session; the old one stays resumable |
|
|
190
191
|
| `/resume [<id>]` | Pick another session from this directory (or switch to the given one) |
|
|
@@ -199,6 +200,7 @@ In the TUI:
|
|
|
199
200
|
| `/context` | What fills the context window: system prompt, tools, MCP tools, project instructions, compaction summary and messages, with tokens, % and a bar |
|
|
200
201
|
| `/memory [project\|global]` | Edit `AGENTS.md` (this project's or `~/.dostuff/AGENTS.md`) in the same editor as `/config`; `Ctrl+S` saves and the agent follows it from the next message |
|
|
201
202
|
| `/doctor` | The `dostuff doctor` checks (config, API key, MCP config, memory, hooks), with a fix for each problem |
|
|
203
|
+
| `/tools` | Every tool the agent has: when it asks (in `ask` mode), whether subagents get it and what it does, then each connected MCP server's tools (reached through `call_mcp_tool`) |
|
|
202
204
|
| `/hooks [r]` | List the configured hooks per event: file, matcher, timeout, `fail_closed`, and whether each runs (`user` / `trusted` / `untrusted` / `disabled` / `broken`). `/hooks r` re-reads the config files. See [Hooks](#hooks) |
|
|
203
205
|
| `/queue` / `/queue clear` | List the prompts waiting for the current turn: edit one (back into the input), run it next or remove it / drop them all |
|
|
204
206
|
| `/jobs [<id>]` / `/jobs kill <id>` | List this session's background jobs (id, owner, status, runtime, command) / show a job's last 40 lines of output and its log files / stop one (the agent is told). See [Background jobs](#background-jobs) |
|
|
@@ -233,6 +235,8 @@ In the TUI:
|
|
|
233
235
|
|
|
234
236
|
## Tools and permissions
|
|
235
237
|
|
|
238
|
+
`/tools` lists these in the TUI, plus the tools of the connected MCP servers.
|
|
239
|
+
|
|
236
240
|
| Tool | Kind | Asks? |
|
|
237
241
|
| ---- | ---- | ----- |
|
|
238
242
|
| `read_file`, `list_files`, `grep`, `glob`, `get_current_datetime`, `search_mcp_tools`, `get_mcp_tool_details` | read | never |
|
|
@@ -242,9 +246,9 @@ In the TUI:
|
|
|
242
246
|
| `call_mcp_tool` | mcp | yes |
|
|
243
247
|
| `web_fetch` | network | yes; `a` (always) allows that domain for the session |
|
|
244
248
|
| `web_search` | network | yes; `a` (always) allows every search for the session. Free: DuckDuckGo by default, the `ddgs` package if installed (`pip install "dostuff[search]"`), or your own SearXNG via `search.searxng_url` |
|
|
245
|
-
| `
|
|
249
|
+
| `agent`, `send_message`, `stop_agent` | — | no; each subagent's own calls ask, titled with the agent |
|
|
246
250
|
| `read_settings` | read | never (MCP `env` / header values are shown as `<redacted>`) |
|
|
247
|
-
| `edit_config`, `set_mcp_server`, `remove_mcp_server` | settings | **always, in every mode, with no "always" option** (shows the diff or the server's command) |
|
|
251
|
+
| `edit_config`, `set_mcp_server`, `remove_mcp_server`, `create_agent_type` | settings | **always, in every mode, with no "always" option** (shows the diff or the server's command) |
|
|
248
252
|
|
|
249
253
|
File tools writing under a `.dostuff` directory, and `bash_command` calls whose command or `cwd` names `.dostuff`, are
|
|
250
254
|
settings changes too, so they always ask. That way auto mode can't quietly add a hook to `~/.dostuff/config.yaml`. Paths
|
|
@@ -344,6 +348,112 @@ paths). Directories older than 7 days are removed at startup.
|
|
|
344
348
|
|
|
345
349
|
---
|
|
346
350
|
|
|
351
|
+
## Subagents
|
|
352
|
+
|
|
353
|
+
A subagent is a separate agent with its own context, system prompt and tools. The main agent hands it a task with the
|
|
354
|
+
`agent` tool and gets one report back, so the searching, reading and trial and error stay out of the main
|
|
355
|
+
conversation. Several `agent` calls in one response run in parallel. The main agent follows up with `send_message`
|
|
356
|
+
and can stop one with `stop_agent`.
|
|
357
|
+
|
|
358
|
+
| Tool | What it does |
|
|
359
|
+
|---|---|
|
|
360
|
+
| `agent(description, prompt, subagent_type, model, run_in_background, isolation)` | Start an agent. `description` is 3–5 words for the UI; `prompt` is the whole task (the agent sees nothing else); `subagent_type` picks the type (default `general-purpose`); `model` overrides the type's; `isolation="worktree"` runs it in its own git worktree. The result is its report, ending with `agent_id: <id>` |
|
|
361
|
+
| `send_message(to, message, run_in_background)` | Continue an agent. One that has ended runs again with its whole history plus the message; one still running reads it before its next step |
|
|
362
|
+
| `stop_agent(agent_id)` | Stop a running agent; its shell jobs are killed and its worktree is closed out |
|
|
363
|
+
|
|
364
|
+
A subagent can never start, message or stop agents, delete files, save memories, write the todo list or change
|
|
365
|
+
settings, whatever its type asks for. At most `agents.max_concurrent` (4) run at once; more are queued.
|
|
366
|
+
|
|
367
|
+
### Agent types
|
|
368
|
+
|
|
369
|
+
| Type | Tools | For |
|
|
370
|
+
|---|---|---|
|
|
371
|
+
| `general-purpose` | every subagent tool | research and multi-step tasks, including changing files. The default |
|
|
372
|
+
| `explore` | read-only (its `bash_command` only runs read-only commands) | finding code and answering where things are; model: `agents.explore_model` |
|
|
373
|
+
| `plan` | read-only | investigating and returning a step-by-step plan |
|
|
374
|
+
| `fork` | the main agent's | a copy of the main agent that inherits the whole conversation (same system prompt, so a Claude model reuses the prompt cache). Costly: only when the task needs the conversation. Always the main model |
|
|
375
|
+
|
|
376
|
+
Your own types are Markdown files with YAML frontmatter. They are searched in this order, and the first file with a
|
|
377
|
+
given `name` wins: `.dostuff/agents/` and `.claude/agents/` in the project, then `~/.dostuff/agents/` and
|
|
378
|
+
`~/.claude/agents/`. `agents.read_claude_agents: false` skips both `.claude` folders. A file can replace a built-in
|
|
379
|
+
type, except `fork`. Files are re-read when they change; `/agents reload` forces it.
|
|
380
|
+
|
|
381
|
+
You can also ask the agent for one ("make a code-reviewer agent"): its `create_agent_type(name, description, prompt,
|
|
382
|
+
tools, model, max_iterations, scope, replace)` tool writes the file to `.dostuff/agents/` (`scope="user"`:
|
|
383
|
+
`~/.dostuff/agents/`) after showing it to you. Like the settings tools, it asks in every mode. The new type can be
|
|
384
|
+
started at once.
|
|
385
|
+
|
|
386
|
+
```markdown
|
|
387
|
+
---
|
|
388
|
+
name: code-reviewer
|
|
389
|
+
description: Reviews a diff for bugs and missing tests. Use after a change.
|
|
390
|
+
tools: Read, Grep, Glob, Bash # omit for every subagent tool
|
|
391
|
+
model: fast # inherit (default), an alias from agents.models, or a litellm model string
|
|
392
|
+
max_iterations: 30 # optional; default agents.max_iterations
|
|
393
|
+
---
|
|
394
|
+
You are a code reviewer. Report findings as a list, most severe first.
|
|
395
|
+
```
|
|
396
|
+
|
|
397
|
+
`tools:` takes DoStuff names or Claude Code's, so Claude Code agent files work unchanged:
|
|
398
|
+
|
|
399
|
+
| Claude Code | DoStuff |
|
|
400
|
+
|---|---|
|
|
401
|
+
| `Read` | `read_file` |
|
|
402
|
+
| `Write` | `write_file` |
|
|
403
|
+
| `Edit`, `MultiEdit` | `edit_file` |
|
|
404
|
+
| `Glob` / `Grep` / `LS` | `glob` / `grep` / `list_files` |
|
|
405
|
+
| `Bash` | `bash_command` (plus `bash_output`, `kill_shell`) |
|
|
406
|
+
| `WebFetch` / `WebSearch` | `web_fetch` / `web_search` |
|
|
407
|
+
| `mcp__*` | `search_mcp_tools`, `get_mcp_tool_details`, `call_mcp_tool` |
|
|
408
|
+
|
|
409
|
+
Unknown and forbidden names are dropped with a warning naming the file; `/agents types` lists each type with its
|
|
410
|
+
source, resolved model, tools and any warnings, and `/agents types <name>` shows one type's whole config: its
|
|
411
|
+
system prompt, model, tools and max iterations (for `fork`, the task message it gets). `model:` aliases come from `agents.models`; Claude Code's `sonnet`,
|
|
412
|
+
`opus` and `haiku` are looked up there too and fall back to the main model (with a warning in the report) when they
|
|
413
|
+
aren't defined. The call's `model=` wins over the type's `model:`.
|
|
414
|
+
|
|
415
|
+
### Background agents
|
|
416
|
+
|
|
417
|
+
With `run_in_background=true` the call returns the `agent_id` at once and the main agent keeps working. When the agent
|
|
418
|
+
ends, its report arrives as a `<background-agent id=… status=…>` message before the main agent's next model call, and
|
|
419
|
+
the TUI shows `⚙ agent "<description>" (<type>) finished after 2m 10s`. If the TUI is idle it starts a turn for it
|
|
420
|
+
(`agents.wake_on_end`, at most 3 automatic turns in a row together with background jobs). `Ctrl+B` moves running
|
|
421
|
+
foreground agents to the background. Approval prompts from a background agent are titled
|
|
422
|
+
`[agent: <description> · <type>]` and wait while you type. The status line shows `⚙ 2 agents` (or
|
|
423
|
+
`⚠ 1 agent waiting` for approval); click it for `/agents`.
|
|
424
|
+
|
|
425
|
+
`dostuff -p` waits for background agents and runs a turn on their reports before it prints the answer, for at most 3
|
|
426
|
+
such turns; agents still running then are stopped and named on stderr. `--output-format stream-json` prints an
|
|
427
|
+
`{"type": "agent", …}` event when an agent starts and when it ends.
|
|
428
|
+
|
|
429
|
+
Quitting asks before it stops running agents. `/clear` and `/resume` keep background agents running in the new
|
|
430
|
+
session.
|
|
431
|
+
|
|
432
|
+
### Transcripts and `/agents`
|
|
433
|
+
|
|
434
|
+
Every agent's steps are saved in the session database, apart from the main conversation. `/agents` lists this
|
|
435
|
+
session's agents (id, status, runtime, description and type, tokens, cost); pick one to read its whole transcript,
|
|
436
|
+
answer its approval prompt, stop it or show its type's system prompt and config. After a restart or `/resume` the agents come back as records (a run that was
|
|
437
|
+
going is `interrupted`) that `send_message` can continue.
|
|
438
|
+
|
|
439
|
+
### Hooks and config
|
|
440
|
+
|
|
441
|
+
`SubagentStart` fires when a run starts and can add context to its task; `SubagentStop` fires on its final answer.
|
|
442
|
+
Both match the agent type, and tool hooks inside an agent see `agent_id` and `agent_type`. See [Hooks](#hooks).
|
|
443
|
+
|
|
444
|
+
```yaml
|
|
445
|
+
agents:
|
|
446
|
+
max_iterations: 100 # model calls per run; default: the main agent's loop.max_iterations
|
|
447
|
+
max_concurrent: 4 # running or waiting for approval; more are queued
|
|
448
|
+
wake_on_end: true # a finished background agent resumes the idle TUI
|
|
449
|
+
read_claude_agents: true # also load .claude/agents/
|
|
450
|
+
explore_model: inherit # model of the built-in explore type
|
|
451
|
+
models: # aliases for model: and model=
|
|
452
|
+
fast: anthropic/claude-haiku-5-5
|
|
453
|
+
```
|
|
454
|
+
|
|
455
|
+
---
|
|
456
|
+
|
|
347
457
|
## Hooks
|
|
348
458
|
|
|
349
459
|
Hooks are shell commands DoStuff runs at fixed points of a session: block a tool call, feed a formatter's output back
|
|
@@ -362,7 +472,8 @@ matcher and tool argument names are renamed (see [the table below](#coming-from-
|
|
|
362
472
|
| `PreToolUse` | Before each tool call, before any approval prompt | the tool name | `allow`, `deny` or `ask`; rewrite the arguments |
|
|
363
473
|
| `PostToolUse` | After a tool call ran | the tool name | Append text to the result the model sees |
|
|
364
474
|
| `Stop` | When the agent is about to give its final answer | — | Block, so the turn continues with your reason |
|
|
365
|
-
| `
|
|
475
|
+
| `SubagentStart` | When a subagent run starts (an `agent` call, or a `send_message` that continues one) | the agent type | Add context to the run's task. Can't block |
|
|
476
|
+
| `SubagentStop` | Same as `Stop`, for a subagent's final answer | the agent type | Same as `Stop` |
|
|
366
477
|
|
|
367
478
|
### Config
|
|
368
479
|
|
|
@@ -467,6 +578,9 @@ worktree), with no terminal. stdin is one JSON object:
|
|
|
467
578
|
| `UserPromptSubmit` | `prompt` |
|
|
468
579
|
| `SessionStart` | `source` |
|
|
469
580
|
| `Stop`, `SubagentStop` | `last_assistant_message`, `stop_hook_active` (true once a Stop hook already continued this turn) |
|
|
581
|
+
| `SubagentStart` | `agent_id`, `agent_type`, `background`, `prompt` |
|
|
582
|
+
|
|
583
|
+
Inside a subagent, `PreToolUse`, `PostToolUse` and `SubagentStop` payloads also carry `agent_id` and `agent_type`.
|
|
470
584
|
|
|
471
585
|
The environment adds `DOSTUFF_HOOK_EVENT`, `DOSTUFF_SESSION_ID`, `DOSTUFF_TURN_ID`, `DOSTUFF_PROJECT_ROOT` and
|
|
472
586
|
`DOSTUFF_TURN_TYPE`. Output is capped at `loop.max_tool_output_chars`.
|
|
@@ -526,8 +640,8 @@ nesting are the same. Tool names and some argument names differ, so rename the m
|
|
|
526
640
|
| `Grep` / `Glob` | `grep` / `glob` | per tool |
|
|
527
641
|
| `mcp__<server>__<tool>` | `call_mcp_tool` | server and tool are inside `tool_input` |
|
|
528
642
|
|
|
529
|
-
Not supported yet: `http`, `prompt` and `agent` hook types, and the `Notification`, `PreCompact
|
|
530
|
-
|
|
643
|
+
Not supported yet: `http`, `prompt` and `agent` hook types, and the `Notification`, `PreCompact` and `SessionEnd`
|
|
644
|
+
events.
|
|
531
645
|
|
|
532
646
|
---
|
|
533
647
|
|
|
@@ -562,7 +676,6 @@ models:
|
|
|
562
676
|
|
|
563
677
|
loop:
|
|
564
678
|
max_iterations: 100
|
|
565
|
-
subagent_max_iterations: 25
|
|
566
679
|
# context_window: 128000 # override when dostuff/litellm don't know the model
|
|
567
680
|
max_tool_output_chars: 30000 # longer tool results keep head + tail
|
|
568
681
|
max_retries: 6 # retries on rate limits, timeouts, 5xx (0 = none)
|
|
@@ -574,6 +687,12 @@ memory:
|
|
|
574
687
|
permissions:
|
|
575
688
|
mode: ask # ask | allowlist | auto | plan
|
|
576
689
|
allow: []
|
|
690
|
+
|
|
691
|
+
agents: # see Subagents
|
|
692
|
+
max_iterations: 100 # model calls per run; default: loop.max_iterations (older: loop.subagent_max_iterations)
|
|
693
|
+
max_concurrent: 4
|
|
694
|
+
models:
|
|
695
|
+
fast: anthropic/claude-haiku-5-5
|
|
577
696
|
```
|
|
578
697
|
|
|
579
698
|
See [`config.example.yaml`](https://github.com/kVarunkk/DoStuff/blob/package-structure/dostuff/templates/config.example.yaml) for a full template. `dostuff setup` writes it for you.
|
|
@@ -885,7 +1004,9 @@ dostuff/
|
|
|
885
1004
|
│ ├── web_fetch.py # read a URL as text
|
|
886
1005
|
│ ├── web_search.py # free web search (SearXNG / ddgs / DuckDuckGo)
|
|
887
1006
|
│ ├── todo_write.py # visible task list
|
|
888
|
-
│
|
|
1007
|
+
│ ├── agent.py # the agent tool (subagents: dostuff/agent/subagents/)
|
|
1008
|
+
│ ├── create_agent_type.py # write a new agent type file
|
|
1009
|
+
│ └── send_message.py, stop_agent.py # continue or stop an agent
|
|
889
1010
|
├── cli.py # CLI typer entrypoints and doctor checkup utilities
|
|
890
1011
|
├── cli_tui.py # Textual TUI Application and adapter translates state
|
|
891
1012
|
├── config.py # layered config loader supporting project/global yaml and multi-model configuration
|
|
@@ -5,7 +5,7 @@ from typing import Any
|
|
|
5
5
|
|
|
6
6
|
from dostuff.config import get_config
|
|
7
7
|
from dostuff.helpers.agent.constants import (
|
|
8
|
-
BACKGROUND_WAIT_HEADLESS, BACKGROUND_WAIT_INTERACTIVE, MEMORY_INSTRUCTIONS, SYSTEM_INSTRUCTIONS,
|
|
8
|
+
AGENT_BACKGROUND, BACKGROUND_WAIT_HEADLESS, BACKGROUND_WAIT_INTERACTIVE, MEMORY_INSTRUCTIONS, SYSTEM_INSTRUCTIONS,
|
|
9
9
|
)
|
|
10
10
|
from dostuff.helpers.agent.environment_context import build_environment_block
|
|
11
11
|
from dostuff.helpers.agent.load_identity import load_identity
|
|
@@ -23,25 +23,47 @@ def _background_wait(interactive: bool) -> str:
|
|
|
23
23
|
return BACKGROUND_WAIT_INTERACTIVE if get_config().jobs_wake_on_end else ""
|
|
24
24
|
|
|
25
25
|
|
|
26
|
+
def skills_summary(skills: list[dict[str, Any]]) -> str:
|
|
27
|
+
"""The skills list as the system prompt shows it."""
|
|
28
|
+
summary = "\n\n".join(
|
|
29
|
+
f"- name: {s['name']}\n description: {s['description']}\n location: {s['location']}"
|
|
30
|
+
for s in skills
|
|
31
|
+
)
|
|
32
|
+
return summary or "(none available)"
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
def project_instructions_section(cwd: Path | None = None) -> str:
|
|
36
|
+
"""`## Project Instructions` + every applicable AGENTS.md / CLAUDE.md, or "" when there are none."""
|
|
37
|
+
project_instructions = load_project_instructions(cwd)
|
|
38
|
+
return "## Project Instructions\n" + project_instructions if project_instructions else ""
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def agent_types_list() -> str:
|
|
42
|
+
"""One ` - name: description` line per agent type, fork included (subagents spec D11, D13)."""
|
|
43
|
+
from dostuff.agent.subagents.definitions import current_definitions
|
|
44
|
+
from dostuff.agent.subagents.fork import FORK_DESCRIPTION, FORK_TYPE
|
|
45
|
+
descriptions = {name: d.description for name, d in current_definitions().types.items()}
|
|
46
|
+
descriptions[FORK_TYPE] = FORK_DESCRIPTION
|
|
47
|
+
return "\n".join(f" - {name}: {descriptions[name]}" for name in sorted(descriptions))
|
|
48
|
+
|
|
49
|
+
|
|
26
50
|
def build_base_instructions(interactive: bool = False) -> tuple[str, list[dict[str, Any]]]:
|
|
27
51
|
"""(identity + skills + project instructions, the skills found). Built once per session.
|
|
28
52
|
|
|
29
53
|
`interactive`: the TUI, which wakes the agent when a background job ends; headless doesn't.
|
|
30
54
|
"""
|
|
31
55
|
skills = discover_skills()
|
|
32
|
-
skills_summary = "\n\n".join(
|
|
33
|
-
f"- name: {s['name']}\n description: {s['description']}\n location: {s['location']}"
|
|
34
|
-
for s in skills
|
|
35
|
-
)
|
|
36
56
|
instructions = SYSTEM_INSTRUCTIONS.format(
|
|
37
57
|
dostuff_identity=load_identity(),
|
|
38
|
-
skills_summary=skills_summary
|
|
58
|
+
skills_summary=skills_summary(skills),
|
|
39
59
|
memory_section=MEMORY_INSTRUCTIONS if chroma.chroma_available() else "",
|
|
40
60
|
background_wait=_background_wait(interactive),
|
|
61
|
+
agent_types=agent_types_list(),
|
|
62
|
+
agent_background=AGENT_BACKGROUND if interactive or get_config().agents_wake_on_end else "",
|
|
41
63
|
)
|
|
42
|
-
|
|
43
|
-
if
|
|
44
|
-
instructions += "\n\n
|
|
64
|
+
project = project_instructions_section()
|
|
65
|
+
if project:
|
|
66
|
+
instructions += "\n\n" + project
|
|
45
67
|
return instructions, skills
|
|
46
68
|
|
|
47
69
|
|