bash-tool

bash-tool is designed to provide sandboxed execution environments for AI agents.

Core Concepts:

• Sandboxing: By default, it uses just-bash (a simulated environment). For full VM capabilities (supporting Node.js, Python, etc.), you must provide a @vercel/sandbox instance.
• Pre-population: Files provided in the files option are written to the sandbox before the tools are returned to the agent.
• Contextual Awareness: The bash tool's description automatically includes the current working directory and a list of available files so the LLM has context.
• Working Directory: The default working directory is /workspace. All files are written relative to the destination path.
• Lifecycle: The sandbox lifecycle is managed externally; there is no stop() method on the tools themselves.

You can initialize a bash tool with a set of files and pass it to an AI SDK ToolLoopAgent. This allows the agent to execute commands, read, and write files within the provided sandbox environment.

Note: If you are using AI SDK 6, import stepCountIs instead of isStepCount for the stopWhen option.

import { createBashTool } from "bash-tool";
import { isStepCount, ToolLoopAgent } from "ai";

const { tools } = await createBashTool({
  files: {
    "src/index.ts": "export const hello = 'world';",
    "package.json": '{"name": "my-project"}',
  },
});

const agent = new ToolLoopAgent({
  model: yourModel,
  tools,
  // Or use just the bash tool as tools: {bash: tools.bash}
  stopWhen: isStepCount(20),
});

const result = await agent.generate({
  prompt: "Analyze the project and create a summary report",
});

If a skill only requires providing knowledge, style guides, or process documentation to the AI without executing code, you can use createSkillTool standalone. This is useful for providing domain knowledge, formatting rules, or best practices.

For these skills, the SKILL.md file should contain only the YAML frontmatter and Markdown instructions, with no accompanying .sh files.

import { experimental_createSkillTool as createSkillTool } from "bash-tool";

// Discover instruction-only skills
const { skill, skills } = await createSkillTool({
  skillsDirectory: "./knowledge",
});

// Use just the skill tool - no bash needed
const agent = new ToolLoopAgent({
  model: "anthropic/claude-haiku-4.5",
  tools: { skill },
});

Since the default just-bash is a simulation that cannot run binaries like Python or Node.js, use @vercel/sandbox to provide a full virtual machine environment.

import { Sandbox } from "@vercel/sandbox";
const vm = await Sandbox.create();
const { tools } = await createBashTool({ sandbox: vm });
// Call vm.stop() when done

To run the provided skills-tool demonstration from the repository root, use npx tsx to execute the index file:

npx tsx examples/skills-tool/index.ts

To use the basic bash tool functionality, install bash-tool and just-bash via npm:

npm install bash-tool just-bash

For full VM support, install @vercel/sandbox or another sandbox product instead of just-bash.

A skill is represented as a directory within your designated skills/ folder. To create a new skill, follow this structure:

1. Create a new directory (e.g., skills/my-new-skill/).
2. Add a SKILL.md file containing YAML frontmatter for metadata and Markdown for instructions.
3. Add one or more bash scripts that the AI can execute to perform the skill's tasks.

Example Directory Structure:

skills/
├── my-skill/
│   ├── SKILL.md      # Instructions (YAML frontmatter + markdown)
│   ├── task1.sh      # Bash script
│   └── task2.sh      # Bash script

To provide an AI agent with filesystem and shell capabilities, use createBashTool. This function returns a tools object containing bash, readFile, and writeFile tools. You can pre-populate the sandbox with files using the files option.

Note: If you are using AI SDK 6, use stepCountIs instead of isStepCount for the stopWhen option in ToolLoopAgent.

import { createBashTool } from "bash-tool";
import { isStepCount, ToolLoopAgent } from "ai";

const { tools } = await createBashTool({
  files: {
    "src/index.ts": "export const x = 1;",
    "package.json": '{"name": "test"}',
  },
});

const agent = new ToolLoopAgent({
  model,
  tools,
  stopWhen: isStepCount(20),
});

const result = await agent.generate({
  prompt: "List files in src/",
});