Tools

Tools

Tools are Ollama function-calling definitions executed locally in the Electron main process. They are attached to a chat turn when Tools are enabled.

Mental model

Kind	Persistence	Implementation
Builtin	Code	tools/registry.ts BUILTINS + tools/exec.ts
Custom shell/HTTP	userData/anylm-tools.json	Templates with {param}; no app rebuild

Default: builtins are enabled unless listed in the disabled set. Custom tools default to whatever enabled you set on save.

Key files

File	Role
app/src/main/tools/registry.ts	Builtin catalog, save/toggle, ollamaTools()
app/src/main/tools/exec.ts	Dispatch + confirm + shell/HTTP/custom
app/src/main/tools/fs-tools.ts	Workspace-relative FS operations
app/src/main/tools/web-search.ts	Search backend for web_search
app/src/renderer/js/tools-view.ts	Tools UI
app/src/types/domain.d.ts	ToolDefinition, ToolParam, OllamaToolDef

Builtin catalog (current)

Name	Risky	Notes
get_time	no	Local clock
read_file	no	Relative to workspace or absolute
list_directory	no
write_file	yes	Workspace-relative
create_directory	yes
move_path / copy_path / delete_path	yes
find_files	no	Name substring / glob
web_search	no	Used by Web research skill
open_app_or_url	yes
run_shell	yes	15s timeout; prefer narrower tools
http_fetch	GET no / other yes	Body for POST/PUT
ask_user	no	Structured question → renderer
generate_document	yes	pdf/docx/pptx/md — always confirms

Shell timeout constant: SHELL_TIMEOUT = 15_000 in exec.ts.

How to create a custom tool (no code)

1. Tools → New tool.
2. Name: snake_case (becomes the Ollama function name).
3. Description: one clear sentence for the model about when to call it.
4. Kind:
   • Shell — command template with {param} placeholders (always risky).
   • HTTP — URL template + method; non-GET is risky.
5. Params: name | description | required.
6. Enable the tool; in chat turn Tools on; ask something concrete.

Recipes

• Prefer one focused tool over exposing raw run_shell.
• Escape assumptions: shell values are escaped; URL params are encoded.
• Keep output small; large stdout is truncated for the model.
• Write descriptions that include trigger phrases (“when the user asks to …”).

How to add a builtin tool (code)

1. Append to BUILTINS in registry.ts:

{
  id: "my_tool",
  name: "my_tool",
  description: "Use when …",
  params: [{ name: "x", description: "…", required: true }],
  enabled: true,
  builtin: true,
  risky: false,
},

2. Implement a case "my_tool": in execBuiltin inside exec.ts. Always return a string.
3. If mutating / network / process: set risky: true so the confirm gate runs.
4. Optional: document on the marketing catalog (web/) if user-facing.

Execution context

tools/exec.execute(name, args, confirm, allow?, context?):

• allow — optional Set of tool names permitted even if globally disabled (skills use this).
• context — chat/project/workspace hints for FS and documents.
• Confirm callback bridges to renderer onToolConfirm / replyToolConfirm.

Interaction with skills

Skills may either:

• Reference registry tools by toolNames, or
• Define connector-native tools with their own run(args, bearer).

Chat merges schemas from both registries. Routing: connector-owned names → skills/exec; everything else → tools/exec.

Limits & model requirements

• Single-agent tool loop: up to 15 rounds (ipc.ts).
• Multi-agent workers: 3 rounds (agents/workers.ts).
• Needs a tool-capable Ollama model. Small models may emit text JSON; recovery logic tries to parse those into tool calls.

Proxy caveat

The local OpenAI-compatible proxy does not run AnyLM tools. External clients get governed chat completions only.

IPC surface

Method	Purpose
toolsList	Builtin + custom
toolsSave	Create/update custom (kind, command/url, method, params)
toolsDelete / toolsToggle	Manage custom / enabled state
workspaceGet / Pick / Clear	FS sandbox root for file tools
onToolConfirm / replyToolConfirm	Risky approval

Testing

• bun test covers exec helpers, FS tools, web research recovery, etc.
• Manual: toggle off/on, confirm deny path, workspace-relative paths, shell timeout.