Optional shell-tool scripts that wrap companion CLIs from the
nlink-jp org. None are embedded in the production binary or
auto-installed — copy the ones you want into your
<dataDir>/tools/ directory (typically
~/Library/Application Support/shell-agent-v2/tools/).
| Script | Wraps | Requires | Default MITL |
|---|---|---|---|
web-search.sh |
gem-search | gem-search binary on $PATH |
off (@category: read) |
generate-image.sh |
gem-image | gem-image binary on $PATH |
on (@category: write) |
search-kb-gem.sh |
gem-rag (Vertex AI Gemini RAG) | gem-rag binary + pre-indexed corpus |
off |
search-kb-lite.sh |
lite-rag (local LLM RAG) | lite-rag binary + pre-indexed corpus |
off |
summary.sh |
gem-summary (Vertex AI Gemini single-call text summariser) | gem-summary binary on $PATH |
off |
All five scripts declare @timeout: 120 because the underlying
Gemini round-trips routinely exceed the 30-second default
(gem-summary's chunked path in particular can fan out 5-10
parallel calls and a merge call). See
docs/en/history/tool-execution-timeout.md
for the rationale.
summary.sh is the recommended path for ordinary summary
requests — "summarise this document", "give me a TL;DR",
"what does this report say". One LLM call (or one merge call
plus parallel chunk calls for over-context-window inputs).
The built-in analyze-text tool, by contrast, uses a
sliding-window summariser that issues 3-5 LLM calls and
maintains a running summary across windows. That overhead pays
off for log audits / anomaly detection across long
documents where the running-summary context bridge between
windows is load-bearing. For plain summarisation it's overkill.
The @description: field in summary.sh calls out this
contrast explicitly so the LLM can pick correctly from the
tool list — no need to seed System Rules or modify
shell-agent-v2's built-in prompts. If you observe drift in
practice, add a System Rules entry that pins the preference
(examples/system_rules/ is the natural home).
cp examples/shell_tools/web-search.sh \
~/Library/Application\ Support/shell-agent-v2/tools/shell-agent-v2 picks up new scripts on the next agent turn — no
restart needed. If the tool doesn't appear, check
Settings → Tools for parse errors (typically a missing
@tool: header).
These four scripts are reference implementations, not
contracts — feel free to fork the file, edit the command,
adjust the timeout, or change the MITL category. shell-agent-v2
treats anything under <dataDir>/tools/*.sh with a valid
@tool: header as a tool.
The header format and supported metadata (@tool:,
@description:, @category:, @timeout:, @mitl:) live in
docs/en/reference/architecture.md
under §5 Tool system. The structural test
internal/bundled.TestRepoRootExamples_HaveToolHeader keeps
every example here syntactically valid.
Each script needs an external CLI on $PATH (gem-search,
gem-image, gem-rag, lite-rag). Auto-installing them would
surface broken tools to users who haven't installed the
corresponding companion, polluting the Settings → Tools list
with permanent errors. Opt-in install via copy is the cleaner
choice.
Sibling library: ../system_rules/ — same
pattern, but for <dataDir>/system_rules.md standing
instructions instead of shell tools.