# bash-tool

> A generic bash tool for AI agents, compatible with the AI SDK, that runs commands in a just-bash or Vercel Sandbox environment.

bash-tool is an open-source TypeScript package from Vercel Labs that gives AI agents a bash tool, a file-reading tool and a file-writing tool. It is compatible with the AI SDK and runs commands against the just-bash virtual environment by default, or against a full VM sandbox.

## What It Is

bash-tool exposes three tools to an agent: `bash` (runs a command and returns stdout, stderr and exit code), `readFile` and `writeFile` (which creates parent directories as needed). A developer calls `createBashTool` with initial files or a local directory to upload, then passes the resulting tools to an AI SDK agent such as `ToolLoopAgent`. For analysis agents, the bash tool alone may be enough.

## Sandbox Options

By default it pairs with just-bash, a TypeScript bash interpreter with an in-memory filesystem built for AI agents. The just-bash project describes itself as beta software. For full VM support, bash-tool can use `@vercel/sandbox` or another sandbox product, including reconnecting to an existing sandbox by ID across serverless invocations. Developers can also supply a custom just-bash instance or implement their own sandbox with `executeCommand`, `readFile` and `writeFiles`.

## Control and Extensibility

`onBeforeBashCall` and `onAfterBashCall` hooks let developers log, rewrite or block commands and modify results. An experimental skills feature discovers directories containing a `SKILL.md` file, with optional scripts, and exposes them through a skill tool alongside the bash tool.

## Features
- bash, readFile and writeFile tools for AI agents
- Upload local directories with glob filters
- Pre- and post-command interception hooks
- Custom sandbox implementation interface
- Persistent sandbox reconnection via Sandbox.get
- Experimental skill tool using SKILL.md directories
- Works with just-bash in-memory virtual filesystem

## Integrations
AI SDK, just-bash, @vercel/sandbox

## Platforms
WINDOWS, WEB, API, DEVELOPER_SDK, CLI

## Pricing
Open Source

## Links
- Website: https://justbash.dev/
- Documentation: https://github.com/vercel-labs/bash-tool#readme
- Repository: https://github.com/vercel-labs/bash-tool
- EveryDev.ai: https://www.everydev.ai/tools/bash-tool