Introducing bash-tool for filesystem-based context retrieval

We open-sourced bash-tool, the Bash execution engine used by our text-to-SQL agent that we recently re-architected to reduce our token usage, improve the accuracy of the agent's responses, and improve the agent's overall performance.

bash-tool gives your agent a way to find the right context by running bash-like commands over files, then returning only the results of those tool calls to the model.

Context windows can fill up quickly if you include large amounts of text into a prompt. As agents tend to do well with Unix-style workflows like find, grep, jq, and pipes, with bash-tool you can now keep large context local, in a filesystem, and let the agent use those commands to retrieve smaller slices of context on demand.

bash-tool provides bash, readFile, and writeFile tools for AI SDK agents, working with both in-memory and sandboxed environments, and:

• runs on top of just-bash, which interprets bash scripts directly in TypeScript without a shell process or arbitrary binary execution

• you can preload that filesystem with your files at startup, so your agent can search them when needed without pasting everything into the prompt

• it supports running in-memory or in a custom isolated VM

1
import { createBashTool } from "bash-tool";
2

3
const { tools } = await createBashTool({
4
  files: { "src/index.ts": "export const hello = 'world';" },
5
});
6

7
const agent = new ToolLoopAgent({ model, tools });

If you need a real shell, a real filesystem, or custom binaries, you can run the same tool against a Sandbox-compatible API for full VM isolation.

1
import { createBashTool } from "bash-tool";
2
import { Sandbox } from "@vercel/sandbox";
3
const sandbox = await Sandbox.create();
4

5
const { tools } = await createBashTool({ sandbox });
6

7
const agent = new ToolLoopAgent({ model, tools });