dostuff 0.2.14__tar.gz → 0.2.16__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (211) hide show
  1. {dostuff-0.2.14 → dostuff-0.2.16}/PKG-INFO +113 -35
  2. {dostuff-0.2.14 → dostuff-0.2.16}/README.md +112 -34
  3. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/agent/call_agent.py +35 -8
  4. dostuff-0.2.16/dostuff/agent/capabilities.py +163 -0
  5. dostuff-0.2.16/dostuff/agent/instructions.py +173 -0
  6. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/agent/loop.py +155 -13
  7. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/agent/subagents/__init__.py +2 -0
  8. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/agent/subagents/definitions.py +81 -6
  9. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/agent/subagents/fork.py +15 -4
  10. dostuff-0.2.16/dostuff/agent/subagents/prompt.py +129 -0
  11. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/agent/subagents/registry.py +23 -6
  12. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/agent/subagents/run.py +19 -2
  13. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/cli.py +221 -0
  14. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/cli_tui.py +1132 -124
  15. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/config.py +34 -0
  16. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/headless.py +25 -6
  17. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/agent/constants.py +30 -11
  18. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/agent/context_usage.py +7 -2
  19. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/agent/tool_output.py +29 -0
  20. dostuff-0.2.16/dostuff/helpers/agent/turn_context.py +334 -0
  21. dostuff-0.2.16/dostuff/helpers/extras.py +40 -0
  22. dostuff-0.2.16/dostuff/helpers/memory/consolidate.py +131 -0
  23. dostuff-0.2.16/dostuff/helpers/memory/repair_index.py +214 -0
  24. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/memory/resolve_memory_operation.py +9 -5
  25. dostuff-0.2.16/dostuff/helpers/memory/same_episode.py +33 -0
  26. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/skills/discover_skills.py +45 -10
  27. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/skills/skill_command.py +12 -2
  28. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/ui/doctor.py +26 -2
  29. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/ui/tools_listing.py +14 -1
  30. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/lib/mcp/mcp_tool_registry_store.py +5 -6
  31. dostuff-0.2.16/dostuff/lib/memory/backend.py +55 -0
  32. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/lib/memory/chroma.py +15 -0
  33. dostuff-0.2.16/dostuff/lib/memory/episodic_memory_store.py +266 -0
  34. dostuff-0.2.16/dostuff/lib/memory/hybrid_memory_store.py +391 -0
  35. dostuff-0.2.16/dostuff/lib/memory/migrate.py +118 -0
  36. dostuff-0.2.16/dostuff/lib/memory/safe_query.py +141 -0
  37. dostuff-0.2.16/dostuff/lib/memory/semantic_memory_store.py +143 -0
  38. dostuff-0.2.16/dostuff/lib/memory/sqlite_memory_store.py +562 -0
  39. dostuff-0.2.16/dostuff/lib/memory/stores.py +145 -0
  40. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/lib/model.py +14 -0
  41. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/setup_wizard.py +16 -1
  42. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/templates/config.example.yaml +5 -0
  43. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/tools/agent.py +3 -2
  44. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/tools/ask_user.py +15 -9
  45. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/tools/bash/jobs.py +61 -3
  46. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/tools/create_agent_type.py +11 -3
  47. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/tools/definitions.py +7 -4
  48. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/tools/memory/save_episode.py +28 -8
  49. dostuff-0.2.16/dostuff/tools/memory/save_memory.py +54 -0
  50. dostuff-0.2.16/dostuff/tools/memory/search_memory.py +141 -0
  51. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/tools/names.py +1 -0
  52. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/tools/web_search.py +10 -0
  53. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff.egg-info/PKG-INFO +113 -35
  54. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff.egg-info/SOURCES.txt +24 -0
  55. {dostuff-0.2.14 → dostuff-0.2.16}/pyproject.toml +5 -1
  56. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_ask_user.py +9 -9
  57. dostuff-0.2.16/tests/test_capabilities.py +547 -0
  58. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_checkpoints_todos_caching.py +68 -1
  59. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_cli_commands.py +64 -2
  60. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_config_memory_mcp.py +175 -11
  61. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_create_agent_type.py +9 -0
  62. dostuff-0.2.16/tests/test_episode_index.py +113 -0
  63. dostuff-0.2.16/tests/test_extras.py +100 -0
  64. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_jobs.py +18 -1
  65. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_loop.py +436 -4
  66. dostuff-0.2.16/tests/test_memory_delivery.py +552 -0
  67. dostuff-0.2.16/tests/test_memory_fts5_fallback.py +123 -0
  68. dostuff-0.2.16/tests/test_memory_hybrid_store.py +227 -0
  69. dostuff-0.2.16/tests/test_memory_index_divergence.py +262 -0
  70. dostuff-0.2.16/tests/test_memory_index_repair.py +162 -0
  71. dostuff-0.2.16/tests/test_memory_migrate.py +273 -0
  72. dostuff-0.2.16/tests/test_memory_recall_eval.py +376 -0
  73. dostuff-0.2.16/tests/test_memory_sqlite_store.py +174 -0
  74. dostuff-0.2.16/tests/test_memory_store_scope.py +502 -0
  75. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_optional_memory_and_instructions.py +39 -15
  76. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_roadmap_021.py +21 -0
  77. dostuff-0.2.16/tests/test_search_memory.py +322 -0
  78. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_subagents_background.py +1 -1
  79. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_subagents_fork.py +41 -12
  80. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_subagents_run.py +125 -2
  81. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_subagents_store.py +1 -1
  82. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_subagents_types.py +175 -1
  83. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_tui.py +1557 -59
  84. dostuff-0.2.16/tests/test_turn_context.py +413 -0
  85. dostuff-0.2.14/dostuff/agent/instructions.py +0 -112
  86. dostuff-0.2.14/dostuff/agent/subagents/prompt.py +0 -53
  87. dostuff-0.2.14/dostuff/helpers/agent/turn_context.py +0 -58
  88. dostuff-0.2.14/dostuff/lib/memory/episodic_memory_store.py +0 -164
  89. dostuff-0.2.14/dostuff/lib/memory/semantic_memory_store.py +0 -80
  90. dostuff-0.2.14/dostuff/lib/memory/stores.py +0 -44
  91. dostuff-0.2.14/dostuff/tools/memory/save_memory.py +0 -40
  92. dostuff-0.2.14/tests/test_turn_context.py +0 -197
  93. {dostuff-0.2.14 → dostuff-0.2.16}/LICENSE +0 -0
  94. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/__init__.py +0 -0
  95. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/__main__.py +0 -0
  96. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/agent/permissions.py +0 -0
  97. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/agent/run_tool.py +0 -0
  98. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/agent/subagents/adapter.py +0 -0
  99. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/agent/append_step.py +0 -0
  100. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/agent/attachments.py +0 -0
  101. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/agent/clipboard.py +0 -0
  102. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/agent/consume_stream.py +0 -0
  103. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/agent/convert_document.py +0 -0
  104. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/agent/environment_context.py +0 -0
  105. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/agent/file_mentions.py +0 -0
  106. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/agent/get_model_token_limit.py +0 -0
  107. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/agent/load_identity.py +0 -0
  108. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/agent/load_project_instructions.py +0 -0
  109. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/agent/loop_check_cancelled.py +0 -0
  110. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/agent/loop_emit.py +0 -0
  111. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/agent/manage_context.py +0 -0
  112. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/agent/model_cost.py +0 -0
  113. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/agent/notices.py +0 -0
  114. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/agent/pastes.py +0 -0
  115. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/agent/quick_memory.py +0 -0
  116. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/agent/side_question.py +0 -0
  117. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/agent/slash_suggestion.py +0 -0
  118. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/agent/steering.py +0 -0
  119. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/agent/tool_attachments.py +0 -0
  120. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/config_secrets.py +0 -0
  121. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/hooks/__init__.py +0 -0
  122. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/hooks/dispatch.py +0 -0
  123. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/hooks/events.py +0 -0
  124. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/hooks/load_hooks.py +0 -0
  125. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/hooks/run_hook.py +0 -0
  126. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/hooks/trust.py +0 -0
  127. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/mcp/load_mcp_config.py +0 -0
  128. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/mcp/mcp_oauth.py +0 -0
  129. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/mcp/server_config.py +0 -0
  130. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/mcp/token_store.py +0 -0
  131. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/memory/export_session.py +0 -0
  132. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/memory/shell_step.py +0 -0
  133. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/models/add_model_entry.py +0 -0
  134. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/models/list_models.py +0 -0
  135. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/models/opencode.py +0 -0
  136. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/skills/custom_commands.py +0 -0
  137. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/tools/diff.py +0 -0
  138. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/tools/generate_tool_schema.py +0 -0
  139. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/tools/project_root.py +0 -0
  140. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/tools/resolve_safe_path.py +0 -0
  141. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/ui/__init__.py +0 -0
  142. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/ui/ask_answers.py +0 -0
  143. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/ui/emit.py +0 -0
  144. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/ui/prompt_history.py +0 -0
  145. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/helpers/ui/terminal_signals.py +0 -0
  146. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/lib/checkpoints.py +0 -0
  147. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/lib/exceptions.py +0 -0
  148. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/lib/mcp/mcp_client.py +0 -0
  149. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/lib/mcp/mcp_client_registration_store.py +0 -0
  150. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/lib/memory/session_store.py +0 -0
  151. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/lib/memory/types.py +0 -0
  152. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/lib/tracing.py +0 -0
  153. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/lib/worktree.py +0 -0
  154. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/memory/__init__.py +0 -0
  155. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/skills.py +0 -0
  156. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/templates/env.example +0 -0
  157. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/tools/__init__.py +0 -0
  158. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/tools/bash/bash_command.py +0 -0
  159. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/tools/bash/bash_output.py +0 -0
  160. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/tools/bash/kill_shell.py +0 -0
  161. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/tools/files/delete_file.py +0 -0
  162. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/tools/files/edit_file.py +0 -0
  163. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/tools/files/list_files.py +0 -0
  164. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/tools/files/multi_edit.py +0 -0
  165. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/tools/files/read_file.py +0 -0
  166. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/tools/files/write_file.py +0 -0
  167. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/tools/get_current_datetime.py +0 -0
  168. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/tools/mcp/call_mcp_tool.py +0 -0
  169. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/tools/mcp/get_mcp_tool_details.py +0 -0
  170. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/tools/mcp/search_mcp_tools.py +0 -0
  171. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/tools/search/glob.py +0 -0
  172. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/tools/search/grep.py +0 -0
  173. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/tools/search/walk.py +0 -0
  174. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/tools/send_message.py +0 -0
  175. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/tools/settings.py +0 -0
  176. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/tools/stop_agent.py +0 -0
  177. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/tools/todo_write.py +0 -0
  178. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff/tools/web_fetch.py +0 -0
  179. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff.egg-info/dependency_links.txt +0 -0
  180. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff.egg-info/entry_points.txt +0 -0
  181. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff.egg-info/requires.txt +0 -0
  182. {dostuff-0.2.14 → dostuff-0.2.16}/dostuff.egg-info/top_level.txt +0 -0
  183. {dostuff-0.2.14 → dostuff-0.2.16}/setup.cfg +0 -0
  184. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_attachments.py +0 -0
  185. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_bash_command.py +0 -0
  186. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_export_session.py +0 -0
  187. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_file_mentions.py +0 -0
  188. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_file_tools.py +0 -0
  189. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_hooks.py +0 -0
  190. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_mcp_e2e.py +0 -0
  191. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_mcp_env_references.py +0 -0
  192. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_mcp_oauth.py +0 -0
  193. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_opencode.py +0 -0
  194. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_pastes.py +0 -0
  195. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_permissions.py +0 -0
  196. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_session_store.py +0 -0
  197. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_settings_tools.py +0 -0
  198. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_setup_wizard.py +0 -0
  199. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_side_question.py +0 -0
  200. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_side_question_litellm.py +0 -0
  201. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_skill_command.py +0 -0
  202. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_skills_discovery.py +0 -0
  203. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_slash_suggestion.py +0 -0
  204. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_steering.py +0 -0
  205. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_subagent.py +0 -0
  206. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_terminal_signals.py +0 -0
  207. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_tool_schemas.py +0 -0
  208. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_tools_listing.py +0 -0
  209. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_web_fetch.py +0 -0
  210. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_web_search.py +0 -0
  211. {dostuff-0.2.14 → dostuff-0.2.16}/tests/test_worktree.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: dostuff
3
- Version: 0.2.14
3
+ Version: 0.2.16
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
@@ -85,7 +85,7 @@ DoStuff is a terminal AI agent that runs anywhere `pip` runs. It gives you a ful
85
85
  - **Multi-provider LLMs** via [litellm](https://docs.litellm.ai/docs/providers) — OpenAI, Anthropic, Gemini, Groq, Mistral, Ollama, OpenRouter, OpenCode Zen / Go
86
86
  - **Persistent sessions** in SQLite; resume with `dostuff -c`, `dostuff resume` or `dostuff --session <id>`, branch one off with `/fork`
87
87
  - **Git worktrees** — `/worktree` or `dostuff -w` runs a session on its own branch and checkout; subagents can run in their own worktree too
88
- - **Long-term memory** (semantic + episodic) backed by ChromaDB — optional, `pip install "dostuff[memory]"`
88
+ - **Long-term memory** (semantic + episodic) in a local SQLite file, searched by keywords and, with `pip install "dostuff[memory]"`, by meaning
89
89
  - **MCP server support** — stdio (npx, uvx) and HTTP transports
90
90
  - **`@file` mentions** — type `@` in the prompt to pick a file or folder; its content (or listing) is sent with the message
91
91
  - **Project instructions** — `AGENTS.md` / `CLAUDE.md` from `~/.dostuff/`, the repo root and every folder down to the current one, combined
@@ -97,16 +97,17 @@ DoStuff is a terminal AI agent that runs anywhere `pip` runs. It gives you a ful
97
97
  - **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)
98
98
  - **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)
99
99
  - **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
100
- - **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)
100
+ - **Skills loader** — drop a `SKILL.md` in the right folder and the agent is told about it on your next message, no restart; 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)
101
101
  - **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)
102
102
  - **Per-tool timeout** (120s) to prevent hung servers; long tool output is truncated (head + tail) before it reaches the model
103
103
  - **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
104
+ - **Output-limit recovery** — a reply the provider stops at its output-token cap is never taken as the answer: the model is told it was cut off and continues (3 times in a row at most, then the turn ends with the text marked incomplete), and a tool call whose arguments were cut off is reported as such so the model retries it smaller. `loop.max_tokens` sets the cap for every model call, main agent and subagents (unset: the provider's default — on Anthropic-style routes, such as Claude or MiniMax through OpenCode Go, litellm then sends 4096 for models it doesn't know); an agent file's `max_tokens:` overrides it for that type, e.g. one that writes long files. If the provider rejects a cap above the model's limit, the error says which setting sent it
104
105
  - **Token and cost tracking** — per-turn and cumulative totals in `/status` and the line after each turn (`✻ Worked for 1m 5s · $0.01`); cost in USD from litellm's price table (hidden when the model has no known price). The table bundled with litellm is used, so startup doesn't wait on a download; set `LITELLM_LOCAL_MODEL_COST_MAP=False` to fetch the latest one from GitHub instead
105
- - **Long-term memory tools** — the agent saves facts (`save_memory`) and notable moments (`save_episode`) as they come up; both are recalled in later sessions
106
+ - **Long-term memory tools** — the agent saves facts (`save_memory`, about you or about this project) and notable moments (`save_episode`) as they come up; saved facts (up to 50, newest first) are shown to the agent in later sessions, episodes related to the prompt are recalled, the agent looks up older ones with `search_memory`, and `/memories consolidate` merges overlapping facts after showing you the change
106
107
  - **Graceful exit** — `Ctrl+Q` or `/exit` saves the session, cleans up, and stops background workers
107
108
  - **Clean Cancellation** — `Escape` can cancel in-flight agent turns cleanly without corrupting the session
108
109
  - **2-state session split** — `session_steps` (full audit) / `working_history` (LLM payload); DB persists both plus `compaction_notes` + `last_input_tokens`
109
- - **Auto & Manual Compaction** — Manual `/compact` runs compaction and saves it. Auto-compaction triggers automatically during the agent loop if context usage (`last_input_tokens`) exceeds `loop.auto_compact_threshold` (default 50%) of the model's token limit; `off` disables it (an overflowing window is still compacted), and `/compact auto <N|off>` changes it for the session. It keeps at least 15% or 20k tokens of the most recent steps in the working history, summarizing the rest into `compaction_notes` which are appended to system instructions.
110
+ - **Auto & Manual Compaction** — Manual `/compact` runs compaction and saves it. Auto-compaction triggers automatically during the agent loop if context usage (`last_input_tokens`) exceeds `loop.auto_compact_threshold` (default 50%) of the model's token limit; `off` disables it (an overflowing window is still compacted), and `/compact auto <N|off>` changes it for the session. It keeps at least 15% or 20k tokens of the most recent steps in the working history, summarizing the rest into `compaction_notes` which are appended to system instructions. Each subagent compacts its own history at the same percent of its own model's window, unless `agents.compact_threshold` or the agent file's `compact_threshold:` sets another (`/agents types <name>` shows which applies).
110
111
  - **Tracing (opt-in)** — OTLP tracing support built into `lib/tracing.py`; prompt and tool content are redacted from spans by default
111
112
 
112
113
  ---
@@ -126,7 +127,7 @@ Optional features come as extras:
126
127
  | Install | Adds |
127
128
  |---|---|
128
129
  | `pip install dostuff` | Everything except the extras below, including MCP (with OAuth tokens kept in the OS keyring) |
129
- | `pip install "dostuff[memory]"` | Long-term memory (facts and past decisions across sessions) and semantic MCP tool search, via ChromaDB. Large download |
130
+ | `pip install "dostuff[memory]"` | Memory recall by meaning as well as by keywords (a reworded question still finds the memory), and semantic MCP tool search, via ChromaDB. Large download. Memory itself works without it |
130
131
  | `pip install "dostuff[search]"` | Steadier `web_search` through the `ddgs` package (several engines) instead of DuckDuckGo's HTML page |
131
132
  | `pip install "dostuff[docs]"` | Word, Excel and PowerPoint files (`.docx`, `.xlsx`, `.pptx`), and PDFs for models that can't read them, converted to text for `@path` and `read_file` (`pypdf`, `python-docx`, `openpyxl`, `python-pptx`) |
132
133
  | `pip install "dostuff[images]"` | Pillow: large images are downscaled to fit the model's limit, and `Alt+V` reads the clipboard directly |
@@ -135,7 +136,8 @@ Optional features come as extras:
135
136
 
136
137
  Extras combine, e.g. `pip install "dostuff[memory,search]"`. Without `memory` everything else
137
138
  works: the memory tools are hidden from the model and MCP tool search matches keywords instead of
138
- meaning. `dostuff doctor` shows whether memory is on.
139
+ meaning. `dostuff doctor` lists every extra, installed or not, with the command that adds it; `dostuff setup`
140
+ ends by naming the ones you don't have, and `/tools` says what each missing one changes about the tools.
139
141
 
140
142
  ### Other install methods
141
143
 
@@ -152,7 +154,7 @@ For development (editable mode, from a clone):
152
154
  git clone https://github.com/kVarunkk/DoStuff.git
153
155
  cd DoStuff
154
156
  pip install -e . # core
155
- pip install -e ".[memory]" # + long-term memory (chromadb)
157
+ pip install -e ".[memory]" # + memory search by meaning (chromadb)
156
158
  pip install -e ".[search]" # + ddgs web search
157
159
  pip install -e ".[full]" # + memory + search
158
160
  pip install -e ".[dev]" # + pytest + mypy
@@ -210,7 +212,8 @@ In the TUI:
210
212
  | `dostuff init [--force]` | Create `.dostuff/` config/skills in current dir (won't overwrite without `--force`) |
211
213
  | `dostuff setup` | Pick a model, save its API key, write `~/.dostuff/config.yaml` (runs automatically on first launch) |
212
214
  | `dostuff config` | Show resolved config paths and values |
213
- | `dostuff doctor` | Health check: config, API key, MCP, data dir; prints a fix for each problem |
215
+ | `dostuff doctor` | Health check: config, API key, MCP, data dir, memory and the optional extras; prints a fix for each problem |
216
+ | `dostuff memory [check\|repair\|consolidate] [-y]` | Check that long-term memory's indexes match what is saved (`check`, the default): the keyword index, and on the default backend the embedding index (memories not indexed, out of date, or forgotten but still indexed). `repair` fixes what `check` found, rebuilding either index from `memory.db`, which it never changes, so nothing saved is lost. On `memory.backend: chroma` it rebuilds a broken Chroma index after "Error finding id" errors, backing it up to `~/.dostuff/data/chroma-backups/` first. Stop dostuff before repairing. `consolidate` asks the model to merge your overlapping saved facts and this project's, shows the change, and writes it only when you say yes (`-y` skips the question; in auto mode it refuses without `-y`) |
214
217
  | `dostuff resume [<id>]` | Resume the latest session started in the current directory (or the given one; a unique ID prefix is enough). `--fork` resumes a copy, `--worktree` moves it into a new worktree |
215
218
  | `dostuff sessions [--all] [-n N]` | List sessions in the current directory with their title or first prompt (`--all`: every directory) |
216
219
  | `dostuff sessions rename <id> <title>` | Name a session |
@@ -242,28 +245,30 @@ In the TUI:
242
245
  | `Up` / `Down` | On the first / last line of the input: previous / next prompt typed in this directory (saved in `~/.dostuff/data/prompt_history.jsonl`) |
243
246
  | `Ctrl+R` | Search the prompts typed in this directory (type to filter, `Enter` puts the prompt in the input) |
244
247
  | `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 |
245
- | `Ctrl+O` | Expand / collapse every truncated tool and shell result (click one to toggle just that one) |
248
+ | `Ctrl+O` | Expand / collapse every tool-call line and truncated shell result, with tool output in full (click one to open just that one, with a preview of each result; click a call in it for that result in full) |
246
249
  | `Ctrl+B` | While the agent waits on a shell command or a foreground subagent (the loader says `Ctrl+B to background`): move them to the background; the agent gets what a command printed so far and carries on, and hears from the agent when it ends. Not for `!command`s. See [Background jobs](#background-jobs) and [Subagents](#subagents) |
247
250
  | `Shift+Tab` | Cycle the permission mode for this session: ask → auto → plan → allowlist (shown in the status bar) |
248
251
  | `Ctrl+Backspace` / `Ctrl+W` / `Alt+Backspace` | Delete the previous word; `Ctrl+Delete` / `Alt+Delete` the next one |
249
- | `/agents` / `/agents types` / `/agents reload` | This session's agents (running first): pick one to read its transcript, answer its approval prompt or stop it / the agent types with their source, model and tools (`/agents types <name>`: one type's system prompt and config) / re-read the agent files |
252
+ | `/agents` / `/agents types` / `/agents reload` | This session's agents (running first): pick one to read its transcript, answer its approval prompt or stop it / the agent types with their source, model and tools (`/agents types <name>`: one type's system prompt and config) / re-read the agent files and rebuild the system prompt from them |
253
+ | `/skills` / `/skills reload` | The skills this session knows: each one's folder, and which are manual only / re-read them now and rebuild the system prompt (reports what was added and removed). See [Skills](#skills) |
250
254
  | `/exit` | Save the session and quit |
251
255
  | `/clear` | Start a new session; the old one stays resumable |
252
- | `/resume [<id>]` | Pick another session from this directory (or switch to the given one) |
256
+ | `/resume [<id>]` | Pick another session from this directory (or switch to the given one). A long session shows its last 60 steps under an `↑ N earlier steps` line; scroll to the top or click the line to load older ones |
253
257
  | `/fork [title] [--worktree]` | Copy this session into a new one and switch to it; the original is unchanged |
254
258
  | `/worktree [name]` / `/worktree exit` | Move the session into a new git worktree on branch `dostuff/<name>` / leave it (removed if unchanged, otherwise keep or remove) |
255
259
  | `/permissions [mode]` | Show or change the permission mode for this session (`ask`, `allowlist`, `auto`, `plan`) |
256
260
  | `/copy` | Copy the model's last answer to the clipboard |
257
261
  | `/btw <question>` | Ask a side question about the conversation, even while a turn runs: answered in a panel above the input, without tools, never added to the history. See [Side questions](#side-questions-btw) |
258
262
  | `/steer <message>` | Send a correction to the running turn: the model reads it at the next tool boundary and carries on, without the turn ending. See [Mid-turn steering](#mid-turn-steering-steer) |
263
+ | `/thinking [level]` | Set how hard the model thinks for this session: `auto` (the provider's default), `off`, `minimal`, `low`, `medium` or `high`; models without reasoning ignore it (default from `loop.reasoning_effort`) |
259
264
  | `/notifications [on\|off\|bell\|osc9]` | Turn turn-finished / approval notifications on or off for this session (default from `ui.notifications`) |
260
265
  | `/model [<provider/model>] [--active]` | Pick a model: your saved ones (`models:` in config.yaml) first, then "More <provider> models…" for each provider's list (type to filter; Enter on no match uses what you typed). A model that isn't saved yet is added to `~/.dostuff/config.yaml`. A plain `/model` switch lasts only for this session; add `--active` (e.g. `/model --active`, or `/model anthropic/claude-sonnet-5-5 --active`) to make it the default that new sessions start with |
261
266
  | `/config [mcp] [project]` | Edit a settings file right in the TUI: pick `config.yaml` or the MCP servers, user (`~/.dostuff`) or project (`./.dostuff`), or name one (`/config mcp project`). `Ctrl+S` checks the file, saves it and applies it without a restart (an invalid file stays open with the error); `Esc` closes, twice if there are unsaved changes. A new file starts with every option commented out. `.env` files aren't offered |
262
267
  | `/status` | Session, directory, model, permission mode, tokens, context use, MCP servers |
263
- | `/context` | What fills the context window: system prompt, turn context (the environment, recalled memories and hook context sent with each prompt), tools, MCP tools, project instructions, compaction summary and messages, with tokens, % and a bar |
268
+ | `/context` | What fills the context window: system prompt, turn context (the environment and hook context sent with the prompts), memory (the saved facts and recalled episodes the model is shown; listed once any are), tools, MCP tools, project instructions, compaction summary and messages, with tokens, % and a bar |
264
269
  | `/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 |
265
- | `/doctor` | The `dostuff doctor` checks (config, API key, MCP config, memory, hooks), with a fix for each problem |
266
- | `/tools` | Every tool the agent has: when it asks (in `ask` mode), whether subagents get it and what it does, then each connected MCP server's tools (reached through `call_mcp_tool`) |
270
+ | `/doctor` | The `dostuff doctor` checks (config, API key, MCP config, memory, optional extras, hooks), with a fix for each problem |
271
+ | `/tools` | Every tool the agent has: when it asks (in `ask` mode), whether subagents get it and what it does, then what each missing optional extra changes, then each connected MCP server's tools (reached through `call_mcp_tool`) |
267
272
  | `/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) |
268
273
  | `/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 |
269
274
  | `/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) |
@@ -274,16 +279,21 @@ In the TUI:
274
279
  | `/export [<path>]` | Save this session as Markdown (default `dostuff-session-<id>.md`) |
275
280
  | `/undo [force]` | Revert the agent's file changes from its last file-editing turn |
276
281
  | `/compact` | Manually trigger context compaction; `/compact auto <1-100\|off>` sets the auto-compaction threshold for this session |
277
- | `/memories` | List the facts saved about you (and where each came from) |
282
+ | `/memories` | List your saved facts and this project's, newest first, with the date each was saved; `/memories consolidate` merges overlapping facts after showing you the change (not in auto mode) |
278
283
  | `/episodes` | List saved episodes (decisions, corrections, fixes) recalled here, newest first |
279
- | `/forget <key or id>` | Delete a saved fact (by key) or episode (by the id shown in `/episodes`) |
284
+ | `/forget <key or id>` | Delete a saved fact (by key: this project's first, `user:<key>` for the user-wide one) or episode (by the id shown in `/episodes`) |
280
285
  | `Ctrl+Q` | Graceful quit with save |
281
286
  | `Escape` | Cancel in-flight turn (also answers "no" to an open approval prompt) |
282
287
  | `/help` | Show available in-TUI commands |
283
288
 
284
289
  **Visual elements:**
285
290
 
286
- - **Messages** — `>` for your prompts (on a grey band), `●` for agent replies and tool calls, `⎿` for tool results; the terminal background shows through
291
+ - **Messages** — `>` for your prompts (on a grey band), `●` for agent replies, `⎿` for tool and shell output; the terminal background shows through
292
+ - **Tool calls** — a run of calls with nothing between them is one line, such as `● Read 2 files, ran 1 shell command`
293
+ (`Reading…` while they run, `· 1 failed` in red when one returned an error). Click it to see each call on its own
294
+ `●` line (blue while it runs, red when it failed) with the start of its result; click a call to see its whole result,
295
+ and again for the start only. `Ctrl+O` opens them all in full. Plans (`todo_write`), `ask_user` questions and
296
+ subagents keep their own `●` line, and file edits still show their diff
287
297
  - **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
288
298
  - **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
289
299
  - **Turn summary** — `✻ Worked for 1m 5s · $0.01 · done 12:59 PM` after each turn
@@ -311,9 +321,10 @@ In the TUI:
311
321
  | `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 |
312
322
  | `call_mcp_tool` | mcp | yes |
313
323
  | `web_fetch` | network | yes; `a` (always) allows that domain for the session |
314
- | `web_search` | network | yes; `a` (always) allows every search for the session. Free: DuckDuckGo by default, the `ddgs` package if installed (`pip install "dostuff[search]"`), or your own SearXNG via `search.searxng_url` |
324
+ | `web_search` | network | yes; `a` (always) allows every search for the session. Free: DuckDuckGo by default, the `ddgs` package if installed (`pip install "dostuff[search]"`), or your own SearXNG via `search.searxng_url`. The first search that falls back to DuckDuckGo's HTML page says so once in the TUI |
315
325
  | `agent`, `send_message`, `stop_agent` | — | no; each subagent's own calls ask, titled with the agent |
316
326
  | `ask_user` | read | never (it is the agent talking to you; subagents never get it) |
327
+ | `save_memory`, `save_episode`, `search_memory` | read | never (each save is shown in the TUI; only with the `memory` extra; subagents never get them) |
317
328
  | `read_settings` | read | never (MCP `env` / header values are shown as `<redacted>`) |
318
329
  | `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) |
319
330
 
@@ -449,9 +460,24 @@ The top line is the tab strip: `▌` marks the question you are on (bold and ora
449
460
  answered, and both sit in the same slot so the tabs never shift as you answer. The submit row is dim until
450
461
  every question has an answer, then it brightens and the parenthetical hint goes away.
451
462
 
452
- - **Nothing submits on one key.** A pick records the answer and moves to the next question; `Submit answers` is
453
- the only thing that sends, and it stays inert (`answer every question first`) until every question has one.
454
- `←`/`Shift+Tab` goes back, so an earlier answer can be changed before submitting.
463
+ - **Nothing submits on one key.** A pick records the answer and moves to the next question; `Submit answers`
464
+ stays inert (`answer every question first`) until every question has one. `←`/`Shift+Tab` goes back, so an
465
+ earlier answer can be changed before submitting.
466
+ - **You review before it sends.** `Submit answers` opens a review of every question with your answer under it;
467
+ the review's own `Submit answers` row is what sends. From the review, `←`/`Shift+Tab` goes back to the
468
+ questions, and Enter on an answer (or its number, or a click) reopens that question to change it:
469
+
470
+ ```
471
+ ✓ DB · ✓ Auth · ▌ Review
472
+ Review your answers
473
+ 1. Which database should I use?
474
+ → Postgres
475
+ 2. Which auth methods?
476
+ → JWT, OAuth
477
+ ────────────────────────────────────────────────────────
478
+ ❯ Submit answers
479
+ ↑/↓ select · Enter on an answer changes it · Enter on Submit sends · ← back · Esc cancel
480
+ ```
455
481
  - **`2-4` options, one line each**, with the trade-off where it matters. A multi-select question toggles with
456
482
  `space` or its number, and the joined answer comes back in option order.
457
483
  - **`Other`** is always the last row, numbered after the options: pick it and the input takes a typed answer (a
@@ -459,8 +485,12 @@ every question has an answer, then it brightens and the parenthetical hint goes
459
485
  in the tab strip; **Enter** (or `o`) on it takes the input, and `←`/`Tab` still move between questions — so
460
486
  landing on a free-text question never traps you in the input. A call where *every* question is free text skips
461
487
  the panel entirely and the input takes each answer in turn, with the last Enter as the submission.
462
- - **Esc** cancels the questions and ends the turn, like Esc on an approval prompt. **Ctrl+Q** / `/exit` with a
488
+ - **Esc** while typing an `Other` answer goes back to the options, recording nothing and keeping the answers you
489
+ already gave. Esc on the options cancels the questions and ends the turn, like Esc on an approval prompt (in a
490
+ call with no panel, where every question is free text, Esc in the input cancels). **Ctrl+Q** / `/exit` with a
463
491
  question open cancel it first and then quit.
492
+ - Long labels and descriptions wrap in full rather than being cut, but the model is told to keep each part short:
493
+ the question one sentence, a label 1-5 words, a description about 15 words at most.
464
494
  - Up to 4 questions per call. The prompt tells the model when to ask: when the answer changes what it builds and
465
495
  the repo can't tell it; never to confirm a plan, to ask permission, or for anything `grep` / `read_file` answers.
466
496
 
@@ -635,9 +665,13 @@ and can stop one with `stop_agent`.
635
665
  | `send_message(to, message, run_in_background)` | Continue an agent. One that has ended runs again with its whole history plus the message; one still running reads it before its next step |
636
666
  | `stop_agent(agent_id)` | Stop a running agent; its shell jobs are killed and its worktree is closed out |
637
667
 
638
- A subagent can never start, message or stop agents, delete files, save memories, write the todo list or change
668
+ A subagent can never start, message or stop agents, delete files, save or search memories, write the todo list or change
639
669
  settings, whatever its type asks for. At most `agents.max_concurrent` (4) run at once; more are queued.
640
670
 
671
+ A typed subagent sees your saved facts (user facts and this project's, read-only) before its first step, the same
672
+ list the main agent gets; `explore`, `plan` and any type with `omit_memory: true` don't. It never gets past episodes.
673
+ A fork already has them in the conversation it inherits.
674
+
641
675
  ### Agent types
642
676
 
643
677
  | Type | Tools | For |
@@ -645,17 +679,19 @@ settings, whatever its type asks for. At most `agents.max_concurrent` (4) run at
645
679
  | `general-purpose` | every subagent tool | research and multi-step tasks, including changing files. The default |
646
680
  | `explore` | read-only (its `bash_command` only runs read-only commands) | finding code and answering where things are; model: `agents.explore_model` |
647
681
  | `plan` | read-only | investigating and returning a step-by-step plan |
648
- | `fork` | the main agent's | a copy of the main agent that inherits the whole conversation (same system prompt, so a Claude model reuses the prompt cache). Costly: only when the task needs the conversation. Always the main model |
682
+ | `fork` | the main agent's list; the ones no subagent gets (starting or messaging agents, memory, todos, `ask_user`, settings) are refused when called | a copy of the main agent that inherits the whole conversation (same system prompt and tool list, so on a Claude model its first call reads the conversation from the prompt cache). Costly: only when the task needs the conversation. Always the main model |
649
683
 
650
684
  Your own types are Markdown files with YAML frontmatter. They are searched in this order, and the first file with a
651
685
  given `name` wins: `.dostuff/agents/` and `.claude/agents/` in the project, then `~/.dostuff/agents/` and
652
686
  `~/.claude/agents/`. `agents.read_claude_agents: false` skips both `.claude` folders. A file can replace a built-in
653
- type, except `fork`. Files are re-read when they change; `/agents reload` forces it.
687
+ type, except `fork`. Files are re-read when they change, and a type added or removed mid-session is announced to the
688
+ agent before its next model call (see [Adding skills mid-session](#adding-skills-and-agent-types-mid-session));
689
+ `/agents reload` re-reads them now and rebuilds the system prompt.
654
690
 
655
691
  You can also ask the agent for one ("make a code-reviewer agent"): its `create_agent_type(name, description, prompt,
656
- tools, model, max_iterations, scope, replace)` tool writes the file to `.dostuff/agents/` (`scope="user"`:
692
+ tools, model, max_iterations, max_tokens, scope, replace)` tool writes the file to `.dostuff/agents/` (`scope="user"`:
657
693
  `~/.dostuff/agents/`) after showing it to you. Like the settings tools, it asks in every mode. The new type can be
658
- started at once.
694
+ started at once, and the agent is told about it before its next step.
659
695
 
660
696
  ```markdown
661
697
  ---
@@ -664,10 +700,21 @@ description: Reviews a diff for bugs and missing tests. Use after a change.
664
700
  tools: Read, Grep, Glob, Bash # omit for every subagent tool
665
701
  model: fast # inherit (default), an alias from agents.models, or a litellm model string
666
702
  max_iterations: 30 # optional; default agents.max_iterations
703
+ max_tokens: 32000 # optional; output-token cap per model call, default loop.max_tokens
704
+ compact_threshold: 30 # optional; auto-compact at this % of its window (1-100 or off), default agents.compact_threshold
705
+ omit_memory: true # optional; leave out your saved facts (default false)
706
+ skills: code-style, testing # optional; these skills' instructions go into its system prompt
667
707
  ---
668
708
  You are a code reviewer. Report findings as a list, most severe first.
669
709
  ```
670
710
 
711
+ `skills:` (a list, or names separated by commas) puts each named skill's `SKILL.md` instructions into the agent's
712
+ system prompt, after the type's own body, so the agent follows them without having to load them first. At most 32
713
+ skills and `agents.max_preload_chars` characters (default 60000) go in. A skill that isn't found, is manual-only or
714
+ can't be read is skipped, and so is everything after the first one that doesn't fit. The run's report starts with a
715
+ `[warning] Skills not preloaded: ...` line naming each skipped skill and the reason. `fork` has no type, so it
716
+ preloads nothing.
717
+
671
718
  `tools:` takes DoStuff names or Claude Code's, so Claude Code agent files work unchanged:
672
719
 
673
720
  | Claude Code | DoStuff |
@@ -684,7 +731,8 @@ Unknown and forbidden names are dropped with a warning naming the file; `/agents
684
731
  source, resolved model, tools and any warnings, and `/agents types <name>` shows one type's whole config: its
685
732
  system prompt, model, tools and max iterations (for `fork`, the task message it gets). `model:` aliases come from `agents.models`; Claude Code's `sonnet`,
686
733
  `opus` and `haiku` are looked up there too and fall back to the main model (with a warning in the report) when they
687
- aren't defined. The call's `model=` wins over the type's `model:`.
734
+ aren't defined. The call's `model=` wins over the type's `model:`. Claude Code's `memory:` field (a per-agent memory
735
+ folder) is ignored with a warning: DoStuff has no per-agent memory.
688
736
 
689
737
  ### Background agents
690
738
 
@@ -722,6 +770,8 @@ agents:
722
770
  wake_on_end: true # a finished background agent resumes the idle TUI
723
771
  read_claude_agents: true # also load .claude/agents/
724
772
  explore_model: inherit # model of the built-in explore type
773
+ max_preload_chars: 60000 # most skill text an agent file's skills: puts in its system prompt
774
+ # compact_threshold: 30 # auto-compaction % for subagents (1-100 or off); default: the main agent's
725
775
  models: # aliases for model: and model=
726
776
  fast: anthropic/claude-haiku-5-5
727
777
  ```
@@ -964,8 +1014,10 @@ loop:
964
1014
  max_tool_output_chars: 30000 # longer tool results keep head + tail
965
1015
  max_retries: 6 # retries on rate limits, timeouts, 5xx (0 = none)
966
1016
  retry_max_delay: 60 # cap on each wait, seconds; Retry-After is honored
1017
+ # max_tokens: 16000 # output-token cap per model call (unset: the provider's default); keep it within the model's output limit
967
1018
 
968
1019
  memory:
1020
+ backend: hybrid # hybrid (default) | sqlite (keywords only) | chroma (the store before hybrid)
969
1021
  episodic_scope: project # recall past episodes from this directory (project) or anywhere (user)
970
1022
 
971
1023
  permissions:
@@ -1159,7 +1211,7 @@ Detailed instructions for the agent go here.
1159
1211
 
1160
1212
  **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.
1161
1213
 
1162
- **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.
1214
+ **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`, where it is marked `manual only`, as it is in the `Skills loaded` line at startup and in `/skills`. Only `false`, `no`, `off`, `0` or an empty value leave a skill visible to the model; anything else, a typo included, hides it.
1163
1215
 
1164
1216
  > [!IMPORTANT]
1165
1217
  > `disable-model-invocation` is **not a security boundary**. It stops the model from discovering and choosing the
@@ -1173,7 +1225,25 @@ A mention follows a space or a new line, can be any case, and may end in one `.`
1173
1225
 
1174
1226
  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.
1175
1227
 
1176
- Run `dostuff init` to bootstrap a local `.dostuff/skills/` folder. Restart the agent after adding new skills.
1228
+ Run `dostuff init` to bootstrap a local `.dostuff/skills/` folder.
1229
+
1230
+ ### Adding skills and agent types mid-session
1231
+
1232
+ No restart is needed. Before every model call dostuff checks the skill folders (a quick look at file sizes and
1233
+ times, a few milliseconds; a skill is re-read only when something moved) and the agent folders. When a skill or agent
1234
+ type was added, removed, or had its `description` changed since the agent was last told, it gets a short hidden note
1235
+ with the name, description and, for a skill, its folder. That includes one the agent made itself mid-turn, e.g. with
1236
+ `create_agent_type`: the note arrives before its next step. You don't see the note in the transcript, but `/name`
1237
+ works for a new skill from your next message, the `/` menu and `/help` list it, and the file tools can read its
1238
+ folder. A removed skill stops being a command and stops being readable at the same moment. Manual-only skills are
1239
+ never announced. Subagents get the same notes for skills that appear while they run.
1240
+
1241
+ The system prompt itself keeps the lists it was built with, so the provider's prompt cache stays warm; the note is
1242
+ added after your message, and a note at the start of a turn joins your message. It is rebuilt when you enter or
1243
+ leave a worktree, save `AGENTS.md` (`/memory`, `# note`), or run `/skills reload` or `/agents reload`. Those two re-read everything now and
1244
+ rebuild the prompt from the next message (the next request then pays one uncached prompt). Use them after
1245
+ editing a skill's `description` on a drive with coarse file times, or whenever you want the prompt itself current.
1246
+ Editing a `SKILL.md` body needs nothing: the agent reads the body when it uses the skill.
1177
1247
 
1178
1248
  ### Custom commands
1179
1249
 
@@ -1200,12 +1270,20 @@ after adding a command.
1200
1270
  - **DB:** `~/.dostuff/data/sessions.db` (SQLite)
1201
1271
  - **Resume:** `dostuff resume` (latest in the current dir), `dostuff resume <id>` or `dostuff --session <id>`
1202
1272
  - **List:** `dostuff sessions` (current dir) / `dostuff sessions --all`
1203
- - **Memory stores:** `~/.dostuff/data/chroma/` (needs `pip install "dostuff[memory]"`; without it, saved memories are kept on disk but not used)
1273
+ - **Memory store:** `~/.dostuff/data/memory.db` (SQLite), built in; no extra needed. It needs SQLite's FTS5 (full-text search), which almost every Python's `sqlite3` includes; on one without it, memory uses the `chroma` store when the `memory` extra is installed and is off otherwise, and the TUI, `dostuff -p` and `dostuff doctor` say so
1204
1274
  - Semantic (key/value facts)
1205
1275
  - Episodic (events with summaries and timestamps)
1206
- - **Saved when:** the agent decides — `save_memory` stores a key/value fact (an overlapping fact is updated, not duplicated) and `save_episode` stores a decision, correction or lesson (one that rewords an episode already saved in the directory is skipped). Each save is shown in the TUI; nothing is extracted at exit. Subagents can't save memories.
1276
+ - **Backends** (`memory.backend`) — `hybrid` (the default) searches `memory.db` two ways at once: by keywords (SQLite full-text search), and, with `pip install "dostuff[memory]"`, by meaning through an embedding index in `~/.dostuff/data/memory-index/`, so a question worded differently from the memory still finds it. Without the extra it searches by keywords only. `sqlite` is keywords only; `chroma` is the embeddings-only store dostuff used before. On a retrieval benchmark (LongMemEval-S, 470 questions), hybrid put the right memory in its top 5 for 97% of questions (keywords alone 96%, embeddings alone 74%) and delivered it to the agent automatically for 85% (59% and 65%).
1277
+ - **Upgrading from the chroma store** — on the first start with `hybrid` or `sqlite`, the facts and episodes in `~/.dostuff/data/chroma/` are copied into `memory.db` once (the TUI says how many; `dostuff -p` says it on stderr); `~/.dostuff/data/chroma/` itself is left as it was, so `memory.backend: chroma` still finds them. A memory you forget afterwards is not brought back. If the extra isn't installed, nothing is copied and the TUI says how to bring them in. The embedding index then fills in the background ("Indexing N memories..."); until it has, those memories are found by keywords.
1278
+ - **Saved when:** the agent decides — `save_memory` stores a key/value fact (an overlapping fact of the same scope is updated, not duplicated) and `save_episode` stores a decision, correction or lesson (one that rewords an episode already saved in the directory is skipped; for one of the same type that is close but not a near-copy, the model is asked whether it adds anything to the saved one, and it is skipped only when the answer is clearly that it adds nothing (an unclear answer or a failed call saves it); a lesson next to the event it explains is always kept). Each save is shown in the TUI; nothing is extracted at exit. Subagents can't save memories.
1279
+ - **Fact scopes** — a fact is about you (`scope="user"`, the default: your name, editor, how you like answers) or about one project (`scope="project"`: its tooling, conventions, decisions), keyed by the directory it was saved in. The same key can be saved once per scope and project. A project fact is only shown in its own directory.
1207
1280
  - **Two step tables** — `session_steps` (full audit, shown on resume) and `working_steps` (what the model sees; compaction flags old rows instead of rewriting them). Each step is one INSERT. DBs from 0.1.6 and earlier are migrated on first open (`PRAGMA user_version`).
1208
- - **Memory recall** — episodic memories come from your past sessions in the same directory (`memory.episodic_scope: user` for all directories). The agent is told never to save facts that only appeared in tool output; only facts and episodes related to the prompt are recalled (an unrelated prompt like "hi" gets none). List them with `/memories` and `/episodes`, delete one with `/forget`.
1281
+ - **Fact delivery** — every saved fact (yours plus this project's) is listed for the agent before its first model call, in a hidden step after your prompt, and sent again only when the list changes (a save, an update, `/forget`) or a compaction drops it, so the prompt cache holds. Facts are listed newest first until they fill a budget of about 4,000 tokens (a few hundred typical facts), with project facts taking at most 60% of it; past that, up to 3 of the rest that match the prompt are added to that turn's context (a fact already added earlier in the session isn't added again until a compaction drops it, unless its value changed), and the agent can look up the others with `search_memory`. Typed subagents get the same list (see [Subagents](#subagents)). While some facts are left out, every turn's context says how many, with a reminder to search before writing code or committing.
1282
+ - **Episode recall** — episodic memories come from your past sessions in the same directory (`memory.episodic_scope: user` for all directories); only episodes related to the prompt are recalled (an unrelated prompt like "hi" gets none), up to 3 a turn, and one the session already shows isn't recalled again until a compaction drops it. The block says how many matched and (in project scope) how many the project has saved, so the agent knows when more exist. Older episodes rank lower by type: an event loses half its weight in about two weeks, a lesson in about ten, and a decision, preference or correction doesn't fade. A project keeps at most 200 episodes; past that, the lowest-ranked go after each save, never a decision. The agent is told never to save facts that only appeared in tool output. List them with `/memories` and `/episodes`, delete one with `/forget`.
1283
+ - **Episode index** — besides the episodes recalled for a prompt, the agent gets a list of the episodes saved in this project, one line each (`[DECISION 2026-10-30] Chose SQLite for the cache`), in a hidden step like the facts: decisions, preferences and corrections first, newest first, then lessons and events by how recent they are, up to about 1,500 tokens (the list says when older ones are left out). It is sent again only when an episode is saved, forgotten or pruned, so the prompt cache holds. It lets the agent see that a decision exists even when the prompt shares no words with it, and look up the detail with `search_memory`. Subagents don't get it.
1284
+ - **Searching memory** — `search_memory` lets the agent look past those limits itself: facts that aren't in its list (yours and this project's) and this project's episodes (every directory's with `episodic_scope: user`), ranked by how well they match its query alone, with no fade for age; each result shows its date and, for an episode, its type. A search returns up to 10 facts and 5 episodes (the agent can ask for up to 20 and 10), and says when more facts matched, so the agent can search again with narrower words. For a question about a kind of memory (what was decided, what you corrected, what was learned) the agent can name an episode type: every episode of that type is ranked first, even one that shares no words with the question, followed by the ordinary matches of other types, so a wrong type never hides what the search would otherwise find. When its list doesn't hold every saved fact, it is told to search before it writes code, commits, or changes the database, CI, dependencies or the build, and when an error looks familiar or you ask what was decided. It only reads, so it never asks and works in plan mode; subagents don't get it.
1285
+ - **Consolidating facts** — `/memories consolidate` (or `dostuff memory consolidate`) asks the model once to merge overlapping facts (yours and this project's, never across the two), shows what would be removed, changed and added, and writes it only when you say yes. It is never automatic; in auto mode it refuses rather than ask (on the command line, `--yes` merges without asking). The TUI suggests it at startup and in `/memories` once you have more than 30 user facts.
1286
+ - **Index repair** — on the default backend, `memory.db` is the record and both indexes are rebuilt from it: every save also queues the change for the embedding index in the same transaction, so a crash or an index error only delays it (the next save or search catches up), a search never returns a memory that `memory.db` no longer has, and the TUI indexes whatever is missing at startup. If the embedding index fails, recall carries on by keywords. `dostuff memory check` reports what is out of step and `dostuff memory repair` fixes it. On `memory.backend: chroma`, if Chroma's vector index gets out of sync with its stored rows (chroma-core/chroma#7032), recall and saving fall back to a slower scan instead of failing, and the TUI warns at startup. `dostuff memory repair` rebuilds the index; rows it can't rebuild are left out but kept in the backup, and a failed rebuild leaves the original as it was. `dostuff memory repair --reembed` also re-embeds facts saved by older versions (as `"User's <key> is <value>"`) as their value alone, after a backup; they keep working without it.
1209
1287
  - **Token persistence** — `prompt_tokens` / `completion_tokens` / `total_tokens` / `last_input_tokens` saved to DB; resume restores percent from DB meta
1210
1288
 
1211
1289
  Long-term memory survives `pip install . --upgrade` because it lives in the user's home directory, not in the package.
@@ -1314,7 +1392,7 @@ dostuff/
1314
1392
  │ ├── files/ # read, write, edit, delete, list
1315
1393
  │ ├── search/ # grep and glob (pure Python, default excludes)
1316
1394
  │ ├── mcp/ # mcp tool search, detail, and execution wrappers
1317
- │ ├── memory/ # save_memory / save_episode
1395
+ │ ├── memory/ # save_memory / save_episode / search_memory
1318
1396
  │ ├── settings.py # read_settings, edit_config, set/remove_mcp_server
1319
1397
  │ ├── web_fetch.py # read a URL as text
1320
1398
  │ ├── web_search.py # free web search (SearXNG / ddgs / DuckDuckGo)