Documentation/

Custom Tools

Every project has its own scripts — deploy, database migrations, health checks, notifications. They live in shell scripts that only you know how to run. Your AI agents can't use them. New team members don't know they exist.

Define a tool in YAML. Run it from CLI. Your AI agent and editor can use it too. One definition, every surface.

Create a Tool

8v action create deploy --template deploy

This scaffolds a tool definition in your project's .8v/actions/ directory.

Tool Format

A tool is a YAML file:

name: deploy
description: Deploy to staging
inputs:
  env:
    type: string
    default: staging
run: |
  ./scripts/deploy.sh --env {{ env }}
  • name — how you invoke it
  • description — what it does (shown to AI agents so they know when to use it)
  • inputs — typed parameters with optional defaults
  • run — the shell command to execute, with template variables

Run a Tool

8v action run deploy                    # Uses default inputs
8v action run deploy --env production   # Override an input

List Available Tools

8v action list                          # See all tools in this project

This shows built-in tools (build, test, lint, format, search) and any custom tools you've defined.

Browse Templates

8v action examples                      # See all available templates

Templates give you a starting point:

TemplateWhat It Does
shellRun any shell command
lintCustom lint check
deployDeployment script
notifySend a notification
testCustom test runner

One Definition, Every Surface

This is the key idea: define a tool once, and it's available everywhere.

  • CLI — 8v action run deploy
  • AI agents — Claude Code, Codex, Aider see it and can invoke it
  • Editors — Cursor, Windsurf, Zed expose it through their AI assistant

When an AI agent needs to deploy, it sees your deploy tool, reads the description, understands the inputs, and runs it. No extra integration. No wiring. You defined it once.

Where Tools Live

Tool definitions are stored in .8v/actions/ inside your project. They're plain YAML files — commit them to version control so your team has the same tools.

Next

Referenced by