Custom Tools

Beyond the built-in tools, you can give the agent your own developer-defined script tools. A custom tool is described by a small TOML manifest. Once stella finds it, the tool appears alongside the built-ins, and the agent can call it like any other tool.

Where manifests live

Drop a <name>.toml manifest file into one of these directories:

• Workspace — .stella/tools/ (checked in with the project, shared with your team).
• User global — ~/.stella/tools/ (personal, available across all your workspaces).

If the same tool name is defined in both places, the workspace manifest wins. This lets a project override a personal default while keeping your other global tools available everywhere else.

A third source is read after both: tools/*.toml inside an installed plugin. Plugin manifests are scanned last. If either of your own directories already defines a name, that definition wins, and the plugin's copy is dropped with a diagnostic naming both files. This means installing a plugin can never silently redirect a tool you already call. A plugin's tool also gets ${plugin_dir} filled in wherever its package directory belongs, in every command element and every [env] value. That placeholder is not expanded in your own manifests, since no plugin package is in scope there.

Run stella tools at any time to see which custom tools were found, alongside the built-ins.

export STELLA_TRUST_PROJECT=1

Manifest shape

A manifest declares the tool's name, description, the command to run, and an input_schema:

name = "wordcount"
description = "Count the words in a file and print the total."

# The command Stella runs when the agent calls this tool. It is an argv array,
# spawned directly with no shell; command[0] resolves against the workspace root.
command = ["scripts/wordcount.sh"]

# Optional. Default 30000 (30 seconds), hard-capped at 600000 (10 minutes) —
# a manifest asking for more is clamped. Past the timeout, the script's whole
# process group is killed and the tool returns a named error.
timeout_ms = 60000

# Optional extra environment variables for the child process, applied on top
# of the inherited environment.
[env]
WORDCOUNT_LOCALE = "en_US"

# Tool inputs are a JSON Schema, written as TOML under [input_schema].
[input_schema]
type = "object"
required = ["path"]

[input_schema.properties.path]
type = "string"
description = "Path to the file whose words should be counted."

Fields

Script input

When the agent calls a custom tool, stella spawns command directly from the argv array. It never goes through a shell, so there's no injection surface in the tool's input. The working directory is set to the workspace root. The model's input JSON reaches your script two ways, so a simple script needs no JSON parser at all:

1. The whole input object is written to the script's stdin as one JSON document, then stdin is closed. Your script sees EOF.
2. Each top-level scalar property (string, number, bool) is exported as STELLA_INPUT_<UPPER_SNAKE_KEY>. path becomes STELLA_INPUT_PATH, and dry_run becomes STELLA_INPUT_DRY_RUN. Nested objects and arrays only arrive on stdin.

The manifest's [env] table is applied on top of the inherited environment, before the STELLA_INPUT_* exports. Input keys come from the model, but they're namespaced under STELLA_INPUT_, so they can never overwrite PATH or your [env] values.

A script that reads both channels:

#!/usr/bin/env bash
set -euo pipefail

# Scalar inputs arrive as environment variables…
path="$STELLA_INPUT_PATH"

# …and the full input object arrives as one JSON document on stdin —
# read it (e.g. with jq) when you need nested objects or arrays.
input="$(cat)"    # {"path": "src/lib.rs"}

wc -w < "$path"

Exit 0 and the captured stdout becomes the tool's result. A non-zero exit returns an error carrying the exit code and the last part of stderr. Both streams are trimmed from the middle if they get too long.

Validating manifests

Before a run, check every manifest with the strict pre-flight validator:

stella tools --validate            # scans .stella/tools/ and ~/.stella/tools/
stella tools --validate ./mytools  # or an explicit directory

stella is lenient at discovery time. A broken manifest just becomes a diagnostic, and the session keeps running. So this validator is your chance to catch problems before a run has already spent your budget. It parses each <name>.toml file and sorts problems into severities:

It exits non-zero if any manifest has errors, which is handy in CI.

How custom tools appear

Once stella finds a manifest, it registers the tool into the session, and it shows up next to the built-ins, including in the output of stella tools. The agent can then call it as part of its normal step loop. Like every other tool, a custom tool follows the per-tool permission model, and its calls can be gated or blocked with a PreToolUse hook.