Tools

All 10 tools available in bashkit, with descriptions and usage examples.

Bash

Execute shell commands with configurable timeouts. Returns stdout, stderr, and exit code.

// Tool input schema
{
  command: string,       // The command to execute
  description: string,   // What this command does
  timeout: number | null // Timeout in ms (default: 120000)
}

// Example output
{
  stdout: "Hello, world!\n",
  stderr: "",
  exit_code: 0
}

Configure blocked commands and timeouts:

const { tools } = await createAgentTools(sandbox, {
  tools: {
    Bash: {
      timeout: 10000,
      blockedCommands: ['rm -rf', 'dd if=', 'curl'],
    },
  },
});

Read

Read file contents or list directory entries. Supports line offset and limit for large files.

// Tool input schema
{
  file_path: string,    // Absolute path to read
  offset: number | null, // Start line (1-based)
  limit: number | null   // Max lines to return
}

// File output
{
  content: "line 1\nline 2\n...",
  line_count: 42
}

// Directory output (when path is a directory)
{
  entries: ["src/", "package.json", "README.md"],
  entry_count: 3
}

Write

Create or overwrite files. Creates parent directories automatically.

// Tool input schema
{
  file_path: string,  // Absolute path to write
  content: string     // Full file content
}

// Output
{
  path: "/path/to/file.ts",
  bytes_written: 1234
}

Edit

Replace specific strings in existing files. Supports single or multi-occurrence replacement.

// Tool input schema
{
  file_path: string,        // Absolute path to edit
  old_string: string,       // String to find
  new_string: string,       // Replacement string
  replace_all: boolean | null // Replace all occurrences (default: false)
}

// Output
{
  path: "/path/to/file.ts",
  replacements: 1
}

Glob

Find files by glob pattern. Uses fast pattern matching that works with any codebase size.

// Tool input schema
{
  pattern: string,    // Glob pattern (e.g. "**/*.ts")
  path: string | null // Base directory (default: working dir)
}

// Output
{
  files: [
    "src/index.ts",
    "src/tools/bash.ts",
    "src/tools/read.ts"
  ],
  count: 3
}

Grep

Search file contents with regex. Uses ripgrep under the hood for fast results. Returns matching lines with surrounding context.

// Tool input schema
{
  pattern: string,     // Regex pattern to search
  path: string | null, // Directory to search in
  include: string | null // File pattern filter (e.g. "*.ts")
}

// Output
{
  matches: [
    {
      file: "src/tools/bash.ts",
      line: 42,
      content: "  const timeout = config?.timeout ?? 120000;",
      context_before: ["  // Default timeout"],
      context_after: ["  const maxOutput = config?.maxOutput ?? 30000;"]
    }
  ],
  count: 1
}

WebSearch

Search the web with optional domain filtering. Requires the parallel-web package and a Parallel API key.

// Tool input schema
{
  query: string,           // Search query
  domains: string[] | null // Limit to specific domains
}

// Output
{
  results: [
    {
      title: "Vercel AI SDK Documentation",
      url: "https://sdk.vercel.ai/docs",
      snippet: "The Vercel AI SDK is a TypeScript toolkit..."
    }
  ]
}

Enabled by passing webSearch config:

const { tools } = await createAgentTools(sandbox, {
  webSearch: { apiKey: process.env.PARALLEL_API_KEY },
});

WebFetch

Fetch and extract content from URLs. Returns cleaned text content from web pages.

// Tool input schema
{
  url: string,           // URL to fetch
  format: string | null  // "text" | "markdown" | "html"
}

// Output
{
  content: "Page content extracted as clean text...",
  title: "Page Title",
  url: "https://example.com/page"
}

Task

Spawn sub-agents for complex, multi-step work. Each sub-agent gets its own tool set and conversation context. When budget tracking is enabled, costs are shared across parent and child agents.

// Tool input schema
{
  description: string,  // Short task description
  prompt: string        // Detailed instructions for the sub-agent
}

// The sub-agent runs autonomously and returns its result
// Budget tracking auto-wires into sub-agents when configured

TodoWrite

Manage structured task lists. Useful for agents that need to track multi-step workflows.

// Tool input schema
{
  todos: [
    {
      id: string,
      content: string,
      status: "pending" | "in_progress" | "done",
      priority: "high" | "medium" | "low"
    }
  ]
}

// Output
{
  todos: [...], // Updated todo list
  count: 5
}