{ "@context": "https://schema.org", "@id": "https://aggr.aymericbeaumet.com/items/ampcode-com/2025-08-29-bring-your-own-tools/#webpage", "@type": [ "WebPage", "ArchiveComponent" ], "articleBody": "You can now provide tools to Amp in the form of executable files.\n\nIf the environment variable `AMP_TOOLBOX` is set and contains the path to a directory, Amp will look in that directory for executables to be used as tools.\n\nOn start, Amp will invoke each executable it found, with the environment variable `TOOLBOX_ACTION` set to `describe`. The tool is then expected to write its description (which is what will end up in the system prompt that's sent to the agent) to `stdout`.\n\nHere is an example:\n\n```javascript\n#!/usr/bin/env bun\nimport fs from 'node:fs'\nconst action = process.env.TOOLBOX_ACTION\n\nif (action === 'describe') showDescription()\nelse if (action === 'execute') runTests()\n\nfunction showDescription() {\n\tprocess.stdout.write(\n\t\tJSON.stringify({\n\t\t\tname: 'run-tests',\n\t\t\tdescription: 'use this tool instead of Bash to run tests in a workspace',\n\t\t\targs: { dir: ['string', 'the workspace directory'] },\n\t\t}),\n\t)\n}\n```\n\nWhen the agent then decides to invoke your tool, Amp runs the executable again, this time setting `TOOLBOX_ACTION` to `execute`. Amp passes the tool call arguments on `stdin` and the executable can then execute the tool call:\n\n```javascript\nfunction runTests() {\n\tlet dir = JSON.parse(fs.readFileSync(0, 'utf-8'))['dir']\n\tdir = dir && dir.length > 0 ? dir : '.'\n\tBun.spawn(['pnpm', '-C', dir, 'run', 'test', '--no-color', '--run'], {\n\t\tstdio: ['inherit', 'inherit', 'inherit'],\n\t})\n}\n```\n\nYou can read more about toolboxes and possible input and output formats [in the manual](https://ampcode.com/manual#toolboxes).\n", "authors": [], "captured_at": "2026-10-04T12:50:30.804479567+00:00", "category": "programming", "content_html": "

You can now provide tools to Amp in the form of executable files.

\n

If the environment variable AMP_TOOLBOX is set and contains the path to a directory, Amp will look in that directory for executables to be used as tools.

\n

On start, Amp will invoke each executable it found, with the environment variable TOOLBOX_ACTION set to describe. The tool is then expected to write its description (which is what will end up in the system prompt that's sent to the agent) to stdout.

\n

Here is an example:

\n
#!/usr/bin/env bun\nimport fs from 'node:fs'\nconst action = process.env.TOOLBOX_ACTION\n\nif (action === 'describe') showDescription()\nelse if (action === 'execute') runTests()\n\nfunction showDescription() {\n\tprocess.stdout.write(\n\t\tJSON.stringify({\n\t\t\tname: 'run-tests',\n\t\t\tdescription: 'use this tool instead of Bash to run tests in a workspace',\n\t\t\targs: { dir: ['string', 'the workspace directory'] },\n\t\t}),\n\t)\n}\n
\n

When the agent then decides to invoke your tool, Amp runs the executable again, this time setting TOOLBOX_ACTION to execute. Amp passes the tool call arguments on stdin and the executable can then execute the tool call:

\n
function runTests() {\n\tlet dir = JSON.parse(fs.readFileSync(0, 'utf-8'))['dir']\n\tdir = dir && dir.length > 0 ? dir : '.'\n\tBun.spawn(['pnpm', '-C', dir, 'run', 'test', '--no-color', '--run'], {\n\t\tstdio: ['inherit', 'inherit', 'inherit'],\n\t})\n}\n
\n

You can read more about toolboxes and possible input and output formats in the manual.

\n", "content_markdown": "You can now provide tools to Amp in the form of executable files.\n\nIf the environment variable `AMP_TOOLBOX` is set and contains the path to a directory, Amp will look in that directory for executables to be used as tools.\n\nOn start, Amp will invoke each executable it found, with the environment variable `TOOLBOX_ACTION` set to `describe`. The tool is then expected to write its description (which is what will end up in the system prompt that's sent to the agent) to `stdout`.\n\nHere is an example:\n\n```javascript\n#!/usr/bin/env bun\nimport fs from 'node:fs'\nconst action = process.env.TOOLBOX_ACTION\n\nif (action === 'describe') showDescription()\nelse if (action === 'execute') runTests()\n\nfunction showDescription() {\n\tprocess.stdout.write(\n\t\tJSON.stringify({\n\t\t\tname: 'run-tests',\n\t\t\tdescription: 'use this tool instead of Bash to run tests in a workspace',\n\t\t\targs: { dir: ['string', 'the workspace directory'] },\n\t\t}),\n\t)\n}\n```\n\nWhen the agent then decides to invoke your tool, Amp runs the executable again, this time setting `TOOLBOX_ACTION` to `execute`. Amp passes the tool call arguments on `stdin` and the executable can then execute the tool call:\n\n```javascript\nfunction runTests() {\n\tlet dir = JSON.parse(fs.readFileSync(0, 'utf-8'))['dir']\n\tdir = dir && dir.length > 0 ? dir : '.'\n\tBun.spawn(['pnpm', '-C', dir, 'run', 'test', '--no-color', '--run'], {\n\t\tstdio: ['inherit', 'inherit', 'inherit'],\n\t})\n}\n```\n\nYou can read more about toolboxes and possible input and output formats [in the manual](https://ampcode.com/manual#toolboxes).\n", "dateCreated": "2026-10-04T12:50:30.804479567+00:00", "date_created": "2025-08-29T00:00:00+00:00", "date_modified": "2025-08-29T00:00:00+00:00", "date_published": "2025-08-29T00:00:00+00:00", "description": "You can now provide tools to Amp in the form of executable files. If the environment variable AMP_TOOLBOX is set and contains the path to a directory, Amp will look in that directory for executables to be used as tools. On start, Amp will…", "external_url": "https://ampcode.com/news/toolboxes", "git": { "commit": "ebb0941c5c06a2ab2377342d607535262a3e969e", "path": "items/ampcode-com/2025/08/2025-08-29-bring-your-own-tools.md", "permalink": "https://github.com/aymericbeaumet/aggr-instance/blob/ebb0941c5c06a2ab2377342d607535262a3e969e/items/ampcode-com/2025/08/2025-08-29-bring-your-own-tools.md" }, "id": "urn:aggr:item:352787a09d7ed4209b02c32868c73ddc9f825dce", "isBasedOn": { "@id": "https://ampcode.com/news/toolboxes" }, "mainEntity": { "@id": "https://ampcode.com/news/toolboxes", "@type": "CreativeWork", "archivedAt": { "@id": "https://aggr.aymericbeaumet.com/items/ampcode-com/2025-08-29-bring-your-own-tools/#webpage" }, "dateModified": "2025-08-29T00:00:00+00:00", "datePublished": "2025-08-29T00:00:00+00:00", "headline": "Bring Your Own Tools", "timeRequired": "PT1M", "url": "https://ampcode.com/news/toolboxes", "wordCount": 213 }, "name": "Archived snapshot: Bring Your Own Tools", "preview": null, "reading_minutes": 1, "replicated_at": null, "source": "ampcode-com", "source_name": "Amp News", "summary": "You can now provide tools to Amp in the form of executable files. If the environment variable AMP_TOOLBOX is set and contains the path to a directory, Amp will look in that directory for executables to be used as tools. On start, Amp will invoke each executable it found, with the environment variable TOOLBOX_ACTION set to describe. The tool is then expected to write its description (which is what will end up in the system prompt that's sent to the agent) to stdout. Here is an example: #!/usr/bin/env bun import fs from 'node:fs' const action = process.env.TOOLBOX_ACTION if (action === 'describe') showDescription() else if (action === 'execute') runTests() function showDescription() { process.stdout.write( JSON.stringify({ name: 'run-tests', description: 'use this tool instead of Bash to run tests in a workspace', args: { dir: ['string', 'the workspace directory'] }, }), ) } When the agent then decides to invoke your tool, Amp runs the executable again, this time setting TOOLBOX_ACTION to execute. Amp passes the tool call arguments on stdin and the executable can then execute the tool call: function runTests() { let dir = JSON.parse(fs.readFileSync(0, 'utf-8'))['dir'] dir = dir && dir.length > 0 ? dir : '.' Bun.spawn(['pnpm', '-C', dir, 'run', 'test', '--no-color', '--run'], { stdio: ['inherit', 'inherit', 'inherit'], }) } You can read more about toolboxes and possible input and output formats in the manual.", "tags": [], "temporalCoverage": "2026-10-04T12:50:30.804479567+00:00", "title": "Bring Your Own Tools", "url": "https://aggr.aymericbeaumet.com/items/ampcode-com/2025-08-29-bring-your-own-tools/", "word_count": 213 }