From df7eefaf71312ea7c562ffbe26fc314de0138b36 Mon Sep 17 00:00:00 2001 From: Levi Neely Date: Wed, 12 Aug 2026 19:35:36 +0200 Subject: [PATCH] doc: rename tool-overlays to tool-definitions --- README.md | 2 +- doc/{tool-overlays.md => tool-definitions.md} | 102 +++++------------- 2 files changed, 28 insertions(+), 76 deletions(-) rename doc/{tool-overlays.md => tool-definitions.md} (69%) diff --git a/README.md b/README.md index f6bc67f..408054c 100644 --- a/README.md +++ b/README.md @@ -62,7 +62,7 @@ Everything lives under `$XDG_CONFIG_HOME/ollie/` (default: `~/.config/ollie/`) | **Parallel execution** | Non-conflicting tool calls within a turn run in parallel (scope-based conflict scheduling) | | **Agents** | Write a JSON config in `~/.config/ollie/agents/` with agent prompt in `~/.config/ollie/prompts/` | | **Tools** | Drop an executable + `.meta` in `~/.config/ollie/tools/` — load at runtime via `tool_load` | -| **Tool overlays** | Integrate external CLIs (or MCP servers via CLI bridges) with `.meta` files only — no wrapper code ([doc](doc/tool-overlays.md)) | +| **Tool definitions** | Define tools with `.meta` files only — no wrapper script needed ([doc](doc/tool-definitions.md)) | | **Domain skills** | Load markdown skill modules at runtime | ## Repository layout diff --git a/doc/tool-overlays.md b/doc/tool-definitions.md similarity index 69% rename from doc/tool-overlays.md rename to doc/tool-definitions.md index 817d283..1377470 100644 --- a/doc/tool-overlays.md +++ b/doc/tool-definitions.md @@ -1,21 +1,24 @@ -# Tool Overlays +# Tool Definitions -A tool overlay is a set of `.meta` files that expose external CLIs to ollie -without wrapper scripts. The `.meta` file declares the schema and specifies -the shell command to run — no executable needed. +A `.meta` file can define a tool without any companion executable. The `cmd` +field specifies a shell command to run — the registry executes it via shell, +passing the tool's JSON arguments on stdin. -## Resolution order +This is the same `.meta` schema used in `writing-tools.md`, but without the +sidecar executable. No script, no binary — just the definition. + +## Resolution When the registry resolves a tool, it checks: 1. `~/.config/ollie/tools/` — local script or binary -2. `.meta` `cmd` field — shell command string, executed directly +2. `.meta` `cmd` field — shell command, executed directly 3. `exec.LookPath()` — PATH lookup -If a `.meta` file has a `cmd` field, the registry executes it via shell. The -tool's JSON arguments are passed on stdin. +If a `.meta` file has a `cmd` field and no co-located executable exists, the +registry runs the command via shell. -## Meta-only tool structure +## Structure ```json { @@ -33,7 +36,8 @@ tool's JSON arguments are passed on stdin. } ``` -No script, no binary — just the `.meta` file. +The `cmd` field is the only addition to the standard `.meta` schema. All other +fields work the same as documented in `writing-tools.md`. ## Parsing arguments @@ -64,9 +68,7 @@ For subcommand-style CLIs with variable arguments: This extracts a `command` field, builds `--key=value` flags from remaining fields, and calls `my-cli --key=value ...`. -## Example: wrapping ripgrep - -Expose `rg` as a tool with curated arguments: +## Example: ripgrep ```json { @@ -87,12 +89,7 @@ Expose `rg` as a tool with curated arguments: } ``` -The model calls `rg_search(pattern="error", glob="*.log")`. The cmd pipeline -extracts fields, builds flags conditionally, and runs `rg -g "*.log" "error" "."`. - -## Example: wrapping kubectl - -Expose common kubectl operations: +## Example: kubectl ```json { @@ -111,13 +108,10 @@ Expose common kubectl operations: } ``` -Complex routing logic lives entirely in the `cmd` field. No wrapper script. +## Example: MCP bridge -## Example: wrapping an MCP server - -MCP servers expose tools over JSON-RPC. CLI bridges like `mcp-client-cli` or -`npx @anthropic/mcp-client` let you call them from the command line. Wrap the -bridge in a `.meta`: +MCP servers expose tools over JSON-RPC. CLI bridges like `mcp-client-cli` let +you call them from the command line: ```json { @@ -136,63 +130,21 @@ bridge in a `.meta`: } ``` -The `cmd` extracts the tool name, passes remaining args as JSON to the MCP -bridge. No MCP protocol implementation needed — the bridge handles it. +This works for any MCP server with a CLI bridge. See `doc/resources/no-mcp.md` +for why ollie uses this pattern instead of implementing MCP natively. -This pattern works for any MCP server with a CLI bridge: filesystem, database, -Slack, linear, etc. +## Installation -## Overlay structure - -An overlay is a directory (usually a git repo) with `.meta` files, agent -configs, and prompts: +Copy the `.meta` file to `~/.config/ollie/tools/`. The tool is live immediately +— no restart needed. +```sh +cp my_tool.meta ~/.config/ollie/tools/ ``` -my-overlay/ -├── tools/ -│ ├── tool_a.meta -│ └── tool_b.meta -├── agents/ -│ └── my-agent.json -├── prompts/ -│ └── agent-my-agent.md -└── justfile -``` - -The justfile installs to `~/.config/ollie/`: - -```just -home := env_var('HOME') -cfg := home / ".config/ollie" - -default: install - -install: tools agents prompts - -tools: - install -m644 tools/tool_a.meta {{cfg}}/tools/tool_a.meta - install -m644 tools/tool_b.meta {{cfg}}/tools/tool_b.meta - -agents: - mkdir -p {{cfg}}/agents - install -m644 agents/my-agent.json {{cfg}}/agents/my-agent.json - -prompts: - mkdir -p {{cfg}}/prompts - install -m644 prompts/agent-my-agent.md {{cfg}}/prompts/agent-my-agent.md - -uninstall: - rm -f {{cfg}}/tools/tool_a.meta {{cfg}}/tools/tool_b.meta - rm -f {{cfg}}/agents/my-agent.json - rm -f {{cfg}}/prompts/agent-my-agent.md -``` - -Run `just install`. Tools are live immediately — no restart needed. ## Notes - `additionalProperties: true` allows pass-through arguments the schema doesn't enumerate. - Prefix tool names to avoid collisions (`acme_deploy`, not `deploy`). - Test cmd pipelines: `echo '{"pattern":"TODO"}' | bash -c 'YOUR_CMD'` -- Agent configs can auto-load overlay tools via `autoLoad`. -- Overlays compose: multiple overlays install to the same tools directory. +- Agent configs can auto-load tools via `autoLoad`.