dostuff 0.2.4__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.
Files changed (166) hide show
  1. {dostuff-0.2.4 → dostuff-0.2.6}/PKG-INFO +198 -12
  2. {dostuff-0.2.4 → dostuff-0.2.6}/README.md +197 -11
  3. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/agent/instructions.py +45 -9
  4. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/agent/loop.py +70 -19
  5. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/agent/permissions.py +7 -1
  6. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/agent/run_tool.py +20 -4
  7. dostuff-0.2.6/dostuff/agent/subagents/__init__.py +32 -0
  8. dostuff-0.2.6/dostuff/agent/subagents/adapter.py +103 -0
  9. dostuff-0.2.6/dostuff/agent/subagents/definitions.py +373 -0
  10. dostuff-0.2.6/dostuff/agent/subagents/fork.py +43 -0
  11. dostuff-0.2.6/dostuff/agent/subagents/prompt.py +53 -0
  12. dostuff-0.2.6/dostuff/agent/subagents/registry.py +576 -0
  13. dostuff-0.2.6/dostuff/agent/subagents/run.py +148 -0
  14. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/cli_tui.py +1141 -103
  15. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/config.py +54 -4
  16. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/headless.py +140 -20
  17. dostuff-0.2.6/dostuff/helpers/agent/append_step.py +13 -0
  18. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/agent/constants.py +70 -7
  19. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/agent/get_model_token_limit.py +4 -4
  20. dostuff-0.2.6/dostuff/helpers/agent/notices.py +132 -0
  21. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/agent/slash_suggestion.py +21 -1
  22. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/hooks/dispatch.py +9 -5
  23. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/hooks/events.py +26 -0
  24. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/hooks/load_hooks.py +2 -1
  25. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/hooks/run_hook.py +10 -1
  26. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/skills/discover_skills.py +17 -3
  27. dostuff-0.2.6/dostuff/helpers/ui/tools_listing.py +61 -0
  28. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/lib/memory/session_store.py +99 -5
  29. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/lib/model.py +23 -5
  30. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/templates/config.example.yaml +27 -4
  31. dostuff-0.2.6/dostuff/tools/agent.py +102 -0
  32. dostuff-0.2.6/dostuff/tools/bash/bash_command.py +227 -0
  33. dostuff-0.2.6/dostuff/tools/bash/bash_output.py +42 -0
  34. dostuff-0.2.6/dostuff/tools/bash/jobs.py +657 -0
  35. dostuff-0.2.6/dostuff/tools/bash/kill_shell.py +28 -0
  36. dostuff-0.2.6/dostuff/tools/create_agent_type.py +138 -0
  37. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/definitions.py +33 -9
  38. dostuff-0.2.6/dostuff/tools/names.py +16 -0
  39. dostuff-0.2.6/dostuff/tools/send_message.py +53 -0
  40. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/settings.py +8 -5
  41. dostuff-0.2.6/dostuff/tools/stop_agent.py +21 -0
  42. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff.egg-info/PKG-INFO +198 -12
  43. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff.egg-info/SOURCES.txt +27 -1
  44. {dostuff-0.2.4 → dostuff-0.2.6}/pyproject.toml +1 -1
  45. dostuff-0.2.6/tests/test_bash_command.py +381 -0
  46. {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_checkpoints_todos_caching.py +1 -1
  47. {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_cli_commands.py +199 -0
  48. {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_config_memory_mcp.py +64 -1
  49. dostuff-0.2.6/tests/test_create_agent_type.py +93 -0
  50. {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_hooks.py +201 -5
  51. dostuff-0.2.6/tests/test_jobs.py +753 -0
  52. {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_loop.py +2 -2
  53. {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_permissions.py +53 -0
  54. dostuff-0.2.6/tests/test_session_store.py +440 -0
  55. {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_settings_tools.py +1 -1
  56. dostuff-0.2.6/tests/test_skills_discovery.py +37 -0
  57. {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_slash_suggestion.py +18 -0
  58. dostuff-0.2.6/tests/test_subagent.py +174 -0
  59. dostuff-0.2.6/tests/test_subagents_background.py +510 -0
  60. dostuff-0.2.6/tests/test_subagents_fork.py +241 -0
  61. dostuff-0.2.6/tests/test_subagents_run.py +499 -0
  62. dostuff-0.2.6/tests/test_subagents_store.py +324 -0
  63. dostuff-0.2.6/tests/test_subagents_types.py +485 -0
  64. {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_tool_schemas.py +11 -2
  65. dostuff-0.2.6/tests/test_tools_listing.py +35 -0
  66. dostuff-0.2.6/tests/test_tui.py +3069 -0
  67. {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_worktree.py +26 -25
  68. dostuff-0.2.4/dostuff/helpers/agent/append_step.py +0 -11
  69. dostuff-0.2.4/dostuff/tools/bash/bash_command.py +0 -170
  70. dostuff-0.2.4/dostuff/tools/delegate_to_subagent.py +0 -258
  71. dostuff-0.2.4/tests/test_session_store.py +0 -179
  72. dostuff-0.2.4/tests/test_subagent.py +0 -82
  73. dostuff-0.2.4/tests/test_tui.py +0 -1511
  74. {dostuff-0.2.4 → dostuff-0.2.6}/LICENSE +0 -0
  75. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/__init__.py +0 -0
  76. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/__main__.py +0 -0
  77. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/agent/call_agent.py +0 -0
  78. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/cli.py +0 -0
  79. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/agent/consume_stream.py +0 -0
  80. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/agent/context_usage.py +0 -0
  81. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/agent/environment_context.py +0 -0
  82. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/agent/file_mentions.py +0 -0
  83. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/agent/load_identity.py +0 -0
  84. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/agent/load_project_instructions.py +0 -0
  85. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/agent/loop_check_cancelled.py +0 -0
  86. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/agent/loop_emit.py +0 -0
  87. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/agent/manage_context.py +0 -0
  88. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/agent/model_cost.py +0 -0
  89. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/agent/pastes.py +0 -0
  90. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/agent/quick_memory.py +0 -0
  91. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/agent/tool_output.py +0 -0
  92. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/hooks/__init__.py +0 -0
  93. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/hooks/trust.py +0 -0
  94. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/mcp/load_mcp_config.py +0 -0
  95. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/mcp/mcp_oauth.py +0 -0
  96. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/mcp/server_config.py +0 -0
  97. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/mcp/token_store.py +0 -0
  98. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/memory/export_session.py +0 -0
  99. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/memory/resolve_memory_operation.py +0 -0
  100. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/memory/shell_step.py +0 -0
  101. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/models/add_model_entry.py +0 -0
  102. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/models/list_models.py +0 -0
  103. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/models/opencode.py +0 -0
  104. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/skills/custom_commands.py +0 -0
  105. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/skills/skill_command.py +0 -0
  106. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/tools/diff.py +0 -0
  107. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/tools/generate_tool_schema.py +0 -0
  108. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/tools/project_root.py +0 -0
  109. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/tools/resolve_safe_path.py +0 -0
  110. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/ui/__init__.py +0 -0
  111. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/ui/doctor.py +0 -0
  112. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/ui/emit.py +0 -0
  113. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/ui/prompt_history.py +0 -0
  114. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/ui/terminal_signals.py +0 -0
  115. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/lib/checkpoints.py +0 -0
  116. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/lib/exceptions.py +0 -0
  117. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/lib/mcp/mcp_client.py +0 -0
  118. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/lib/mcp/mcp_client_registration_store.py +0 -0
  119. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/lib/mcp/mcp_tool_registry_store.py +0 -0
  120. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/lib/memory/chroma.py +0 -0
  121. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/lib/memory/episodic_memory_store.py +0 -0
  122. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/lib/memory/semantic_memory_store.py +0 -0
  123. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/lib/memory/stores.py +0 -0
  124. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/lib/memory/types.py +0 -0
  125. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/lib/tracing.py +0 -0
  126. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/lib/worktree.py +0 -0
  127. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/memory/__init__.py +0 -0
  128. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/setup_wizard.py +0 -0
  129. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/skills.py +0 -0
  130. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/templates/env.example +0 -0
  131. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/__init__.py +0 -0
  132. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/files/delete_file.py +0 -0
  133. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/files/edit_file.py +0 -0
  134. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/files/list_files.py +0 -0
  135. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/files/read_file.py +0 -0
  136. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/files/write_file.py +0 -0
  137. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/get_current_datetime.py +0 -0
  138. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/mcp/call_mcp_tool.py +0 -0
  139. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/mcp/get_mcp_tool_details.py +0 -0
  140. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/mcp/search_mcp_tools.py +0 -0
  141. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/memory/save_episode.py +0 -0
  142. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/memory/save_memory.py +0 -0
  143. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/search/glob.py +0 -0
  144. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/search/grep.py +0 -0
  145. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/search/walk.py +0 -0
  146. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/todo_write.py +0 -0
  147. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/web_fetch.py +0 -0
  148. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/web_search.py +0 -0
  149. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff.egg-info/dependency_links.txt +0 -0
  150. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff.egg-info/entry_points.txt +0 -0
  151. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff.egg-info/requires.txt +0 -0
  152. {dostuff-0.2.4 → dostuff-0.2.6}/dostuff.egg-info/top_level.txt +0 -0
  153. {dostuff-0.2.4 → dostuff-0.2.6}/setup.cfg +0 -0
  154. {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_file_mentions.py +0 -0
  155. {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_file_tools.py +0 -0
  156. {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_mcp_e2e.py +0 -0
  157. {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_mcp_oauth.py +0 -0
  158. {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_opencode.py +0 -0
  159. {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_optional_memory_and_instructions.py +0 -0
  160. {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_pastes.py +0 -0
  161. {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_roadmap_021.py +0 -0
  162. {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_setup_wizard.py +0 -0
  163. {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_skill_command.py +0 -0
  164. {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_terminal_signals.py +0 -0
  165. {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_web_fetch.py +0 -0
  166. {dostuff-0.2.4 → 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.4
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,10 +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
+ - **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)
88
89
  - **File sandbox** — file tools stay inside the project directory and never read `.env*` files or `~/.dostuff/`
89
90
  - **Skills loader** — drop a `SKILL.md` in the right folder, restart, done; run one with `/<skill-name> [args]`
90
- - **Subagents** — `delegate_to_subagent` runs a bounded task with a restricted tool set; its approval prompts and ESC go through the same TUI
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)
91
92
  - **Per-tool timeout** (120s) to prevent hung servers; long tool output is truncated (head + tail) before it reaches the model
92
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
93
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
@@ -229,8 +230,10 @@ In the TUI:
229
230
  | `Ctrl+R` | Search the prompts typed in this directory (type to filter, `Enter` puts the prompt in the input) |
230
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 |
231
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 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) |
232
234
  | `Shift+Tab` | Cycle the permission mode for this session: ask → auto → plan → allowlist (shown in the status bar) |
233
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 |
234
237
  | `/exit` | Save the session and quit |
235
238
  | `/clear` | Start a new session; the old one stays resumable |
236
239
  | `/resume [<id>]` | Pick another session from this directory (or switch to the given one) |
@@ -245,7 +248,10 @@ In the TUI:
245
248
  | `/context` | What fills the context window: system prompt, tools, MCP tools, project instructions, compaction summary and messages, with tokens, % and a bar |
246
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 |
247
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`) |
248
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) |
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 |
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) |
249
255
  | `/<skill> [args]` | Run a skill: every discovered skill is a command (listed in the `/` menu and `/help`). See [Skills](#skills) |
250
256
  | `/<command> [args]` | Run a custom command from `.dostuff/commands/` or `~/.dostuff/commands/`. See [Custom commands](#custom-commands) |
251
257
  | `/rename <title>` | Name this session (shown by `dostuff sessions`) |
@@ -267,7 +273,9 @@ In the TUI:
267
273
  - **Diffs** — `write_file` / `edit_file` changes shown as a coloured diff
268
274
  - **Errors** — red background
269
275
  - **Status bar** — `cwd • model • permission mode • context usage %` by default; `help`, `session`, `tokens` and `cost` can be added. Choose and order the items with `ui.status_bar` in `config.yaml`; when the terminal is too narrow (or zoomed in), long items are shortened and the least important dropped (help, session, cwd, tokens, cost, model, context, mode) instead of being cut off
276
+ - **Shells** — while background jobs run, a `⚙ 2 shells` item sits at the end of the status bar whatever `ui.status_bar` says. Click it (or press `↓` in an empty input) to list the session's jobs with when each started and how long it has run, and click it again to close the list; pick one (click or Enter) to see its last 8 lines of output and log path in the same small panel, refresh them, or stop it
270
277
  - **Loading** — bold `Working...` with a live elapsed timer and queued-prompt count, or streamed thoughts displayed live
278
+ - **Queued prompts** — prompts sent while a turn runs wait above the input, one row each, and run in order. Click the list (or `/queue`) to pick one and edit it (back into the input), run it next or remove it, or clear them all (`/queue clear`). `Esc` cancels the turn and moves the queued prompts back into the input instead of running them
271
279
  - **Terminal title** — the tab / window title shows the run status: `⏳ dostuff · <folder>` while working, `✋` while an approval waits, `✓` when done; the old title comes back on exit. `ui.terminal_title: false` turns it off
272
280
  - **Notifications** (off by default) — `ui.notifications: bell` (terminal bell) or `osc9` (desktop notification in iTerm2, WezTerm, Ghostty, kitty …) when a turn finishes or an approval is waiting, if it took longer than `ui.notify_after_seconds` (30) or the terminal is in the background. `/notifications` switches it per session
273
281
 
@@ -275,17 +283,20 @@ In the TUI:
275
283
 
276
284
  ## Tools and permissions
277
285
 
286
+ `/tools` lists these in the TUI, plus the tools of the connected MCP servers.
287
+
278
288
  | Tool | Kind | Asks? |
279
289
  | ---- | ---- | ----- |
280
290
  | `read_file`, `list_files`, `grep`, `glob`, `get_current_datetime`, `search_mcp_tools`, `get_mcp_tool_details` | read | never |
291
+ | `bash_output`, `kill_shell` | read | never (they only touch the agent's own background jobs) |
281
292
  | `write_file`, `edit_file`, `delete_file` | write | yes (shows a diff) |
282
293
  | `bash_command` | shell | yes, unless every part of the command is on the read-only allow-list (`ls`, `cat`, `git status`, `git diff`, …) with no redirection or substitution |
283
294
  | `call_mcp_tool` | mcp | yes |
284
295
  | `web_fetch` | network | yes; `a` (always) allows that domain for the session |
285
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` |
286
- | `delegate_to_subagent` | — | no; the subagent's own calls ask |
297
+ | `agent`, `send_message`, `stop_agent` | — | no; each subagent's own calls ask, titled with the agent |
287
298
  | `read_settings` | read | never (MCP `env` / header values are shown as `<redacted>`) |
288
- | `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) |
289
300
 
290
301
  File tools writing under a `.dostuff` directory, and `bash_command` calls whose command or `cwd` names `.dostuff`, are
291
302
  settings changes too, so they always ask. That way auto mode can't quietly add a hook to `~/.dostuff/config.yaml`. Paths
@@ -321,12 +332,176 @@ API keys stay in `.env` files, which the agent can't read or change. Subagents d
321
332
 
322
333
  > [!NOTE]
323
334
  > **Cancelling a running tool.** ESC stops waiting for tools at once and the turn ends; results that already
324
- > finished are kept. Tools that run in a worker thread (file tools, `bash_command`) cannot be interrupted
325
- > mid-call, so one that was still running may finish in the background; its result is recorded as
335
+ > finished are kept. A running `bash_command` is killed with its children; tools that run in a worker thread (file tools) cannot
336
+ > be interrupted mid-call, so one that was still running may finish in the background; its result is recorded as
326
337
  > `Cancelled by user (may still be running)`.
327
338
 
328
339
  ---
329
340
 
341
+ ## Background jobs
342
+
343
+ Dev servers, file watchers and long test runs don't fit a shell call that has to finish within its timeout. The agent
344
+ starts them as **background jobs** instead and keeps working while they run:
345
+
346
+ | Tool | What it does |
347
+ |---|---|
348
+ | `bash_command(command, run_in_background=true, background_id="dev")` | Starts the job and returns at once with its id, pid and log files. `background_id` is optional (`bg-1`, `bg-2`, … otherwise); starting an id that is still running is refused. At most 8 running jobs per agent |
349
+ | `bash_output("dev", filter=…, wait_for=…, timeout=…)` | The job's status and the stdout / stderr it printed since the last read. `wait_for` is a regex: wait (1–110 s) until a new line matches, e.g. a server's `ready` line, instead of sleeping. `filter` keeps only matching lines |
350
+ | `kill_shell("dev")` | Kills the job and everything it started, and shows its last lines |
351
+
352
+ The approval prompt for a background start reads `Run shell command (background job "dev"):`; `bash_output` and
353
+ `kill_shell` never ask, because they only reach the calling agent's own jobs. Hooks see `run_in_background` and
354
+ `background_id` in `PreToolUse`, and can deny `kill_shell` like any tool. Plan mode allows a background job only for a
355
+ read-only command.
356
+
357
+ **When a job ends** on its own (or you stop it with `/jobs kill`), the agent is told before its next model call with a
358
+ `<background-job id="test" status="exited" code="1" runtime="42s">` message holding the last 20 lines of each stream,
359
+ so it doesn't have to poll to notice a crashed server. In the TUI the same moment shows as `⚙ job "test" exited (1)
360
+ after 42s`, with a notification when the terminal is in the background (`ui.notifications`). If the agent is idle,
361
+ the TUI starts a turn for it right away (`⚙ Resuming the agent: …`), so it can look at the failed test run or crashed
362
+ server on its own. It waits while you are typing, an approval is open or a command like `/compact` runs; if you send a
363
+ prompt first, that turn gets the message instead. A `/jobs kill` alone doesn't wake it, and after 3 such automatic
364
+ turns in a row it waits for your next message. Turn this off with `jobs: {wake_on_end: false}` in `config.yaml`; the
365
+ agent then sees the message with your next prompt.
366
+
367
+ **In the TUI:**
368
+
369
+ - `Ctrl+B` while the agent waits on a shell command (the loader says `Ctrl+B to background`) moves that command, and
370
+ any a subagent is running in the same turn, to the background. The agent gets what it printed so far and carries on;
371
+ the transcript shows `⎿ moved to background as "bg-3"`. `!command`s can't be backgrounded.
372
+ - `/jobs` lists the session's jobs: id, owner (`main` or `subagent: <role>`), status, runtime and command.
373
+ `/jobs <id>` shows the last 40 lines of each stream and the log paths, `/jobs kill <id>` stops one.
374
+ - While any run, a `⚙ 2 shells` item shows at the end of the status bar; click it (or `↓` in an empty input) to pick a job
375
+ from a list (status, start time, runtime, command) and show its output or stop it.
376
+
377
+ **Logs** go to `~/.dostuff/jobs/<session>/<job>.out` and `.err` (you can `tail -f` them; `/jobs <id>` prints the
378
+ paths). Directories older than 7 days are removed at startup.
379
+
380
+ **Jobs live until their owner ends; in the TUI that is the app, not the conversation:**
381
+
382
+ | Event | What happens to the jobs |
383
+ |---|---|
384
+ | Subagent run ends (done, error or cancelled) | its jobs are killed |
385
+ | `/compact` | kept |
386
+ | `/clear` | kept, no prompt: they move to the new session, which gets their end notices and can use `bash_output`/`kill_shell` on them |
387
+ | `/resume` another session | same as `/clear`: the running jobs follow you into the resumed session |
388
+ | Quit (`Ctrl+Q`, `/exit`) | "Quit and stop 2 background jobs?", then they are killed |
389
+ | Headless run (`dostuff -p`) ends, or `Ctrl+C` | all killed, one stderr line each (`stream-json`: `{"type": "job", …}` events) |
390
+
391
+ > [!WARNING]
392
+ > If DoStuff is killed hard (task manager, `kill -9`, power loss), its jobs keep running: they are detached from the
393
+ > terminal by design. Each session records its jobs in `~/.dostuff/jobs/<session>/jobs.json`, and the next start
394
+ > warns `1 background job from an earlier session may still be running (npm run dev, pid 4812)`. It doesn't kill
395
+ > them, since a pid may have been reused by then; check with your OS tools.
396
+
397
+ ---
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
+
330
505
  ## Hooks
331
506
 
332
507
  Hooks are shell commands DoStuff runs at fixed points of a session: block a tool call, feed a formatter's output back
@@ -345,7 +520,8 @@ matcher and tool argument names are renamed (see [the table below](#coming-from-
345
520
  | `PreToolUse` | Before each tool call, before any approval prompt | the tool name | `allow`, `deny` or `ask`; rewrite the arguments |
346
521
  | `PostToolUse` | After a tool call ran | the tool name | Append text to the result the model sees |
347
522
  | `Stop` | When the agent is about to give its final answer | — | Block, so the turn continues with your reason |
348
- | `SubagentStop` | Same, for a `delegate_to_subagent` run | — | Same |
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` |
349
525
 
350
526
  ### Config
351
527
 
@@ -450,6 +626,9 @@ worktree), with no terminal. stdin is one JSON object:
450
626
  | `UserPromptSubmit` | `prompt` |
451
627
  | `SessionStart` | `source` |
452
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`.
453
632
 
454
633
  The environment adds `DOSTUFF_HOOK_EVENT`, `DOSTUFF_SESSION_ID`, `DOSTUFF_TURN_ID`, `DOSTUFF_PROJECT_ROOT` and
455
634
  `DOSTUFF_TURN_TYPE`. Output is capped at `loop.max_tool_output_chars`.
@@ -509,8 +688,8 @@ nesting are the same. Tool names and some argument names differ, so rename the m
509
688
  | `Grep` / `Glob` | `grep` / `glob` | per tool |
510
689
  | `mcp__<server>__<tool>` | `call_mcp_tool` | server and tool are inside `tool_input` |
511
690
 
512
- Not supported yet: `http`, `prompt` and `agent` hook types, and the `Notification`, `PreCompact`, `SessionEnd` and
513
- `SubagentStart` events.
691
+ Not supported yet: `http`, `prompt` and `agent` hook types, and the `Notification`, `PreCompact` and `SessionEnd`
692
+ events.
514
693
 
515
694
  ---
516
695
 
@@ -545,7 +724,6 @@ models:
545
724
 
546
725
  loop:
547
726
  max_iterations: 100
548
- subagent_max_iterations: 25
549
727
  # context_window: 128000 # override when dostuff/litellm don't know the model
550
728
  max_tool_output_chars: 30000 # longer tool results keep head + tail
551
729
  max_retries: 6 # retries on rate limits, timeouts, 5xx (0 = none)
@@ -557,6 +735,12 @@ memory:
557
735
  permissions:
558
736
  mode: ask # ask | allowlist | auto | plan
559
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
560
744
  ```
561
745
 
562
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.
@@ -868,7 +1052,9 @@ dostuff/
868
1052
  │ ├── web_fetch.py # read a URL as text
869
1053
  │ ├── web_search.py # free web search (SearXNG / ddgs / DuckDuckGo)
870
1054
  │ ├── todo_write.py # visible task list
871
- │ └── delegate_to_subagent.py # bounded subagents (optionally in a worktree)
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
872
1058
  ├── cli.py # CLI typer entrypoints and doctor checkup utilities
873
1059
  ├── cli_tui.py # Textual TUI Application and adapter translates state
874
1060
  ├── config.py # layered config loader supporting project/global yaml and multi-model configuration