Custom Tools

Copair comes with 8 built-in tools, but you can extend it with custom tools tailored to your workflow.

Built-in Tools

Creating a Custom Tool

Custom tools are defined as JavaScript/TypeScript modules that export a tool definition:

// tools/deploy.ts
import { defineTool } from 'copair'

export default defineTool({
  name: 'Deploy',
  description: 'Deploy the application to the staging or production environment',
  parameters: {
    environment: {
      type: 'string',
      enum: ['staging', 'production'],
      description: 'Target environment',
    },
  },
  async execute({ environment }) {
    const command = environment === 'production'
      ? 'npm run deploy:prod'
      : 'npm run deploy:staging'

    const result = await this.bash(command)
    return result
  },
})

Registering Tools

Add custom tools to your project configuration:

// .copair/config.json
{
  "tools": [
    "./tools/deploy.ts",
    "./tools/database.ts"
  ]
}

Copair will load these tools at startup and make them available to the agent.

Tool API

Custom tools have access to Copair's built-in capabilities:

export default defineTool({
  name: 'MigrateDB',
  description: 'Run database migrations',
  parameters: {
    direction: {
      type: 'string',
      enum: ['up', 'down'],
    },
  },
  async execute({ direction }) {
    // Use built-in bash tool
    const result = await this.bash(`npx prisma migrate ${direction}`)

    // Use built-in read tool
    const schema = await this.read('prisma/schema.prisma')

    return {
      migrationResult: result,
      currentSchema: schema,
    }
  },
})

Use Cases

Custom tools are useful for:

• Deployment — Deploy to specific environments with pre-flight checks
• Database — Run migrations, seed data, query databases
• Testing — Run specific test suites, generate test data
• API calls — Interact with internal APIs, fetch configuration
• Code generation — Generate boilerplate, scaffolding, or templates
• Linting — Run project-specific linters or formatters

Best Practices

• Keep tools focused — Each tool should do one thing well
• Provide clear descriptions — The AI model uses the description to decide when to use the tool
• Validate inputs — Use parameter schemas to ensure correct usage
• Return structured data — Return objects rather than raw strings when possible
• Handle errors gracefully — Catch exceptions and return meaningful error messages