dostuff 0.2.3__tar.gz → 0.2.5__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.3 → dostuff-0.2.5}/PKG-INFO +264 -5
- {dostuff-0.2.3 → dostuff-0.2.5}/README.md +263 -4
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/agent/instructions.py +17 -3
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/agent/loop.py +96 -12
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/agent/permissions.py +34 -3
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/agent/run_tool.py +109 -13
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/cli.py +6 -3
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/cli_tui.py +732 -73
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/config.py +50 -4
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/headless.py +54 -1
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/agent/constants.py +18 -3
- dostuff-0.2.5/dostuff/helpers/hooks/__init__.py +10 -0
- dostuff-0.2.5/dostuff/helpers/hooks/dispatch.py +141 -0
- dostuff-0.2.5/dostuff/helpers/hooks/events.py +84 -0
- dostuff-0.2.5/dostuff/helpers/hooks/load_hooks.py +248 -0
- dostuff-0.2.5/dostuff/helpers/hooks/run_hook.py +186 -0
- dostuff-0.2.5/dostuff/helpers/hooks/trust.py +157 -0
- dostuff-0.2.5/dostuff/helpers/ui/doctor.py +191 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/templates/config.example.yaml +50 -2
- dostuff-0.2.5/dostuff/tools/bash/bash_command.py +227 -0
- dostuff-0.2.5/dostuff/tools/bash/bash_output.py +42 -0
- dostuff-0.2.5/dostuff/tools/bash/jobs.py +653 -0
- dostuff-0.2.5/dostuff/tools/bash/kill_shell.py +28 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/definitions.py +19 -1
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/delegate_to_subagent.py +15 -4
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/settings.py +13 -4
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff.egg-info/PKG-INFO +264 -5
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff.egg-info/SOURCES.txt +12 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/pyproject.toml +1 -1
- dostuff-0.2.5/tests/test_bash_command.py +379 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_cli_commands.py +152 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_config_memory_mcp.py +9 -0
- dostuff-0.2.5/tests/test_hooks.py +1683 -0
- dostuff-0.2.5/tests/test_jobs.py +751 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_permissions.py +77 -0
- dostuff-0.2.5/tests/test_subagent.py +164 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_tool_schemas.py +1 -1
- dostuff-0.2.5/tests/test_tui.py +2330 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_worktree.py +1 -1
- dostuff-0.2.3/dostuff/helpers/ui/doctor.py +0 -47
- dostuff-0.2.3/dostuff/tools/bash/bash_command.py +0 -170
- dostuff-0.2.3/tests/test_subagent.py +0 -82
- dostuff-0.2.3/tests/test_tui.py +0 -1197
- {dostuff-0.2.3 → dostuff-0.2.5}/LICENSE +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/__init__.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/__main__.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/agent/call_agent.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/agent/append_step.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/agent/consume_stream.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/agent/context_usage.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/agent/environment_context.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/agent/file_mentions.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/agent/get_model_token_limit.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/agent/load_identity.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/agent/load_project_instructions.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/agent/loop_check_cancelled.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/agent/loop_emit.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/agent/manage_context.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/agent/model_cost.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/agent/pastes.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/agent/quick_memory.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/agent/slash_suggestion.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/agent/tool_output.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/mcp/load_mcp_config.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/mcp/mcp_oauth.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/mcp/server_config.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/mcp/token_store.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/memory/export_session.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/memory/resolve_memory_operation.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/memory/shell_step.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/models/add_model_entry.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/models/list_models.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/models/opencode.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/skills/custom_commands.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/skills/discover_skills.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/skills/skill_command.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/tools/diff.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/tools/generate_tool_schema.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/tools/project_root.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/tools/resolve_safe_path.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/ui/__init__.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/ui/emit.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/ui/prompt_history.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/helpers/ui/terminal_signals.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/lib/checkpoints.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/lib/exceptions.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/lib/mcp/mcp_client.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/lib/mcp/mcp_client_registration_store.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/lib/mcp/mcp_tool_registry_store.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/lib/memory/chroma.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/lib/memory/episodic_memory_store.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/lib/memory/semantic_memory_store.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/lib/memory/session_store.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/lib/memory/stores.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/lib/memory/types.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/lib/model.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/lib/tracing.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/lib/worktree.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/memory/__init__.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/setup_wizard.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/skills.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/templates/env.example +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/__init__.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/files/delete_file.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/files/edit_file.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/files/list_files.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/files/read_file.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/files/write_file.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/get_current_datetime.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/mcp/call_mcp_tool.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/mcp/get_mcp_tool_details.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/mcp/search_mcp_tools.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/memory/save_episode.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/memory/save_memory.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/search/glob.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/search/grep.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/search/walk.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/todo_write.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/web_fetch.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff/tools/web_search.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff.egg-info/dependency_links.txt +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff.egg-info/entry_points.txt +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff.egg-info/requires.txt +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/dostuff.egg-info/top_level.txt +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/setup.cfg +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_checkpoints_todos_caching.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_file_mentions.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_file_tools.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_loop.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_mcp_e2e.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_mcp_oauth.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_opencode.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_optional_memory_and_instructions.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_pastes.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_roadmap_021.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_session_store.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_settings_tools.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_setup_wizard.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_skill_command.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_slash_suggestion.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_terminal_signals.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/tests/test_web_fetch.py +0 -0
- {dostuff-0.2.3 → dostuff-0.2.5}/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.5
|
|
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,6 +84,8 @@ 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)
|
|
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)
|
|
87
89
|
- **File sandbox** — file tools stay inside the project directory and never read `.env*` files or `~/.dostuff/`
|
|
88
90
|
- **Skills loader** — drop a `SKILL.md` in the right folder, restart, done; run one with `/<skill-name> [args]`
|
|
89
91
|
- **Subagents** — `delegate_to_subagent` runs a bounded task with a restricted tool set; its approval prompts and ESC go through the same TUI
|
|
@@ -203,7 +205,7 @@ In the TUI:
|
|
|
203
205
|
| `dostuff sessions rm <id>... [-y]` | Delete sessions and their `/undo` checkpoints |
|
|
204
206
|
| `dostuff sessions prune [--older-than 30d] [--dry-run] [-y]` | Delete empty sessions, and sessions not used for the given time (`45m`, `12h`, `30d`, `2w`) |
|
|
205
207
|
| `dostuff export [<id>] [-o file\|-]` | Save a session (default: latest here) as Markdown: prompts, answers, tool calls and results |
|
|
206
|
-
| `dostuff -p "<prompt>"` | Headless: run one prompt, print the answer to stdout, exit. Progress goes to stderr. Piped stdin is appended to the prompt (`-p -` reads the prompt from stdin). `--session <id>` continues a session, `--output-format json` (or `--json`) prints `{result, session_id, usage, ...}`, `--output-format stream-json` prints one JSON event per line (`init`, `assistant`, `tool_call`, `tool_result`, `usage`, `error`, then `result`), `-q` hides progress, `--permission-mode ask\|allowlist\|auto\|plan`. `--max-turns N` stops after N model calls (exit code 1). `--allowed-tools` (comma-separated or repeated) runs matching calls without asking in any mode, in the `permissions.allow` syntax (`"npm test"`, `web_fetch:docs.python.org`) or a tool name for every call of it (`write_file`, `bash_command`). Without a terminal, other calls that need approval are denied |
|
|
208
|
+
| `dostuff -p "<prompt>"` | Headless: run one prompt, print the answer to stdout, exit. Progress goes to stderr. Piped stdin is appended to the prompt (`-p -` reads the prompt from stdin). `--session <id>` continues a session, `--output-format json` (or `--json`) prints `{result, session_id, usage, ...}`, `--output-format stream-json` prints one JSON event per line (`init`, `assistant`, `tool_call`, `tool_result`, `usage`, `error`, then `result`), `-q` hides progress, `--permission-mode ask\|allowlist\|auto\|plan`. `--max-turns N` stops after N model calls (exit code 1). `--allowed-tools` (comma-separated or repeated) runs matching calls without asking in any mode, in the `permissions.allow` syntax (`"npm test"`, `web_fetch:docs.python.org`) or a tool name for every call of it (`write_file`, `bash_command`). Without a terminal, other calls that need approval are denied. `--trust-project-hooks` runs the project's [hooks](#project-hooks-and-trust) without a saved trust answer |
|
|
207
209
|
| `dostuff mcp list` | Show MCP servers and the file each comes from |
|
|
208
210
|
| `dostuff mcp add <name> [-e K=V] -- <command> [args...]` | Add a stdio server; `--url <url> [-H "Name: value"]` for HTTP; `--project` writes `./.dostuff/mcp_config.json` |
|
|
209
211
|
| `dostuff mcp remove <name> [--project]` | Remove a server |
|
|
@@ -228,6 +230,7 @@ In the TUI:
|
|
|
228
230
|
| `Ctrl+R` | Search the prompts typed in this directory (type to filter, `Enter` puts the prompt in the input) |
|
|
229
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 |
|
|
230
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 it, and any a subagent is running, to the background; the agent gets what it printed so far and carries on. Not for `!command`s. See [Background jobs](#background-jobs) |
|
|
231
234
|
| `Shift+Tab` | Cycle the permission mode for this session: ask → auto → plan → allowlist (shown in the status bar) |
|
|
232
235
|
| `Ctrl+Backspace` / `Ctrl+W` / `Alt+Backspace` | Delete the previous word; `Ctrl+Delete` / `Alt+Delete` the next one |
|
|
233
236
|
| `/exit` | Save the session and quit |
|
|
@@ -243,7 +246,10 @@ In the TUI:
|
|
|
243
246
|
| `/status` | Session, directory, model, permission mode, tokens, context use, MCP servers |
|
|
244
247
|
| `/context` | What fills the context window: system prompt, tools, MCP tools, project instructions, compaction summary and messages, with tokens, % and a bar |
|
|
245
248
|
| `/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 |
|
|
246
|
-
| `/doctor` | The `dostuff doctor` checks (config, API key, MCP config, memory), with a fix for each problem |
|
|
249
|
+
| `/doctor` | The `dostuff doctor` checks (config, API key, MCP config, memory, hooks), with a fix for each problem |
|
|
250
|
+
| `/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
|
+
| `/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
|
+
| `/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) |
|
|
247
253
|
| `/<skill> [args]` | Run a skill: every discovered skill is a command (listed in the `/` menu and `/help`). See [Skills](#skills) |
|
|
248
254
|
| `/<command> [args]` | Run a custom command from `.dostuff/commands/` or `~/.dostuff/commands/`. See [Custom commands](#custom-commands) |
|
|
249
255
|
| `/rename <title>` | Name this session (shown by `dostuff sessions`) |
|
|
@@ -265,7 +271,9 @@ In the TUI:
|
|
|
265
271
|
- **Diffs** — `write_file` / `edit_file` changes shown as a coloured diff
|
|
266
272
|
- **Errors** — red background
|
|
267
273
|
- **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
|
|
274
|
+
- **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
|
|
268
275
|
- **Loading** — bold `Working...` with a live elapsed timer and queued-prompt count, or streamed thoughts displayed live
|
|
276
|
+
- **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
|
|
269
277
|
- **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
|
|
270
278
|
- **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
|
|
271
279
|
|
|
@@ -276,6 +284,7 @@ In the TUI:
|
|
|
276
284
|
| Tool | Kind | Asks? |
|
|
277
285
|
| ---- | ---- | ----- |
|
|
278
286
|
| `read_file`, `list_files`, `grep`, `glob`, `get_current_datetime`, `search_mcp_tools`, `get_mcp_tool_details` | read | never |
|
|
287
|
+
| `bash_output`, `kill_shell` | read | never (they only touch the agent's own background jobs) |
|
|
279
288
|
| `write_file`, `edit_file`, `delete_file` | write | yes (shows a diff) |
|
|
280
289
|
| `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 |
|
|
281
290
|
| `call_mcp_tool` | mcp | yes |
|
|
@@ -285,6 +294,11 @@ In the TUI:
|
|
|
285
294
|
| `read_settings` | read | never (MCP `env` / header values are shown as `<redacted>`) |
|
|
286
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) |
|
|
287
296
|
|
|
297
|
+
File tools writing under a `.dostuff` directory, and `bash_command` calls whose command or `cwd` names `.dostuff`, are
|
|
298
|
+
settings changes too, so they always ask. That way auto mode can't quietly add a hook to `~/.dostuff/config.yaml`. Paths
|
|
299
|
+
into subagent worktrees (`.dostuff/worktrees/…`) are exempt. The shell check matches the text `.dostuff`, so a name the
|
|
300
|
+
command builds indirectly is not caught.
|
|
301
|
+
|
|
288
302
|
`permissions.mode` in `config.yaml`:
|
|
289
303
|
|
|
290
304
|
- `ask` (default) — as in the table above.
|
|
@@ -314,12 +328,257 @@ API keys stay in `.env` files, which the agent can't read or change. Subagents d
|
|
|
314
328
|
|
|
315
329
|
> [!NOTE]
|
|
316
330
|
> **Cancelling a running tool.** ESC stops waiting for tools at once and the turn ends; results that already
|
|
317
|
-
> finished are kept.
|
|
318
|
-
> mid-call, so one that was still running may finish in the background; its result is recorded as
|
|
331
|
+
> finished are kept. A running `bash_command` is killed with its children; tools that run in a worker thread (file tools) cannot
|
|
332
|
+
> be interrupted mid-call, so one that was still running may finish in the background; its result is recorded as
|
|
319
333
|
> `Cancelled by user (may still be running)`.
|
|
320
334
|
|
|
321
335
|
---
|
|
322
336
|
|
|
337
|
+
## Background jobs
|
|
338
|
+
|
|
339
|
+
Dev servers, file watchers and long test runs don't fit a shell call that has to finish within its timeout. The agent
|
|
340
|
+
starts them as **background jobs** instead and keeps working while they run:
|
|
341
|
+
|
|
342
|
+
| Tool | What it does |
|
|
343
|
+
|---|---|
|
|
344
|
+
| `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 |
|
|
345
|
+
| `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 |
|
|
346
|
+
| `kill_shell("dev")` | Kills the job and everything it started, and shows its last lines |
|
|
347
|
+
|
|
348
|
+
The approval prompt for a background start reads `Run shell command (background job "dev"):`; `bash_output` and
|
|
349
|
+
`kill_shell` never ask, because they only reach the calling agent's own jobs. Hooks see `run_in_background` and
|
|
350
|
+
`background_id` in `PreToolUse`, and can deny `kill_shell` like any tool. Plan mode allows a background job only for a
|
|
351
|
+
read-only command.
|
|
352
|
+
|
|
353
|
+
**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
|
|
354
|
+
`<background-job id="test" status="exited" code="1" runtime="42s">` message holding the last 20 lines of each stream,
|
|
355
|
+
so it doesn't have to poll to notice a crashed server. In the TUI the same moment shows as `⚙ job "test" exited (1)
|
|
356
|
+
after 42s`, with a notification when the terminal is in the background (`ui.notifications`). If the agent is idle,
|
|
357
|
+
the TUI starts a turn for it right away (`⚙ Resuming the agent: …`), so it can look at the failed test run or crashed
|
|
358
|
+
server on its own. It waits while you are typing, an approval is open or a command like `/compact` runs; if you send a
|
|
359
|
+
prompt first, that turn gets the message instead. A `/jobs kill` alone doesn't wake it, and after 3 such automatic
|
|
360
|
+
turns in a row it waits for your next message. Turn this off with `jobs: {wake_on_end: false}` in `config.yaml`; the
|
|
361
|
+
agent then sees the message with your next prompt.
|
|
362
|
+
|
|
363
|
+
**In the TUI:**
|
|
364
|
+
|
|
365
|
+
- `Ctrl+B` while the agent waits on a shell command (the loader says `Ctrl+B to background`) moves that command, and
|
|
366
|
+
any a subagent is running in the same turn, to the background. The agent gets what it printed so far and carries on;
|
|
367
|
+
the transcript shows `⎿ moved to background as "bg-3"`. `!command`s can't be backgrounded.
|
|
368
|
+
- `/jobs` lists the session's jobs: id, owner (`main` or `subagent: <role>`), status, runtime and command.
|
|
369
|
+
`/jobs <id>` shows the last 40 lines of each stream and the log paths, `/jobs kill <id>` stops one.
|
|
370
|
+
- 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
|
|
371
|
+
from a list (status, start time, runtime, command) and show its output or stop it.
|
|
372
|
+
|
|
373
|
+
**Logs** go to `~/.dostuff/jobs/<session>/<job>.out` and `.err` (you can `tail -f` them; `/jobs <id>` prints the
|
|
374
|
+
paths). Directories older than 7 days are removed at startup.
|
|
375
|
+
|
|
376
|
+
**Jobs live until their owner ends; in the TUI that is the app, not the conversation:**
|
|
377
|
+
|
|
378
|
+
| Event | What happens to the jobs |
|
|
379
|
+
|---|---|
|
|
380
|
+
| Subagent run ends (done, error or cancelled) | its jobs are killed |
|
|
381
|
+
| `/compact` | kept |
|
|
382
|
+
| `/clear` | kept, no prompt: they move to the new session, which gets their end notices and can use `bash_output`/`kill_shell` on them |
|
|
383
|
+
| `/resume` another session | same as `/clear`: the running jobs follow you into the resumed session |
|
|
384
|
+
| Quit (`Ctrl+Q`, `/exit`) | "Quit and stop 2 background jobs?", then they are killed |
|
|
385
|
+
| Headless run (`dostuff -p`) ends, or `Ctrl+C` | all killed, one stderr line each (`stream-json`: `{"type": "job", …}` events) |
|
|
386
|
+
|
|
387
|
+
> [!WARNING]
|
|
388
|
+
> If DoStuff is killed hard (task manager, `kill -9`, power loss), its jobs keep running: they are detached from the
|
|
389
|
+
> terminal by design. Each session records its jobs in `~/.dostuff/jobs/<session>/jobs.json`, and the next start
|
|
390
|
+
> warns `1 background job from an earlier session may still be running (npm run dev, pid 4812)`. It doesn't kill
|
|
391
|
+
> them, since a pid may have been reused by then; check with your OS tools.
|
|
392
|
+
|
|
393
|
+
---
|
|
394
|
+
|
|
395
|
+
## Hooks
|
|
396
|
+
|
|
397
|
+
Hooks are shell commands DoStuff runs at fixed points of a session: block a tool call, feed a formatter's output back
|
|
398
|
+
to the model, keep the turn going until the tests pass. They are configured under `hooks:` in `config.yaml` and use
|
|
399
|
+
Claude Code's I/O contract (stdin JSON, exit codes, JSON output), so an existing Claude Code hook script works once its
|
|
400
|
+
matcher and tool argument names are renamed (see [the table below](#coming-from-claude-code)).
|
|
401
|
+
|
|
402
|
+
> [!WARNING]
|
|
403
|
+
> Hooks run with your privileges, **unsandboxed**, and are not permission-checked: they are your config, not model
|
|
404
|
+
> output. Read a project's hooks before you trust them.
|
|
405
|
+
|
|
406
|
+
| Event | When | Matcher is matched against | What a hook can do |
|
|
407
|
+
|---|---|---|---|
|
|
408
|
+
| `SessionStart` | Before the first turn of a session, and after a compaction | the source: `startup`, `resume`, `clear`, `compact` | Add context for the rest of the session |
|
|
409
|
+
| `UserPromptSubmit` | After you send a prompt, before it is stored or sent | — | Reject the prompt, or add context for this turn |
|
|
410
|
+
| `PreToolUse` | Before each tool call, before any approval prompt | the tool name | `allow`, `deny` or `ask`; rewrite the arguments |
|
|
411
|
+
| `PostToolUse` | After a tool call ran | the tool name | Append text to the result the model sees |
|
|
412
|
+
| `Stop` | When the agent is about to give its final answer | — | Block, so the turn continues with your reason |
|
|
413
|
+
| `SubagentStop` | Same, for a `delegate_to_subagent` run | — | Same |
|
|
414
|
+
|
|
415
|
+
### Config
|
|
416
|
+
|
|
417
|
+
`matcher` is a Python regex that must match the whole name (`edit_file` does not match `edit_file_v2`); empty or `*`
|
|
418
|
+
matches everything. `if` (tool events only) is searched in a `bash_command`'s `command`. Inline flags such as `(?i)`
|
|
419
|
+
go first in a pattern. `timeout` (default 30 s, 1–300) and `fail_closed` can be set on a group or on one hook. This is
|
|
420
|
+
the example from the spec, and the two scripts it runs are below:
|
|
421
|
+
|
|
422
|
+
```yaml
|
|
423
|
+
hooks:
|
|
424
|
+
project_trust: ask # ask | allow | deny (D4) — only read from ~/.dostuff/config.yaml
|
|
425
|
+
stop_block_limit: 3 # Stop blocks honoured per turn before the loop is allowed to end (1–10)
|
|
426
|
+
SessionStart:
|
|
427
|
+
- matcher: "startup|resume|clear" # regex, full match against the source; empty or "*" = all
|
|
428
|
+
hooks:
|
|
429
|
+
- type: command
|
|
430
|
+
command: "git status --short"
|
|
431
|
+
PreToolUse:
|
|
432
|
+
- matcher: "bash_command" # regex, full match against the tool name
|
|
433
|
+
if: "(?i)^\\s*git\\s+push" # optional regex, searched in tool_input.command (shell tool only)
|
|
434
|
+
fail_closed: true
|
|
435
|
+
timeout: 10
|
|
436
|
+
hooks:
|
|
437
|
+
- type: command
|
|
438
|
+
name: block-main-push
|
|
439
|
+
command: "python .dostuff/hooks/block_main_push.py"
|
|
440
|
+
PostToolUse:
|
|
441
|
+
- matcher: "write_file|edit_file"
|
|
442
|
+
hooks:
|
|
443
|
+
# the script reads tool_input.path from the stdin JSON and runs the formatter on it;
|
|
444
|
+
# its stdout is fed back to the model (D5)
|
|
445
|
+
- type: command
|
|
446
|
+
name: format
|
|
447
|
+
command: "python .dostuff/hooks/format_file.py"
|
|
448
|
+
Stop:
|
|
449
|
+
- hooks:
|
|
450
|
+
- { type: command, name: tests, command: "python .dostuff/hooks/run_tests.py" }
|
|
451
|
+
```
|
|
452
|
+
|
|
453
|
+
- **`fail_closed: true`** (`PreToolUse` and `UserPromptSubmit` only) is for guardrails: if the hook crashes or times
|
|
454
|
+
out, the call is denied (or the prompt rejected) instead of going ahead. A `fail_closed` hook with a config mistake,
|
|
455
|
+
such as a bad regex, is kept and denies everything it matches; any other invalid hook is dropped with a warning.
|
|
456
|
+
- **`stop_block_limit`** (1–10) bounds how many times `Stop` hooks can continue one turn; after that the turn ends with
|
|
457
|
+
a note.
|
|
458
|
+
- User hooks come first, then the project's are added after them; a project file can't remove or reorder yours.
|
|
459
|
+
|
|
460
|
+
```python
|
|
461
|
+
# .dostuff/hooks/block_main_push.py: PreToolUse on bash_command; the group's `if` already matched `git push`
|
|
462
|
+
import json
|
|
463
|
+
import subprocess
|
|
464
|
+
import sys
|
|
465
|
+
|
|
466
|
+
payload = json.load(sys.stdin)
|
|
467
|
+
words = payload["tool_input"].get("command", "").replace(":", " ").split()
|
|
468
|
+
branch = subprocess.run(["git", "branch", "--show-current"], capture_output=True, text=True,
|
|
469
|
+
cwd=payload["cwd"]).stdout.strip()
|
|
470
|
+
if "main" in words or branch == "main":
|
|
471
|
+
print("Don't push to main: push a feature branch and open a pull request.", file=sys.stderr)
|
|
472
|
+
sys.exit(2) # exit 2 = deny; stderr is the reason the model sees
|
|
473
|
+
```
|
|
474
|
+
|
|
475
|
+
```python
|
|
476
|
+
# .dostuff/hooks/format_file.py: PostToolUse on write_file|edit_file; stdout is appended to the tool result
|
|
477
|
+
import json
|
|
478
|
+
import subprocess
|
|
479
|
+
import sys
|
|
480
|
+
|
|
481
|
+
payload = json.load(sys.stdin)
|
|
482
|
+
path = payload["tool_input"].get("path", "")
|
|
483
|
+
if path.endswith(".py"):
|
|
484
|
+
result = subprocess.run(["ruff", "format", path], capture_output=True, text=True, cwd=payload["cwd"])
|
|
485
|
+
print((result.stdout + result.stderr).strip())
|
|
486
|
+
```
|
|
487
|
+
|
|
488
|
+
```python
|
|
489
|
+
# .dostuff/hooks/run_tests.py: Stop; exit 2 sends the failures back and the turn continues
|
|
490
|
+
import json
|
|
491
|
+
import subprocess
|
|
492
|
+
import sys
|
|
493
|
+
|
|
494
|
+
payload = json.load(sys.stdin)
|
|
495
|
+
result = subprocess.run([sys.executable, "-m", "pytest", "-q", "-x"], capture_output=True, text=True,
|
|
496
|
+
cwd=payload["cwd"])
|
|
497
|
+
if result.returncode not in (0, 5): # 5: no tests collected
|
|
498
|
+
print("Tests fail; fix them before finishing:\n" + result.stdout[-3000:], file=sys.stderr)
|
|
499
|
+
sys.exit(2)
|
|
500
|
+
```
|
|
501
|
+
|
|
502
|
+
### Input and output
|
|
503
|
+
|
|
504
|
+
Each hook runs through the same shell as `bash_command`, in the project directory (a worktree subagent's own
|
|
505
|
+
worktree), with no terminal. stdin is one JSON object:
|
|
506
|
+
|
|
507
|
+
```json
|
|
508
|
+
{"hook_event_name": "PreToolUse", "session_id": "…", "turn_id": "…", "cwd": "…", "turn_type": "interactive_loop",
|
|
509
|
+
"tool_name": "bash_command", "tool_input": {"command": "git push origin main"}, "tool_use_id": "…"}
|
|
510
|
+
```
|
|
511
|
+
|
|
512
|
+
| Event | Extra keys |
|
|
513
|
+
|---|---|
|
|
514
|
+
| `PreToolUse`, `PostToolUse` | `tool_name`, `tool_input`, `tool_use_id`; `PostToolUse` also `tool_response` (the result, already truncated) |
|
|
515
|
+
| `UserPromptSubmit` | `prompt` |
|
|
516
|
+
| `SessionStart` | `source` |
|
|
517
|
+
| `Stop`, `SubagentStop` | `last_assistant_message`, `stop_hook_active` (true once a Stop hook already continued this turn) |
|
|
518
|
+
|
|
519
|
+
The environment adds `DOSTUFF_HOOK_EVENT`, `DOSTUFF_SESSION_ID`, `DOSTUFF_TURN_ID`, `DOSTUFF_PROJECT_ROOT` and
|
|
520
|
+
`DOSTUFF_TURN_TYPE`. Output is capped at `loop.max_tool_output_chars`.
|
|
521
|
+
|
|
522
|
+
| Exit code | Meaning |
|
|
523
|
+
|---|---|
|
|
524
|
+
| `0` | Success. Plain stdout is context (`SessionStart`, `UserPromptSubmit`, `PostToolUse`); JSON on stdout can carry a decision (below) |
|
|
525
|
+
| `2` | Block. stderr (or stdout) is the reason: `PreToolUse` denies the call, `PostToolUse` appends it to the result, `UserPromptSubmit` rejects the prompt, `Stop` continues the turn |
|
|
526
|
+
| other | The hook failed: an error line in the transcript, and the run goes on (unless `fail_closed`) |
|
|
527
|
+
|
|
528
|
+
JSON on stdout (exit 0), in either Claude Code spelling:
|
|
529
|
+
|
|
530
|
+
```json
|
|
531
|
+
{"decision": "block", "reason": "…"}
|
|
532
|
+
{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "allow|deny|ask",
|
|
533
|
+
"permissionDecisionReason": "…", "updatedInput": {"command": "…"},
|
|
534
|
+
"additionalContext": "…"}}
|
|
535
|
+
```
|
|
536
|
+
|
|
537
|
+
When several hooks match, they run one after another, each on the original input: the strictest decision wins
|
|
538
|
+
(`deny` > `ask` > `allow`), contexts are joined in config order, and the last `updatedInput` wins. Plan mode still
|
|
539
|
+
applies: a hook `allow` never runs a call plan mode refused, and settings changes still ask. Rewritten arguments are
|
|
540
|
+
checked again, so a rewrite can't skip the prompt the new call needs. Each hook's effect shows in the transcript as a
|
|
541
|
+
line like `⚓ PreToolUse bash_command → deny (reason)` (a `hook` event in `--output-format stream-json`). ESC kills a
|
|
542
|
+
running hook.
|
|
543
|
+
|
|
544
|
+
### Project hooks and trust
|
|
545
|
+
|
|
546
|
+
Hooks in `./.dostuff/config.yaml` come with the repo, so they are code from whoever wrote it. They run only once you
|
|
547
|
+
trust them, set by `hooks.project_trust` in **`~/.dostuff/config.yaml`** (a project file can't set it):
|
|
548
|
+
|
|
549
|
+
- `ask` (default): before the first project hook would run, the TUI lists every project hook's command and file and
|
|
550
|
+
asks. A yes is saved in `~/.dostuff/trusted_hooks.json` for that project, until the hooks block or any file in
|
|
551
|
+
`.dostuff/hooks/` changes; then it asks again. A no skips them for the session.
|
|
552
|
+
- `allow` runs them without asking; `deny` never runs them.
|
|
553
|
+
- Headless (`dostuff -p`) can't ask: it honours a saved yes, runs them with `--trust-project-hooks`, and otherwise
|
|
554
|
+
skips them with a warning. If a skipped hook is `fail_closed`, it refuses to start (exit code 2) instead.
|
|
555
|
+
|
|
556
|
+
Keep hook scripts in `.dostuff/hooks/`: trust covers the files there, and the model can't edit anything under
|
|
557
|
+
`.dostuff/` without a settings prompt. A script elsewhere in the repo can be changed after you trusted it.
|
|
558
|
+
|
|
559
|
+
`/hooks` lists every hook per event with its file, matcher, timeout, `fail_closed` and whether it runs (`user`,
|
|
560
|
+
`trusted`, `untrusted`, `disabled` or `broken`); `/hooks r` re-reads the config files. `dostuff doctor` reports
|
|
561
|
+
invalid hooks, commands not found on `PATH` and project scripts outside `.dostuff/hooks/`.
|
|
562
|
+
|
|
563
|
+
### Coming from Claude Code
|
|
564
|
+
|
|
565
|
+
The stdin envelope, exit codes, JSON output, event names and the `matcher` + `hooks: [{type: command, command}]`
|
|
566
|
+
nesting are the same. Tool names and some argument names differ, so rename the matcher and any `tool_input` keys:
|
|
567
|
+
|
|
568
|
+
| Claude Code | DoStuff `tool_name` | `tool_input` keys that differ |
|
|
569
|
+
|---|---|---|
|
|
570
|
+
| `Bash` | `bash_command` | none (`command`, plus `cwd`, `timeout`) |
|
|
571
|
+
| `Write` | `write_file` | `file_path` → `path` |
|
|
572
|
+
| `Edit` | `edit_file` | `file_path` → `path`, `old_string`/`new_string` → `old_str`/`new_str` |
|
|
573
|
+
| `Read` | `read_file` | `file_path` → `path` |
|
|
574
|
+
| `Grep` / `Glob` | `grep` / `glob` | per tool |
|
|
575
|
+
| `mcp__<server>__<tool>` | `call_mcp_tool` | server and tool are inside `tool_input` |
|
|
576
|
+
|
|
577
|
+
Not supported yet: `http`, `prompt` and `agent` hook types, and the `Notification`, `PreCompact`, `SessionEnd` and
|
|
578
|
+
`SubagentStart` events.
|
|
579
|
+
|
|
580
|
+
---
|
|
581
|
+
|
|
323
582
|
## Configuration
|
|
324
583
|
|
|
325
584
|
Config is layered, with later sources overriding earlier ones:
|