@@ -1,6 +1,6 @@
---
name: invoking-subagents
-description: Invokes ad-hoc subagents to read through lots of data and extract relevant information. Use only on explicit user request for exploring other repositories, reading series of git logs, looking at large diffs, and anything else that might produce copious amounts of text.
+description: Spawns subagents with configurable tool access that return just the answers without flooding your context. Use for summarizing extensive git history, comparing across multiple repositories in parallel, or processing large diffs/logs.
compatibility: Requires `synu` shell plugin and `claude` CLI tool
license: AGPL-3.0-or-later
metadata:
@@ -9,12 +9,14 @@ metadata:
Invoke with `synu claude --flags -p 'prompt'`.
-Use a precise and thorough prompt. Aggressively restrict which tools it can interact with; if it doesn't need Edit, don't give it Edit. If it needs to read files, Glob, Grep, and Read are probably sufficient. Task can be helpful. Notebook, Slash, Write, Web, Edit, etc. should almost never be necessary. Execute them in the background. You make invoke multiple when appropriate and in parallel if helpful. Once they're running, you may either stop and wait for me to tell you they're finished or continue with other work.
+**Important:** Subagents are scoped to their cwd, just like you. To work in another repository, `cd` there first.
-A more thorough example using the fish plugin from another shell:
+Use a precise and thorough prompt. Aggressively restrict which tools it can interact with; if it doesn't need Edit, don't give it Edit. If it needs to read files, Glob, Grep, and Read are probably sufficient. Task can be helpful. Notebook, Slash, Write, Web, Edit, etc. should almost never be necessary. Execute them in the background. You may invoke multiple when appropriate and in parallel if helpful. Once they're running, you may either stop and wait for me to tell you they're finished or continue with other work.
-```
-fish -c "synu claude --disallowed-tools 'Bash(*) Explore Edit Read WebFetch WebSearch Glob Grep NotebookEdit NotebookRead SlashCommand Write' --allowed-tools 'Bash(git log:*) Bash(git show:*)' -p 'Using only `git log` and `git show`, summarise the major user-facing changes in HASH..HASH. Do not provide code snippets or technical details. Consider user-facing changes, like being able to set a port-out PIN or adding a new button or changing font sizes.'"
+Example exploring git history in another repo:
+
+```bash
+cd /path/to/other/repo && fish -c "synu claude --disallowed-tools 'Bash(*) Explore Edit Read WebFetch WebSearch Glob Grep NotebookEdit NotebookRead SlashCommand Write' --allowed-tools 'Bash(git log:*) Bash(git show:*)' -p 'Using only git log and git show, summarise the major user-facing changes in HASH..HASH. Do not provide code snippets or technical details. Consider user-facing changes, like being able to set a port-out PIN or adding a new button or changing font sizes.'"
```
Refer to [installing-synu.md](references/installing-synu.md) if it's unavailable.