Custom Tools
Custom tools are functions you create that the LLM can call during conversations. They work alongside alphabase’s built-in tools like read, write, and bash.
Treat every custom tool as executable code with the permissions of its runtime context. Review project and global tool files before loading them, validate all arguments, keep access narrow, and do not put credentials in tool source or descriptions. A tool definition is not a security sandbox.
The examples use the @alphabase/plugin workspace helper. Resolve that package
from a compatible distribution supplied
by your deployment; the repository does not guarantee a public npm package.
Creating a tool
Tools are defined as TypeScript or JavaScript files. However, the tool definition can invoke scripts written in any language — TypeScript or JavaScript is only used for the tool definition itself.
Location
They can be defined:
- Locally by placing them in the
.alphabase/tools/directory of your project. - Or globally, by placing them in
~/.config/alphabase/tools/.
Structure
The easiest way to create tools is using the tool() helper which provides type-safety and validation.
import { tool } from "@alphabase/plugin"
export default tool({ description: "Query the project database", args: { query: tool.schema.string().describe("SQL query to execute"), }, async execute(args) { // Your database logic here return `Executed query: ${args.query}` },})The filename becomes the tool name. The above creates a database tool.
Multiple tools per file
You can also export multiple tools from a single file. Each export becomes a separate tool with the name <filename>_<exportname>:
import { tool } from "@alphabase/plugin"
export const add = tool({ description: "Add two numbers", args: { a: tool.schema.number().describe("First number"), b: tool.schema.number().describe("Second number"), }, async execute(args) { return args.a + args.b },})
export const multiply = tool({ description: "Multiply two numbers", args: { a: tool.schema.number().describe("First number"), b: tool.schema.number().describe("Second number"), }, async execute(args) { return args.a * args.b },})This creates two tools: math_add and math_multiply.
Arguments
You can use tool.schema, which is just Zod, to define argument types.
args: { query: tool.schema.string().describe("SQL query to execute")}You can also import Zod directly and return a plain object:
import { z } from "zod"
export default { description: "Tool description", args: { param: z.string().describe("Parameter description"), }, async execute(args, context) { // Tool implementation return "result" },}Context
Tools receive context about the current session:
import { tool } from "@alphabase/plugin"
export default tool({ description: "Get project information", args: {}, async execute(args, context) { // Access context information const { agent, sessionID, messageID, directory, worktree } = context return `Agent: ${agent}, Session: ${sessionID}, Message: ${messageID}, Directory: ${directory}, Worktree: ${worktree}` },})Use context.directory for the session working directory.
Use context.worktree for the git worktree root.
Examples
Write a tool in Python
You can write your tools in any language you want. Here’s an example that adds two numbers using Python.
First, create the tool as a Python script:
import sys
a = int(sys.argv[1])b = int(sys.argv[2])print(a + b)Then create the tool definition that invokes it:
import { tool } from "@alphabase/plugin"import path from "path"
export default tool({ description: "Add two numbers using Python", args: { a: tool.schema.number().describe("First number"), b: tool.schema.number().describe("Second number"), }, async execute(args, context) { const script = path.join(context.worktree, ".alphabase/tools/add.py") const result = await Bun.$`python3 ${script} ${args.a} ${args.b}`.text() return result.trim() },})Here we are using the Bun.$ utility to run the Python script.