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.
- {dostuff-0.2.4 → dostuff-0.2.6}/PKG-INFO +198 -12
- {dostuff-0.2.4 → dostuff-0.2.6}/README.md +197 -11
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/agent/instructions.py +45 -9
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/agent/loop.py +70 -19
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/agent/permissions.py +7 -1
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/agent/run_tool.py +20 -4
- 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.4 → dostuff-0.2.6}/dostuff/cli_tui.py +1141 -103
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/config.py +54 -4
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/headless.py +140 -20
- dostuff-0.2.6/dostuff/helpers/agent/append_step.py +13 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/agent/constants.py +70 -7
- {dostuff-0.2.4 → 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.4 → dostuff-0.2.6}/dostuff/helpers/agent/slash_suggestion.py +21 -1
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/hooks/dispatch.py +9 -5
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/hooks/events.py +26 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/hooks/load_hooks.py +2 -1
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/hooks/run_hook.py +10 -1
- {dostuff-0.2.4 → 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.4 → dostuff-0.2.6}/dostuff/lib/memory/session_store.py +99 -5
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/lib/model.py +23 -5
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/templates/config.example.yaml +27 -4
- dostuff-0.2.6/dostuff/tools/agent.py +102 -0
- dostuff-0.2.6/dostuff/tools/bash/bash_command.py +227 -0
- dostuff-0.2.6/dostuff/tools/bash/bash_output.py +42 -0
- dostuff-0.2.6/dostuff/tools/bash/jobs.py +657 -0
- dostuff-0.2.6/dostuff/tools/bash/kill_shell.py +28 -0
- dostuff-0.2.6/dostuff/tools/create_agent_type.py +138 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/definitions.py +33 -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.4 → dostuff-0.2.6}/dostuff/tools/settings.py +8 -5
- dostuff-0.2.6/dostuff/tools/stop_agent.py +21 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff.egg-info/PKG-INFO +198 -12
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff.egg-info/SOURCES.txt +27 -1
- {dostuff-0.2.4 → dostuff-0.2.6}/pyproject.toml +1 -1
- dostuff-0.2.6/tests/test_bash_command.py +381 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_checkpoints_todos_caching.py +1 -1
- {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_cli_commands.py +199 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_config_memory_mcp.py +64 -1
- dostuff-0.2.6/tests/test_create_agent_type.py +93 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_hooks.py +201 -5
- dostuff-0.2.6/tests/test_jobs.py +753 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_loop.py +2 -2
- {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_permissions.py +53 -0
- dostuff-0.2.6/tests/test_session_store.py +440 -0
- {dostuff-0.2.4 → 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.4 → 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.4 → dostuff-0.2.6}/tests/test_tool_schemas.py +11 -2
- dostuff-0.2.6/tests/test_tools_listing.py +35 -0
- dostuff-0.2.6/tests/test_tui.py +3069 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_worktree.py +26 -25
- dostuff-0.2.4/dostuff/helpers/agent/append_step.py +0 -11
- dostuff-0.2.4/dostuff/tools/bash/bash_command.py +0 -170
- dostuff-0.2.4/dostuff/tools/delegate_to_subagent.py +0 -258
- dostuff-0.2.4/tests/test_session_store.py +0 -179
- dostuff-0.2.4/tests/test_subagent.py +0 -82
- dostuff-0.2.4/tests/test_tui.py +0 -1511
- {dostuff-0.2.4 → dostuff-0.2.6}/LICENSE +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/__init__.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/__main__.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/agent/call_agent.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/cli.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/agent/consume_stream.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/agent/context_usage.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/agent/environment_context.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/agent/file_mentions.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/agent/load_identity.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/agent/load_project_instructions.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/agent/loop_check_cancelled.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/agent/loop_emit.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/agent/manage_context.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/agent/model_cost.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/agent/pastes.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/agent/quick_memory.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/agent/tool_output.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/hooks/__init__.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/hooks/trust.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/mcp/load_mcp_config.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/mcp/mcp_oauth.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/mcp/server_config.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/mcp/token_store.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/memory/export_session.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/memory/resolve_memory_operation.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/memory/shell_step.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/models/add_model_entry.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/models/list_models.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/models/opencode.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/skills/custom_commands.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/skills/skill_command.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/tools/diff.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/tools/generate_tool_schema.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/tools/project_root.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/tools/resolve_safe_path.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/ui/__init__.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/ui/doctor.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/ui/emit.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/ui/prompt_history.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/helpers/ui/terminal_signals.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/lib/checkpoints.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/lib/exceptions.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/lib/mcp/mcp_client.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/lib/mcp/mcp_client_registration_store.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/lib/mcp/mcp_tool_registry_store.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/lib/memory/chroma.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/lib/memory/episodic_memory_store.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/lib/memory/semantic_memory_store.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/lib/memory/stores.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/lib/memory/types.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/lib/tracing.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/lib/worktree.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/memory/__init__.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/setup_wizard.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/skills.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/templates/env.example +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/__init__.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/files/delete_file.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/files/edit_file.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/files/list_files.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/files/read_file.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/files/write_file.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/get_current_datetime.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/mcp/call_mcp_tool.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/mcp/get_mcp_tool_details.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/mcp/search_mcp_tools.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/memory/save_episode.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/memory/save_memory.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/search/glob.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/search/grep.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/search/walk.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/todo_write.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/web_fetch.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff/tools/web_search.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff.egg-info/dependency_links.txt +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff.egg-info/entry_points.txt +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff.egg-info/requires.txt +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/dostuff.egg-info/top_level.txt +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/setup.cfg +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_file_mentions.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_file_tools.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_mcp_e2e.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_mcp_oauth.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_opencode.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_optional_memory_and_instructions.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_pastes.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_roadmap_021.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_setup_wizard.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_skill_command.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_terminal_signals.py +0 -0
- {dostuff-0.2.4 → dostuff-0.2.6}/tests/test_web_fetch.py +0 -0
- {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.
|
|
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** — `
|
|
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
|
-
| `
|
|
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.
|
|
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
|
-
| `
|
|
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
|
|
513
|
-
|
|
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
|
-
│
|
|
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
|