dostuff 0.2.11__tar.gz → 0.2.13__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.11 → dostuff-0.2.13}/PKG-INFO +66 -24
- {dostuff-0.2.11 → dostuff-0.2.13}/README.md +65 -23
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/agent/instructions.py +3 -2
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/agent/permissions.py +209 -23
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/agent/run_tool.py +19 -5
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/agent/subagents/definitions.py +2 -2
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/agent/subagents/run.py +5 -3
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/cli.py +11 -4
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/cli_tui.py +111 -18
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/headless.py +9 -2
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/agent/constants.py +7 -4
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/agent/file_mentions.py +6 -2
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/agent/slash_suggestion.py +9 -0
- dostuff-0.2.13/dostuff/helpers/config_secrets.py +41 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/hooks/dispatch.py +9 -1
- dostuff-0.2.13/dostuff/helpers/mcp/server_config.py +68 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/skills/discover_skills.py +22 -7
- dostuff-0.2.13/dostuff/helpers/skills/skill_command.py +96 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/tools/resolve_safe_path.py +25 -12
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/ui/doctor.py +19 -1
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/ui/tools_listing.py +1 -1
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/lib/checkpoints.py +2 -2
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/lib/mcp/mcp_client.py +8 -3
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/templates/config.example.yaml +2 -2
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/tools/create_agent_type.py +1 -1
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/tools/definitions.py +5 -2
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/tools/files/edit_file.py +33 -17
- dostuff-0.2.13/dostuff/tools/files/multi_edit.py +77 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/tools/names.py +1 -1
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/tools/settings.py +44 -10
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff.egg-info/PKG-INFO +66 -24
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff.egg-info/SOURCES.txt +3 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/pyproject.toml +1 -1
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_checkpoints_todos_caching.py +11 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_cli_commands.py +53 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_create_agent_type.py +2 -1
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_file_tools.py +157 -1
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_hooks.py +72 -1
- dostuff-0.2.13/tests/test_mcp_env_references.py +177 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_optional_memory_and_instructions.py +26 -2
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_permissions.py +348 -19
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_settings_tools.py +61 -5
- dostuff-0.2.13/tests/test_skill_command.py +138 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_skills_discovery.py +57 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_slash_suggestion.py +11 -1
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_subagents_run.py +14 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_subagents_types.py +15 -1
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_tui.py +719 -0
- dostuff-0.2.11/dostuff/helpers/mcp/server_config.py +0 -36
- dostuff-0.2.11/dostuff/helpers/skills/skill_command.py +0 -48
- dostuff-0.2.11/tests/test_skill_command.py +0 -37
- {dostuff-0.2.11 → dostuff-0.2.13}/LICENSE +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/__init__.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/__main__.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/agent/call_agent.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/agent/loop.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/agent/subagents/__init__.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/agent/subagents/adapter.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/agent/subagents/fork.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/agent/subagents/prompt.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/agent/subagents/registry.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/config.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/agent/append_step.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/agent/consume_stream.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/agent/context_usage.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/agent/environment_context.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/agent/get_model_token_limit.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/agent/load_identity.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/agent/load_project_instructions.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/agent/loop_check_cancelled.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/agent/loop_emit.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/agent/manage_context.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/agent/model_cost.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/agent/notices.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/agent/pastes.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/agent/quick_memory.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/agent/side_question.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/agent/steering.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/agent/tool_output.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/agent/turn_context.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/hooks/__init__.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/hooks/events.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/hooks/load_hooks.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/hooks/run_hook.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/hooks/trust.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/mcp/load_mcp_config.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/mcp/mcp_oauth.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/mcp/token_store.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/memory/export_session.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/memory/resolve_memory_operation.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/memory/shell_step.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/models/add_model_entry.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/models/list_models.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/models/opencode.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/skills/custom_commands.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/tools/diff.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/tools/generate_tool_schema.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/tools/project_root.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/ui/__init__.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/ui/ask_answers.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/ui/emit.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/ui/prompt_history.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/helpers/ui/terminal_signals.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/lib/exceptions.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/lib/mcp/mcp_client_registration_store.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/lib/mcp/mcp_tool_registry_store.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/lib/memory/chroma.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/lib/memory/episodic_memory_store.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/lib/memory/semantic_memory_store.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/lib/memory/session_store.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/lib/memory/stores.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/lib/memory/types.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/lib/model.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/lib/tracing.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/lib/worktree.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/memory/__init__.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/setup_wizard.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/skills.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/templates/env.example +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/tools/__init__.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/tools/agent.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/tools/ask_user.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/tools/bash/bash_command.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/tools/bash/bash_output.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/tools/bash/jobs.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/tools/bash/kill_shell.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/tools/files/delete_file.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/tools/files/list_files.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/tools/files/read_file.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/tools/files/write_file.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/tools/get_current_datetime.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/tools/mcp/call_mcp_tool.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/tools/mcp/get_mcp_tool_details.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/tools/mcp/search_mcp_tools.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/tools/memory/save_episode.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/tools/memory/save_memory.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/tools/search/glob.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/tools/search/grep.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/tools/search/walk.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/tools/send_message.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/tools/stop_agent.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/tools/todo_write.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/tools/web_fetch.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff/tools/web_search.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff.egg-info/dependency_links.txt +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff.egg-info/entry_points.txt +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff.egg-info/requires.txt +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/dostuff.egg-info/top_level.txt +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/setup.cfg +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_ask_user.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_bash_command.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_config_memory_mcp.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_export_session.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_file_mentions.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_jobs.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_loop.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_mcp_e2e.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_mcp_oauth.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_opencode.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_pastes.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_roadmap_021.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_session_store.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_setup_wizard.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_side_question.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_side_question_litellm.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_steering.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_subagent.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_subagents_background.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_subagents_fork.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_subagents_store.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_terminal_signals.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_tool_schemas.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_tools_listing.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_turn_context.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_web_fetch.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_web_search.py +0 -0
- {dostuff-0.2.11 → dostuff-0.2.13}/tests/test_worktree.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.13
|
|
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
|
|
@@ -82,15 +82,15 @@ DoStuff is a terminal AI agent that runs anywhere `pip` runs. It gives you a ful
|
|
|
82
82
|
- **MCP server support** — stdio (npx, uvx) and HTTP transports
|
|
83
83
|
- **`@file` mentions** — type `@` in the prompt to pick a file or folder; its content (or listing) is sent with the message
|
|
84
84
|
- **Project instructions** — `AGENTS.md` / `CLAUDE.md` from `~/.dostuff/`, the repo root and every folder down to the current one, combined
|
|
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)
|
|
85
|
+
- **Coding tools** — `read_file` (line numbers, offset/limit), `edit_file` (exact replacement), `multi_edit` (several replacements in one file, all or nothing), `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
|
- **`ask_user`** — the agent asks you a real question — up to 4, with 2–4 options each, multi-select and a free-text "Other" — instead of guessing; the answers come back to it as one result and stay readable in `/resume`. See [Asking the user](#asking-the-user)
|
|
87
87
|
- **`/btw` side questions** — ask about the conversation while a turn runs (or idle) without stopping or queuing it: one model call, no tools run, answered in a panel above the input and never added to the history; `f` hands the question to a background agent that can check it with tools. See [Side questions](#side-questions-btw)
|
|
88
88
|
- **Mid-turn steering (`/steer`)** — send a correction to the turn that is running and the model reads it at the next tool boundary instead of waiting for the turn; plain messages steer by default, and `ui.mid_turn_messages: queue` batches them after the turn instead. See [Mid-turn steering](#mid-turn-steering-steer)
|
|
89
89
|
- **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
|
|
90
90
|
- **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)
|
|
91
91
|
- **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)
|
|
92
|
-
- **File sandbox** — file tools stay inside the project directory, plus read-only access to
|
|
93
|
-
- **Skills loader** — drop a `SKILL.md` in the right folder, restart, done; run one with `/<skill-name> [args]`
|
|
92
|
+
- **File sandbox** — file tools stay inside the project directory, plus read-only access to `.dostuff` (the project's and `~/.dostuff/`) and to discovered skill folders; `.env*` files, `mcp_config.json` and `.dostuff/data` (past sessions and prompts, saved MCP client secrets) are never readable
|
|
93
|
+
- **Skills loader** — drop a `SKILL.md` in the right folder, restart, done; run one with `/<skill-name> [args]`, name one mid-message to allow it for that message, or keep one manual-only with `disable-model-invocation`. See [Skills](#skills)
|
|
94
94
|
- **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)
|
|
95
95
|
- **Per-tool timeout** (120s) to prevent hung servers; long tool output is truncated (head + tail) before it reaches the model
|
|
96
96
|
- **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
|
|
@@ -258,6 +258,7 @@ In the TUI:
|
|
|
258
258
|
| `/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 |
|
|
259
259
|
| `/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) |
|
|
260
260
|
| `/<skill> [args]` | Run a skill: every discovered skill is a command (listed in the `/` menu and `/help`). See [Skills](#skills) |
|
|
261
|
+
| `… /<skill> …` | Mid-message, makes that skill available for this message; the `/` menu offers skills as you type. See [Skills](#skills) |
|
|
261
262
|
| `/<command> [args]` | Run a custom command from `.dostuff/commands/` or `~/.dostuff/commands/`. See [Custom commands](#custom-commands) |
|
|
262
263
|
| `/rename <title>` | Name this session (shown by `dostuff sessions`) |
|
|
263
264
|
| `/export [<path>]` | Save this session as Markdown (default `dostuff-session-<id>.md`) |
|
|
@@ -276,7 +277,7 @@ In the TUI:
|
|
|
276
277
|
- **Sticky prompt** — once a prompt or `!command` scrolls off the top, it stays pinned there on one row while you are in its turn, as the answer streams or when you scroll back through an old one, until the next prompt reaches the top. Click it to go back to the start of the turn; `↓ Jump to bottom` returns you to the latest message
|
|
277
278
|
- **Approvals** — a selector (arrows, a number, or `y` = allow once, `a` = always this session, `n` = deny with an optional note); several calls in one response can be approved together
|
|
278
279
|
- **Turn summary** — `✻ Worked for 1m 5s · $0.01 · done 12:59 PM` after each turn
|
|
279
|
-
- **Diffs** — `write_file` / `edit_file` changes shown as a coloured diff
|
|
280
|
+
- **Diffs** — `write_file` / `edit_file` / `multi_edit` changes shown as a coloured diff
|
|
280
281
|
- **Errors** — red background
|
|
281
282
|
- **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
|
|
282
283
|
- **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
|
|
@@ -296,7 +297,7 @@ In the TUI:
|
|
|
296
297
|
| ---- | ---- | ----- |
|
|
297
298
|
| `read_file`, `list_files`, `grep`, `glob`, `get_current_datetime`, `search_mcp_tools`, `get_mcp_tool_details` | read | never |
|
|
298
299
|
| `bash_output`, `kill_shell` | read | never (they only touch the agent's own background jobs) |
|
|
299
|
-
| `write_file`, `edit_file`, `delete_file` | write | yes (shows a diff) |
|
|
300
|
+
| `write_file`, `edit_file`, `multi_edit`, `delete_file` | write | yes (shows a diff; `multi_edit` shows one diff for all its edits) |
|
|
300
301
|
| `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 |
|
|
301
302
|
| `call_mcp_tool` | mcp | yes |
|
|
302
303
|
| `web_fetch` | network | yes; `a` (always) allows that domain for the session |
|
|
@@ -304,24 +305,35 @@ In the TUI:
|
|
|
304
305
|
| `agent`, `send_message`, `stop_agent` | — | no; each subagent's own calls ask, titled with the agent |
|
|
305
306
|
| `ask_user` | read | never (it is the agent talking to you; subagents never get it) |
|
|
306
307
|
| `read_settings` | read | never (MCP `env` / header values are shown as `<redacted>`) |
|
|
307
|
-
| `edit_config`, `set_mcp_server`, `remove_mcp_server`, `create_agent_type` | settings | **
|
|
308
|
+
| `edit_config`, `set_mcp_server`, `remove_mcp_server`, `create_agent_type` | settings | **yes, in every mode but `auto`, with no "always" option** (shows the diff or the server's command) |
|
|
308
309
|
|
|
309
310
|
File tools writing under a `.dostuff` directory, and `bash_command` calls whose command or `cwd` names `.dostuff`, are
|
|
310
|
-
settings changes too, so
|
|
311
|
-
|
|
312
|
-
command builds indirectly is not caught.
|
|
311
|
+
settings changes too, so `ask` and `allowlist` always prompt for them. Paths into subagent worktrees
|
|
312
|
+
(`.dostuff/worktrees/…`) are exempt, apart from the secrets copied there. The shell check matches the text `.dostuff`,
|
|
313
|
+
so a name the command builds indirectly is not caught.
|
|
314
|
+
|
|
315
|
+
Reading is not a settings change: a read-only shell command on `.dostuff` (`ls .dostuff/agents`, `cat
|
|
316
|
+
~/.dostuff/config.yaml`) runs like any other, plan mode included. Only the part of a pipeline that names the path has to
|
|
317
|
+
be a read, so `grep FAIL ~/.dostuff/jobs/<session>/<job>.out | sed … | sort -u` is fine. The same paths `read_file` can
|
|
318
|
+
open qualify, so in `ask` and `allowlist` these still ask: `.env*` files and `mcp_config.json` (in a `.dostuff` dir, or
|
|
319
|
+
the legacy one at the project root), a wildcard in the path, a command that changes directory, a `cwd` other than the
|
|
320
|
+
project root, and `grep` / `rg` / `Select-String` over all of a `.dostuff` dir, `.dostuff/worktrees` or one worktree,
|
|
321
|
+
which would reach `.env`.
|
|
313
322
|
|
|
314
323
|
`permissions.mode` in `config.yaml`:
|
|
315
324
|
|
|
316
325
|
- `ask` (default) — as in the table above.
|
|
317
326
|
- `allowlist` — as `ask`, plus the patterns in `permissions.allow` run without asking (a shell command prefix such as `npm test`, a tool name such as `write_file`, `call_mcp_tool:<server>__<tool>`, `web_fetch:<domain>`, or `web_search`).
|
|
318
|
-
- `auto` — nothing asks. A red warning is shown at startup.
|
|
327
|
+
- `auto` — nothing asks, so the agent never stops to wait for approval. That includes settings changes: it can add hooks and MCP servers, create agents and skills, and change most of `.dostuff`, so use it only where you would let it do all of that. It refuses two things, and the call fails at once so the agent carries on: secrets (a `.env*` file, `mcp_config.json` or `.dostuff/data` named in a command, or a search that would reach one) and its own limits (`permissions`, `hooks.project_trust`, `trusted_hooks.json`). `config.yaml` changes only through `edit_config`, which can check them. There is no classifier reviewing commands, and the shell checks match text, so this is a guard against mistakes, not a sandbox. A `PreToolUse` hook that asks still prompts, because you configured it, and so does the one-time trust check for project hooks. A red warning is shown at startup.
|
|
319
328
|
- `plan` — read-only: reads and read-only shell commands run; file changes, other shell commands and settings changes are denied with a "plan mode" note, and the model is told to investigate and answer with a plan. Web and MCP calls ask as in `ask`.
|
|
320
329
|
|
|
321
330
|
In the TUI, `Shift+Tab` cycles the mode for the session (ask → auto → plan → allowlist); `/permissions <mode>` picks one.
|
|
322
331
|
|
|
323
332
|
Answering `a` (always) approves that tool, or for the shell those commands, for the rest of the session.
|
|
324
333
|
|
|
334
|
+
`edit_file` and `multi_edit` grant the same thing, so a rule for either covers both: in `permissions.allow`, in
|
|
335
|
+
`--allowed-tools`, and for `a` (always). It stops there: neither covers `write_file` or `delete_file`.
|
|
336
|
+
|
|
325
337
|
**Changing settings by asking.** Instead of editing `~/.dostuff/config.yaml` or `mcp_config.json` by hand, ask
|
|
326
338
|
the agent: "hide the session id in the status bar", "set max_iterations to 50 for this project", "add the GitHub
|
|
327
339
|
MCP server". It reads the settings with `read_settings`, changes `config.yaml` with `edit_config` (an exact-text
|
|
@@ -329,13 +341,13 @@ edit that keeps your comments, checked to be valid YAML) and adds, updates or re
|
|
|
329
341
|
`set_mcp_server` / `remove_mcp_server`, in the user files (`~/.dostuff/`) or the project's (`./.dostuff/`).
|
|
330
342
|
Changes apply at once, without a restart (MCP servers connect or disconnect; tracing changes need a restart).
|
|
331
343
|
Because these files hold the permission rules and an MCP server is a command that runs on your machine, every
|
|
332
|
-
change asks,
|
|
344
|
+
change asks, except in `auto` mode, and so do `write_file` / `edit_file` / `multi_edit` on anything in a `.dostuff` folder.
|
|
333
345
|
API keys stay in `.env` files, which the agent can't read or change. Subagents don't get these tools.
|
|
334
346
|
|
|
335
347
|
> [!IMPORTANT]
|
|
336
348
|
> File tools are sandboxed to the project directory (the directory the session runs in): paths that resolve
|
|
337
|
-
> outside it are rejected, except that
|
|
338
|
-
>
|
|
349
|
+
> outside it are rejected, except that `.dostuff` (the project's and `~/.dostuff/`) and discovered skill folders
|
|
350
|
+
> can be read (never written), and `.env*` files, `mcp_config.json` and `.dostuff/data` cannot be read. **The shell is not sandboxed**:
|
|
339
351
|
> `bash_command` can touch anything your user can, which is why non-read-only commands ask first.
|
|
340
352
|
> The shell is Git Bash / `bash` when found, otherwise PowerShell on Windows or `/bin/sh`.
|
|
341
353
|
|
|
@@ -652,7 +664,7 @@ You are a code reviewer. Report findings as a list, most severe first.
|
|
|
652
664
|
|---|---|
|
|
653
665
|
| `Read` | `read_file` |
|
|
654
666
|
| `Write` | `write_file` |
|
|
655
|
-
| `Edit`, `MultiEdit` | `edit_file` |
|
|
667
|
+
| `Edit`, `MultiEdit` | `edit_file`, `multi_edit` |
|
|
656
668
|
| `Glob` / `Grep` / `LS` | `glob` / `grep` / `list_files` |
|
|
657
669
|
| `Bash` | `bash_command` (plus `bash_output`, `kill_shell`) |
|
|
658
670
|
| `WebFetch` / `WebSearch` | `web_fetch` / `web_search` |
|
|
@@ -731,8 +743,15 @@ matcher and tool argument names are renamed (see [the table below](#coming-from-
|
|
|
731
743
|
|
|
732
744
|
`matcher` is a Python regex that must match the whole name (`edit_file` does not match `edit_file_v2`); empty or `*`
|
|
733
745
|
matches everything. `if` (tool events only) is searched in a `bash_command`'s `command`. Inline flags such as `(?i)`
|
|
734
|
-
go first in a pattern. `timeout` (default 30 s, 1–300) and `fail_closed` can be set on a group or on one hook.
|
|
735
|
-
|
|
746
|
+
go first in a pattern. `timeout` (default 30 s, 1–300) and `fail_closed` can be set on a group or on one hook.
|
|
747
|
+
|
|
748
|
+
A tool matcher that matches `edit_file` also fires for `multi_edit`, so a guard or a formatter on `edit_file` holds for
|
|
749
|
+
the same change made through `multi_edit`. It does not work the other way: a `multi_edit` matcher skips `edit_file`. The
|
|
750
|
+
payload stays true to the call, with `tool_name` set to `multi_edit` and `tool_input` to `{path, edits}`. A script that
|
|
751
|
+
reads `tool_input.path` keeps working; one that reads `tool_input.old_str` gets nothing there and needs to read `edits`.
|
|
752
|
+
A hook that rewrites `old_str` / `new_str` makes a `multi_edit` call fail with a tool error, and nothing is written.
|
|
753
|
+
|
|
754
|
+
This is the example from the spec, and the two scripts it runs are below:
|
|
736
755
|
|
|
737
756
|
```yaml
|
|
738
757
|
hooks:
|
|
@@ -888,6 +907,7 @@ nesting are the same. Tool names and some argument names differ, so rename the m
|
|
|
888
907
|
| `Bash` | `bash_command` | none (`command`, plus `cwd`, `timeout`) |
|
|
889
908
|
| `Write` | `write_file` | `file_path` → `path` |
|
|
890
909
|
| `Edit` | `edit_file` | `file_path` → `path`, `old_string`/`new_string` → `old_str`/`new_str` |
|
|
910
|
+
| `MultiEdit` | `multi_edit` | `file_path` → `path`, and inside `edits`, `old_string`/`new_string` → `old_str`/`new_str` |
|
|
891
911
|
| `Read` | `read_file` | `file_path` → `path` |
|
|
892
912
|
| `Grep` / `Glob` | `grep` / `glob` | per tool |
|
|
893
913
|
| `AskUserQuestion` | `ask_user` | `multiSelect` → `multi_select`; the answers come back as the tool's result |
|
|
@@ -958,7 +978,7 @@ See [`config.example.yaml`](https://github.com/kVarunkk/DoStuff/blob/package-str
|
|
|
958
978
|
|
|
959
979
|
### `.env`
|
|
960
980
|
|
|
961
|
-
**Never put secrets in `config.yaml`.** Use `~/.dostuff/.env` and/or project-local `<cwd>/.dostuff/.env`. Both are read; project values override user values, and real environment variables override both:
|
|
981
|
+
**Never put secrets in `config.yaml`.** `edit_config` refuses them, `/config` warns, and `dostuff doctor` flags any already there. Use `~/.dostuff/.env` and/or project-local `<cwd>/.dostuff/.env`. Both are read; project values override user values, and real environment variables override both:
|
|
962
982
|
|
|
963
983
|
```bash
|
|
964
984
|
# ~/.dostuff/.env (chmod 600 on Unix)
|
|
@@ -1025,32 +1045,40 @@ Manage servers with `dostuff mcp list` / `add` / `remove` instead of editing the
|
|
|
1025
1045
|
"tavily": {
|
|
1026
1046
|
"transport": "stdio",
|
|
1027
1047
|
"command": "npx",
|
|
1028
|
-
"args": ["-y", "@tavily/mcp-server"]
|
|
1029
|
-
"env": { "TAVILY_API_KEY": "tvly-..." }
|
|
1048
|
+
"args": ["-y", "@tavily/mcp-server"]
|
|
1030
1049
|
},
|
|
1031
1050
|
"github": {
|
|
1032
1051
|
"transport": "stdio",
|
|
1033
1052
|
"command": "uvx",
|
|
1034
1053
|
"args": ["mcp-server-github"],
|
|
1035
|
-
"env": { "GITHUB_TOKEN": "
|
|
1054
|
+
"env": { "GITHUB_TOKEN": "${MY_WORK_GITHUB_KEY}" }
|
|
1036
1055
|
},
|
|
1037
1056
|
"remote": {
|
|
1038
1057
|
"transport": "http",
|
|
1039
1058
|
"url": "https://mcp.example.com/sse",
|
|
1040
|
-
"headers": { "Authorization": "Bearer
|
|
1059
|
+
"headers": { "Authorization": "Bearer ${SEARCH_API_KEY}" }
|
|
1041
1060
|
}
|
|
1042
1061
|
}
|
|
1043
1062
|
}
|
|
1044
1063
|
```
|
|
1045
1064
|
|
|
1065
|
+
**Keys go in `.dostuff/.env`, not in this file.** `${NAME}` in `headers` and `env` is replaced from `.env` (or the real environment) when the server connects:
|
|
1066
|
+
|
|
1067
|
+
- **HTTP server:** you pick the name. It only links the two files, so `SEARCH_API_KEY=...` in `.env` matches `${SEARCH_API_KEY}` above.
|
|
1068
|
+
- **Local (stdio) server:** the server picks the name, so copy it from the server's docs. It inherits `.env`, so a key under that exact name needs no `env` entry (`tavily` above reads `TAVILY_API_KEY`). Use `env` to pass a key you saved under another name (`github` above).
|
|
1069
|
+
|
|
1070
|
+
Only the exact form `${NAME}` is replaced, and only in `headers` and `env`. If a variable is missing or empty the server doesn't connect, and the error names it; after adding it, restart dostuff. `dostuff doctor` reports missing variables and plain keys left in the file, and `/config` and `dostuff mcp add` warn about them. On the command line use single quotes, so your shell doesn't expand the name itself: `dostuff mcp add search --url https://mcp.example.com -H 'Authorization: Bearer ${SEARCH_API_KEY}'`.
|
|
1071
|
+
|
|
1072
|
+
A server's `url` receives whatever its headers name, so read a project's `.dostuff/mcp_config.json` before you run dostuff in a repository you don't trust, just as you would for a `command` it runs.
|
|
1073
|
+
|
|
1046
1074
|
| Field | Required for | Notes |
|
|
1047
1075
|
| ----------- | ------------ | ------------------------------ |
|
|
1048
1076
|
| `transport` | optional | `stdio` (default) or `http` |
|
|
1049
1077
|
| `command` | stdio | Executable (`npx`, `uvx`, ...) |
|
|
1050
1078
|
| `args` | stdio | Argument list |
|
|
1051
|
-
| `env` | stdio | Env vars for the child process |
|
|
1079
|
+
| `env` | stdio | Env vars for the child process, added to what it inherits; `${NAME}` is read from `.env` |
|
|
1052
1080
|
| `url` | http | Remote MCP server URL |
|
|
1053
|
-
| `headers` | http | HTTP headers
|
|
1081
|
+
| `headers` | http | HTTP headers; `${NAME}` is read from `.env` |
|
|
1054
1082
|
| `connect_timeout` | optional | Seconds before giving up on this server (default 150, enough for a browser OAuth login) |
|
|
1055
1083
|
|
|
1056
1084
|
MCP servers connect concurrently in the background, so the TUI never blanks during boot. Each server is announced in the chat area upon successful or failed connection.
|
|
@@ -1121,6 +1149,20 @@ Detailed instructions for the agent go here.
|
|
|
1121
1149
|
|
|
1122
1150
|
**Running a skill yourself:** each skill is also a slash command, `/<name> [arguments]` (e.g. `/my-skill src/app.py`), in the TUI and with `dostuff -p "/my-skill ..."`. The turn's message is the skill's `SKILL.md` body plus your arguments (which can use `@path` mentions), so the model follows it straight away instead of deciding whether to read it. The command shows in the `/` menu marked `(skill)` and in `/help`. Built-in commands win a name clash, the first skill found (in the order above) wins between skills, and names with spaces can't be run this way; the model can still use those skills on its own.
|
|
1123
1151
|
|
|
1152
|
+
**Manual-only skills:** add `disable-model-invocation: true` to the frontmatter and the model is not told about the skill. It is left out of the system prompt and every subagent's prompt, so it only runs when you ask for it, with `/<name>` or a mention (below). It stays in the `/` menu and `/help`, and the `Skills loaded` line at startup marks it `(manual only)`. Only `false`, `no`, `off`, `0` or an empty value leave a skill visible to the model; anything else, a typo included, hides it.
|
|
1153
|
+
|
|
1154
|
+
> [!IMPORTANT]
|
|
1155
|
+
> `disable-model-invocation` is **not a security boundary**. It stops the model from discovering and choosing the
|
|
1156
|
+
> skill; it does not block anything. The skill's folder stays readable by the file tools, a project skill is an
|
|
1157
|
+
> ordinary project file, and the shell can read whatever your user can. To guarantee a dangerous command never runs,
|
|
1158
|
+
> put a `PreToolUse` [hook](#hooks) on that command.
|
|
1159
|
+
|
|
1160
|
+
**Mentioning a skill:** write `/<name>` inside a message, as in `go ahead and /deploy`, to make that skill available for that message. This is how the model gets to use a manual-only skill, and it works for any skill. The `SKILL.md` is not expanded: the model gets a note after your message with the skill's name, description and folder, and judges from your wording, so `don't run /deploy yet` works. You keep seeing the message as you typed it, plus a line, `Skill available for this message: deploy`; if that line is missing, the name wasn't recognised. It works in prompts, queued prompts, steering messages and `dostuff -p`. The permission lasts for that message, and subagents don't inherit it.
|
|
1161
|
+
|
|
1162
|
+
A mention follows a space or a new line, can be any case, and may end in one `.`, `,`, `!`, `?`, `:` or `;`. So `` `/deploy` ``, `(/deploy)` and `/deploy/x` are not mentions, and neither is a path like `/tmp/notes.md`. Custom commands can't be mentioned. Only what you type counts: a `/deploy` inside an `@file` or a paste collapsed to `[Pasted text #1 …]` grants nothing. A message that starts with a skill or custom command is that command's run, so `/review then /deploy` grants nothing for `deploy`.
|
|
1163
|
+
|
|
1164
|
+
While you type, `/` after a space opens the menu with skills only. Tab and Enter there replace just that word: your sentence stays and nothing is sent until the next Enter.
|
|
1165
|
+
|
|
1124
1166
|
Run `dostuff init` to bootstrap a local `.dostuff/skills/` folder. Restart the agent after adding new skills.
|
|
1125
1167
|
|
|
1126
1168
|
### Custom commands
|
|
@@ -34,15 +34,15 @@ DoStuff is a terminal AI agent that runs anywhere `pip` runs. It gives you a ful
|
|
|
34
34
|
- **MCP server support** — stdio (npx, uvx) and HTTP transports
|
|
35
35
|
- **`@file` mentions** — type `@` in the prompt to pick a file or folder; its content (or listing) is sent with the message
|
|
36
36
|
- **Project instructions** — `AGENTS.md` / `CLAUDE.md` from `~/.dostuff/`, the repo root and every folder down to the current one, combined
|
|
37
|
-
- **Coding tools** — `read_file` (line numbers, offset/limit), `edit_file` (exact replacement), `write_file`, `grep`, `glob`, `list_files`, `delete_file`, `bash_command`, `web_fetch` (read a URL as text), `web_search` (free, no API key)
|
|
37
|
+
- **Coding tools** — `read_file` (line numbers, offset/limit), `edit_file` (exact replacement), `multi_edit` (several replacements in one file, all or nothing), `write_file`, `grep`, `glob`, `list_files`, `delete_file`, `bash_command`, `web_fetch` (read a URL as text), `web_search` (free, no API key)
|
|
38
38
|
- **`ask_user`** — the agent asks you a real question — up to 4, with 2–4 options each, multi-select and a free-text "Other" — instead of guessing; the answers come back to it as one result and stay readable in `/resume`. See [Asking the user](#asking-the-user)
|
|
39
39
|
- **`/btw` side questions** — ask about the conversation while a turn runs (or idle) without stopping or queuing it: one model call, no tools run, answered in a panel above the input and never added to the history; `f` hands the question to a background agent that can check it with tools. See [Side questions](#side-questions-btw)
|
|
40
40
|
- **Mid-turn steering (`/steer`)** — send a correction to the turn that is running and the model reads it at the next tool boundary instead of waiting for the turn; plain messages steer by default, and `ui.mid_turn_messages: queue` batches them after the turn instead. See [Mid-turn steering](#mid-turn-steering-steer)
|
|
41
41
|
- **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
|
|
42
42
|
- **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)
|
|
43
43
|
- **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)
|
|
44
|
-
- **File sandbox** — file tools stay inside the project directory, plus read-only access to
|
|
45
|
-
- **Skills loader** — drop a `SKILL.md` in the right folder, restart, done; run one with `/<skill-name> [args]`
|
|
44
|
+
- **File sandbox** — file tools stay inside the project directory, plus read-only access to `.dostuff` (the project's and `~/.dostuff/`) and to discovered skill folders; `.env*` files, `mcp_config.json` and `.dostuff/data` (past sessions and prompts, saved MCP client secrets) are never readable
|
|
45
|
+
- **Skills loader** — drop a `SKILL.md` in the right folder, restart, done; run one with `/<skill-name> [args]`, name one mid-message to allow it for that message, or keep one manual-only with `disable-model-invocation`. See [Skills](#skills)
|
|
46
46
|
- **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)
|
|
47
47
|
- **Per-tool timeout** (120s) to prevent hung servers; long tool output is truncated (head + tail) before it reaches the model
|
|
48
48
|
- **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
|
|
@@ -210,6 +210,7 @@ In the TUI:
|
|
|
210
210
|
| `/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 |
|
|
211
211
|
| `/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) |
|
|
212
212
|
| `/<skill> [args]` | Run a skill: every discovered skill is a command (listed in the `/` menu and `/help`). See [Skills](#skills) |
|
|
213
|
+
| `… /<skill> …` | Mid-message, makes that skill available for this message; the `/` menu offers skills as you type. See [Skills](#skills) |
|
|
213
214
|
| `/<command> [args]` | Run a custom command from `.dostuff/commands/` or `~/.dostuff/commands/`. See [Custom commands](#custom-commands) |
|
|
214
215
|
| `/rename <title>` | Name this session (shown by `dostuff sessions`) |
|
|
215
216
|
| `/export [<path>]` | Save this session as Markdown (default `dostuff-session-<id>.md`) |
|
|
@@ -228,7 +229,7 @@ In the TUI:
|
|
|
228
229
|
- **Sticky prompt** — once a prompt or `!command` scrolls off the top, it stays pinned there on one row while you are in its turn, as the answer streams or when you scroll back through an old one, until the next prompt reaches the top. Click it to go back to the start of the turn; `↓ Jump to bottom` returns you to the latest message
|
|
229
230
|
- **Approvals** — a selector (arrows, a number, or `y` = allow once, `a` = always this session, `n` = deny with an optional note); several calls in one response can be approved together
|
|
230
231
|
- **Turn summary** — `✻ Worked for 1m 5s · $0.01 · done 12:59 PM` after each turn
|
|
231
|
-
- **Diffs** — `write_file` / `edit_file` changes shown as a coloured diff
|
|
232
|
+
- **Diffs** — `write_file` / `edit_file` / `multi_edit` changes shown as a coloured diff
|
|
232
233
|
- **Errors** — red background
|
|
233
234
|
- **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
|
|
234
235
|
- **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
|
|
@@ -248,7 +249,7 @@ In the TUI:
|
|
|
248
249
|
| ---- | ---- | ----- |
|
|
249
250
|
| `read_file`, `list_files`, `grep`, `glob`, `get_current_datetime`, `search_mcp_tools`, `get_mcp_tool_details` | read | never |
|
|
250
251
|
| `bash_output`, `kill_shell` | read | never (they only touch the agent's own background jobs) |
|
|
251
|
-
| `write_file`, `edit_file`, `delete_file` | write | yes (shows a diff) |
|
|
252
|
+
| `write_file`, `edit_file`, `multi_edit`, `delete_file` | write | yes (shows a diff; `multi_edit` shows one diff for all its edits) |
|
|
252
253
|
| `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 |
|
|
253
254
|
| `call_mcp_tool` | mcp | yes |
|
|
254
255
|
| `web_fetch` | network | yes; `a` (always) allows that domain for the session |
|
|
@@ -256,24 +257,35 @@ In the TUI:
|
|
|
256
257
|
| `agent`, `send_message`, `stop_agent` | — | no; each subagent's own calls ask, titled with the agent |
|
|
257
258
|
| `ask_user` | read | never (it is the agent talking to you; subagents never get it) |
|
|
258
259
|
| `read_settings` | read | never (MCP `env` / header values are shown as `<redacted>`) |
|
|
259
|
-
| `edit_config`, `set_mcp_server`, `remove_mcp_server`, `create_agent_type` | settings | **
|
|
260
|
+
| `edit_config`, `set_mcp_server`, `remove_mcp_server`, `create_agent_type` | settings | **yes, in every mode but `auto`, with no "always" option** (shows the diff or the server's command) |
|
|
260
261
|
|
|
261
262
|
File tools writing under a `.dostuff` directory, and `bash_command` calls whose command or `cwd` names `.dostuff`, are
|
|
262
|
-
settings changes too, so
|
|
263
|
-
|
|
264
|
-
command builds indirectly is not caught.
|
|
263
|
+
settings changes too, so `ask` and `allowlist` always prompt for them. Paths into subagent worktrees
|
|
264
|
+
(`.dostuff/worktrees/…`) are exempt, apart from the secrets copied there. The shell check matches the text `.dostuff`,
|
|
265
|
+
so a name the command builds indirectly is not caught.
|
|
266
|
+
|
|
267
|
+
Reading is not a settings change: a read-only shell command on `.dostuff` (`ls .dostuff/agents`, `cat
|
|
268
|
+
~/.dostuff/config.yaml`) runs like any other, plan mode included. Only the part of a pipeline that names the path has to
|
|
269
|
+
be a read, so `grep FAIL ~/.dostuff/jobs/<session>/<job>.out | sed … | sort -u` is fine. The same paths `read_file` can
|
|
270
|
+
open qualify, so in `ask` and `allowlist` these still ask: `.env*` files and `mcp_config.json` (in a `.dostuff` dir, or
|
|
271
|
+
the legacy one at the project root), a wildcard in the path, a command that changes directory, a `cwd` other than the
|
|
272
|
+
project root, and `grep` / `rg` / `Select-String` over all of a `.dostuff` dir, `.dostuff/worktrees` or one worktree,
|
|
273
|
+
which would reach `.env`.
|
|
265
274
|
|
|
266
275
|
`permissions.mode` in `config.yaml`:
|
|
267
276
|
|
|
268
277
|
- `ask` (default) — as in the table above.
|
|
269
278
|
- `allowlist` — as `ask`, plus the patterns in `permissions.allow` run without asking (a shell command prefix such as `npm test`, a tool name such as `write_file`, `call_mcp_tool:<server>__<tool>`, `web_fetch:<domain>`, or `web_search`).
|
|
270
|
-
- `auto` — nothing asks. A red warning is shown at startup.
|
|
279
|
+
- `auto` — nothing asks, so the agent never stops to wait for approval. That includes settings changes: it can add hooks and MCP servers, create agents and skills, and change most of `.dostuff`, so use it only where you would let it do all of that. It refuses two things, and the call fails at once so the agent carries on: secrets (a `.env*` file, `mcp_config.json` or `.dostuff/data` named in a command, or a search that would reach one) and its own limits (`permissions`, `hooks.project_trust`, `trusted_hooks.json`). `config.yaml` changes only through `edit_config`, which can check them. There is no classifier reviewing commands, and the shell checks match text, so this is a guard against mistakes, not a sandbox. A `PreToolUse` hook that asks still prompts, because you configured it, and so does the one-time trust check for project hooks. A red warning is shown at startup.
|
|
271
280
|
- `plan` — read-only: reads and read-only shell commands run; file changes, other shell commands and settings changes are denied with a "plan mode" note, and the model is told to investigate and answer with a plan. Web and MCP calls ask as in `ask`.
|
|
272
281
|
|
|
273
282
|
In the TUI, `Shift+Tab` cycles the mode for the session (ask → auto → plan → allowlist); `/permissions <mode>` picks one.
|
|
274
283
|
|
|
275
284
|
Answering `a` (always) approves that tool, or for the shell those commands, for the rest of the session.
|
|
276
285
|
|
|
286
|
+
`edit_file` and `multi_edit` grant the same thing, so a rule for either covers both: in `permissions.allow`, in
|
|
287
|
+
`--allowed-tools`, and for `a` (always). It stops there: neither covers `write_file` or `delete_file`.
|
|
288
|
+
|
|
277
289
|
**Changing settings by asking.** Instead of editing `~/.dostuff/config.yaml` or `mcp_config.json` by hand, ask
|
|
278
290
|
the agent: "hide the session id in the status bar", "set max_iterations to 50 for this project", "add the GitHub
|
|
279
291
|
MCP server". It reads the settings with `read_settings`, changes `config.yaml` with `edit_config` (an exact-text
|
|
@@ -281,13 +293,13 @@ edit that keeps your comments, checked to be valid YAML) and adds, updates or re
|
|
|
281
293
|
`set_mcp_server` / `remove_mcp_server`, in the user files (`~/.dostuff/`) or the project's (`./.dostuff/`).
|
|
282
294
|
Changes apply at once, without a restart (MCP servers connect or disconnect; tracing changes need a restart).
|
|
283
295
|
Because these files hold the permission rules and an MCP server is a command that runs on your machine, every
|
|
284
|
-
change asks,
|
|
296
|
+
change asks, except in `auto` mode, and so do `write_file` / `edit_file` / `multi_edit` on anything in a `.dostuff` folder.
|
|
285
297
|
API keys stay in `.env` files, which the agent can't read or change. Subagents don't get these tools.
|
|
286
298
|
|
|
287
299
|
> [!IMPORTANT]
|
|
288
300
|
> File tools are sandboxed to the project directory (the directory the session runs in): paths that resolve
|
|
289
|
-
> outside it are rejected, except that
|
|
290
|
-
>
|
|
301
|
+
> outside it are rejected, except that `.dostuff` (the project's and `~/.dostuff/`) and discovered skill folders
|
|
302
|
+
> can be read (never written), and `.env*` files, `mcp_config.json` and `.dostuff/data` cannot be read. **The shell is not sandboxed**:
|
|
291
303
|
> `bash_command` can touch anything your user can, which is why non-read-only commands ask first.
|
|
292
304
|
> The shell is Git Bash / `bash` when found, otherwise PowerShell on Windows or `/bin/sh`.
|
|
293
305
|
|
|
@@ -604,7 +616,7 @@ You are a code reviewer. Report findings as a list, most severe first.
|
|
|
604
616
|
|---|---|
|
|
605
617
|
| `Read` | `read_file` |
|
|
606
618
|
| `Write` | `write_file` |
|
|
607
|
-
| `Edit`, `MultiEdit` | `edit_file` |
|
|
619
|
+
| `Edit`, `MultiEdit` | `edit_file`, `multi_edit` |
|
|
608
620
|
| `Glob` / `Grep` / `LS` | `glob` / `grep` / `list_files` |
|
|
609
621
|
| `Bash` | `bash_command` (plus `bash_output`, `kill_shell`) |
|
|
610
622
|
| `WebFetch` / `WebSearch` | `web_fetch` / `web_search` |
|
|
@@ -683,8 +695,15 @@ matcher and tool argument names are renamed (see [the table below](#coming-from-
|
|
|
683
695
|
|
|
684
696
|
`matcher` is a Python regex that must match the whole name (`edit_file` does not match `edit_file_v2`); empty or `*`
|
|
685
697
|
matches everything. `if` (tool events only) is searched in a `bash_command`'s `command`. Inline flags such as `(?i)`
|
|
686
|
-
go first in a pattern. `timeout` (default 30 s, 1–300) and `fail_closed` can be set on a group or on one hook.
|
|
687
|
-
|
|
698
|
+
go first in a pattern. `timeout` (default 30 s, 1–300) and `fail_closed` can be set on a group or on one hook.
|
|
699
|
+
|
|
700
|
+
A tool matcher that matches `edit_file` also fires for `multi_edit`, so a guard or a formatter on `edit_file` holds for
|
|
701
|
+
the same change made through `multi_edit`. It does not work the other way: a `multi_edit` matcher skips `edit_file`. The
|
|
702
|
+
payload stays true to the call, with `tool_name` set to `multi_edit` and `tool_input` to `{path, edits}`. A script that
|
|
703
|
+
reads `tool_input.path` keeps working; one that reads `tool_input.old_str` gets nothing there and needs to read `edits`.
|
|
704
|
+
A hook that rewrites `old_str` / `new_str` makes a `multi_edit` call fail with a tool error, and nothing is written.
|
|
705
|
+
|
|
706
|
+
This is the example from the spec, and the two scripts it runs are below:
|
|
688
707
|
|
|
689
708
|
```yaml
|
|
690
709
|
hooks:
|
|
@@ -840,6 +859,7 @@ nesting are the same. Tool names and some argument names differ, so rename the m
|
|
|
840
859
|
| `Bash` | `bash_command` | none (`command`, plus `cwd`, `timeout`) |
|
|
841
860
|
| `Write` | `write_file` | `file_path` → `path` |
|
|
842
861
|
| `Edit` | `edit_file` | `file_path` → `path`, `old_string`/`new_string` → `old_str`/`new_str` |
|
|
862
|
+
| `MultiEdit` | `multi_edit` | `file_path` → `path`, and inside `edits`, `old_string`/`new_string` → `old_str`/`new_str` |
|
|
843
863
|
| `Read` | `read_file` | `file_path` → `path` |
|
|
844
864
|
| `Grep` / `Glob` | `grep` / `glob` | per tool |
|
|
845
865
|
| `AskUserQuestion` | `ask_user` | `multiSelect` → `multi_select`; the answers come back as the tool's result |
|
|
@@ -910,7 +930,7 @@ See [`config.example.yaml`](https://github.com/kVarunkk/DoStuff/blob/package-str
|
|
|
910
930
|
|
|
911
931
|
### `.env`
|
|
912
932
|
|
|
913
|
-
**Never put secrets in `config.yaml`.** Use `~/.dostuff/.env` and/or project-local `<cwd>/.dostuff/.env`. Both are read; project values override user values, and real environment variables override both:
|
|
933
|
+
**Never put secrets in `config.yaml`.** `edit_config` refuses them, `/config` warns, and `dostuff doctor` flags any already there. Use `~/.dostuff/.env` and/or project-local `<cwd>/.dostuff/.env`. Both are read; project values override user values, and real environment variables override both:
|
|
914
934
|
|
|
915
935
|
```bash
|
|
916
936
|
# ~/.dostuff/.env (chmod 600 on Unix)
|
|
@@ -977,32 +997,40 @@ Manage servers with `dostuff mcp list` / `add` / `remove` instead of editing the
|
|
|
977
997
|
"tavily": {
|
|
978
998
|
"transport": "stdio",
|
|
979
999
|
"command": "npx",
|
|
980
|
-
"args": ["-y", "@tavily/mcp-server"]
|
|
981
|
-
"env": { "TAVILY_API_KEY": "tvly-..." }
|
|
1000
|
+
"args": ["-y", "@tavily/mcp-server"]
|
|
982
1001
|
},
|
|
983
1002
|
"github": {
|
|
984
1003
|
"transport": "stdio",
|
|
985
1004
|
"command": "uvx",
|
|
986
1005
|
"args": ["mcp-server-github"],
|
|
987
|
-
"env": { "GITHUB_TOKEN": "
|
|
1006
|
+
"env": { "GITHUB_TOKEN": "${MY_WORK_GITHUB_KEY}" }
|
|
988
1007
|
},
|
|
989
1008
|
"remote": {
|
|
990
1009
|
"transport": "http",
|
|
991
1010
|
"url": "https://mcp.example.com/sse",
|
|
992
|
-
"headers": { "Authorization": "Bearer
|
|
1011
|
+
"headers": { "Authorization": "Bearer ${SEARCH_API_KEY}" }
|
|
993
1012
|
}
|
|
994
1013
|
}
|
|
995
1014
|
}
|
|
996
1015
|
```
|
|
997
1016
|
|
|
1017
|
+
**Keys go in `.dostuff/.env`, not in this file.** `${NAME}` in `headers` and `env` is replaced from `.env` (or the real environment) when the server connects:
|
|
1018
|
+
|
|
1019
|
+
- **HTTP server:** you pick the name. It only links the two files, so `SEARCH_API_KEY=...` in `.env` matches `${SEARCH_API_KEY}` above.
|
|
1020
|
+
- **Local (stdio) server:** the server picks the name, so copy it from the server's docs. It inherits `.env`, so a key under that exact name needs no `env` entry (`tavily` above reads `TAVILY_API_KEY`). Use `env` to pass a key you saved under another name (`github` above).
|
|
1021
|
+
|
|
1022
|
+
Only the exact form `${NAME}` is replaced, and only in `headers` and `env`. If a variable is missing or empty the server doesn't connect, and the error names it; after adding it, restart dostuff. `dostuff doctor` reports missing variables and plain keys left in the file, and `/config` and `dostuff mcp add` warn about them. On the command line use single quotes, so your shell doesn't expand the name itself: `dostuff mcp add search --url https://mcp.example.com -H 'Authorization: Bearer ${SEARCH_API_KEY}'`.
|
|
1023
|
+
|
|
1024
|
+
A server's `url` receives whatever its headers name, so read a project's `.dostuff/mcp_config.json` before you run dostuff in a repository you don't trust, just as you would for a `command` it runs.
|
|
1025
|
+
|
|
998
1026
|
| Field | Required for | Notes |
|
|
999
1027
|
| ----------- | ------------ | ------------------------------ |
|
|
1000
1028
|
| `transport` | optional | `stdio` (default) or `http` |
|
|
1001
1029
|
| `command` | stdio | Executable (`npx`, `uvx`, ...) |
|
|
1002
1030
|
| `args` | stdio | Argument list |
|
|
1003
|
-
| `env` | stdio | Env vars for the child process |
|
|
1031
|
+
| `env` | stdio | Env vars for the child process, added to what it inherits; `${NAME}` is read from `.env` |
|
|
1004
1032
|
| `url` | http | Remote MCP server URL |
|
|
1005
|
-
| `headers` | http | HTTP headers
|
|
1033
|
+
| `headers` | http | HTTP headers; `${NAME}` is read from `.env` |
|
|
1006
1034
|
| `connect_timeout` | optional | Seconds before giving up on this server (default 150, enough for a browser OAuth login) |
|
|
1007
1035
|
|
|
1008
1036
|
MCP servers connect concurrently in the background, so the TUI never blanks during boot. Each server is announced in the chat area upon successful or failed connection.
|
|
@@ -1073,6 +1101,20 @@ Detailed instructions for the agent go here.
|
|
|
1073
1101
|
|
|
1074
1102
|
**Running a skill yourself:** each skill is also a slash command, `/<name> [arguments]` (e.g. `/my-skill src/app.py`), in the TUI and with `dostuff -p "/my-skill ..."`. The turn's message is the skill's `SKILL.md` body plus your arguments (which can use `@path` mentions), so the model follows it straight away instead of deciding whether to read it. The command shows in the `/` menu marked `(skill)` and in `/help`. Built-in commands win a name clash, the first skill found (in the order above) wins between skills, and names with spaces can't be run this way; the model can still use those skills on its own.
|
|
1075
1103
|
|
|
1104
|
+
**Manual-only skills:** add `disable-model-invocation: true` to the frontmatter and the model is not told about the skill. It is left out of the system prompt and every subagent's prompt, so it only runs when you ask for it, with `/<name>` or a mention (below). It stays in the `/` menu and `/help`, and the `Skills loaded` line at startup marks it `(manual only)`. Only `false`, `no`, `off`, `0` or an empty value leave a skill visible to the model; anything else, a typo included, hides it.
|
|
1105
|
+
|
|
1106
|
+
> [!IMPORTANT]
|
|
1107
|
+
> `disable-model-invocation` is **not a security boundary**. It stops the model from discovering and choosing the
|
|
1108
|
+
> skill; it does not block anything. The skill's folder stays readable by the file tools, a project skill is an
|
|
1109
|
+
> ordinary project file, and the shell can read whatever your user can. To guarantee a dangerous command never runs,
|
|
1110
|
+
> put a `PreToolUse` [hook](#hooks) on that command.
|
|
1111
|
+
|
|
1112
|
+
**Mentioning a skill:** write `/<name>` inside a message, as in `go ahead and /deploy`, to make that skill available for that message. This is how the model gets to use a manual-only skill, and it works for any skill. The `SKILL.md` is not expanded: the model gets a note after your message with the skill's name, description and folder, and judges from your wording, so `don't run /deploy yet` works. You keep seeing the message as you typed it, plus a line, `Skill available for this message: deploy`; if that line is missing, the name wasn't recognised. It works in prompts, queued prompts, steering messages and `dostuff -p`. The permission lasts for that message, and subagents don't inherit it.
|
|
1113
|
+
|
|
1114
|
+
A mention follows a space or a new line, can be any case, and may end in one `.`, `,`, `!`, `?`, `:` or `;`. So `` `/deploy` ``, `(/deploy)` and `/deploy/x` are not mentions, and neither is a path like `/tmp/notes.md`. Custom commands can't be mentioned. Only what you type counts: a `/deploy` inside an `@file` or a paste collapsed to `[Pasted text #1 …]` grants nothing. A message that starts with a skill or custom command is that command's run, so `/review then /deploy` grants nothing for `deploy`.
|
|
1115
|
+
|
|
1116
|
+
While you type, `/` after a space opens the menu with skills only. Tab and Enter there replace just that word: your sentence stays and nothing is sent until the next Enter.
|
|
1117
|
+
|
|
1076
1118
|
Run `dostuff init` to bootstrap a local `.dostuff/skills/` folder. Restart the agent after adding new skills.
|
|
1077
1119
|
|
|
1078
1120
|
### Custom commands
|
|
@@ -25,10 +25,11 @@ def _background_wait(interactive: bool) -> str:
|
|
|
25
25
|
|
|
26
26
|
|
|
27
27
|
def skills_summary(skills: list[dict[str, Any]]) -> str:
|
|
28
|
-
"""The skills list as the system prompt shows it
|
|
28
|
+
"""The skills list as the system prompt shows it: every prompt goes through here, so a manual-only skill
|
|
29
|
+
(`disable-model-invocation`) is left out in this one place."""
|
|
29
30
|
summary = "\n\n".join(
|
|
30
31
|
f"- name: {s['name']}\n description: {s['description']}\n dir: {s['dir']}"
|
|
31
|
-
for s in skills
|
|
32
|
+
for s in skills if not s.get("disable_model_invocation")
|
|
32
33
|
)
|
|
33
34
|
return summary or "(none available)"
|
|
34
35
|
|