Custom Tools

There are two ways to extend altimate-code with custom tools:

1. CLI tools (recommended) — simple executables paired with skills
2. Plugin tools — TypeScript-based tools using the plugin API

CLI Tools (Recommended)

The simplest way to add custom functionality. Drop any executable into .altimate-code/tools/ and it's automatically available to the agent via bash.

Quick Start

# Scaffold a skill + CLI tool pair
altimate-code skill create my-tool

# Or create manually:
mkdir -p .altimate-code/tools
cat > .altimate-code/tools/my-tool << 'EOF'
#!/usr/bin/env bash
set -euo pipefail
echo "Hello from my-tool!"
EOF
chmod +x .altimate-code/tools/my-tool

Tools in .altimate-code/tools/ are automatically prepended to PATH when the agent runs bash commands. No configuration needed. The legacy .opencode/tools/ directory is also loaded for back-compat.

Tool Locations

Location	Scope	Auto-discovered
.altimate-code/tools/	Project	Yes
.opencode/tools/	Project (legacy)	Yes
~/.config/altimate-code/tools/	Global (all projects)	Yes

Pairing with Skills

Create a SKILL.md that teaches the agent when and how to use your tool:

altimate-code skill create my-tool --language python

This scaffolds a SKILL.md and a paired executable under the project config dir. Edit both files to implement your tool. (Both .altimate-code/ and .opencode/ locations are auto-discovered, so either works.)

Validating

altimate-code skill test my-tool

This checks that the SKILL.md is valid and the paired tool is executable.

Installing Community Skills

Install skills (with their paired tools) from GitHub:

# From a GitHub repo
altimate-code skill install anthropics/skills
altimate-code skill install dagster-io/skills

# From a GitHub web URL (pasted from browser)
altimate-code skill install https://github.com/owner/repo/tree/main/skills/my-skill

# Remove an installed skill
altimate-code skill remove my-skill

Or use the TUI: type /skills, then ctrl+i to install or ctrl+a → Remove to delete.

Output Conventions

For best results with the AI agent:

• Default output: Human-readable text (the agent reads this well)
• --json flag: Structured JSON for scripting
• Summary first: "Found 12 matches:" or "3 issues detected:"
• Errors to stderr, results to stdout
• Exit code 0 = success, 1 = error

Plugin Tools (Advanced)

For more complex tools that need access to the altimate-code runtime, use the TypeScript plugin system.

Quick Start

1. Create a tools directory:

mkdir -p .altimate-code/tools

1. Create a tool file:

// .altimate-code/tools/my-tool.ts
import { defineTool } from "@altimateai/altimate-code-plugin/tool"
import { z } from "zod"

export default defineTool({
  name: "my_custom_tool",
  description: "Does something useful",
  parameters: z.object({
    input: z.string().describe("The input to process"),
  }),
  async execute({ input }) {
    // Your tool logic here
    return { result: `Processed: ${input}` }
  },
})

Plugin Package

For more complex tools, create a plugin package:

npm init
npm install @altimateai/altimate-code-plugin zod

// index.ts
import { definePlugin } from "@altimateai/altimate-code-plugin"
import { z } from "zod"

export default definePlugin({
  name: "my-plugin",
  tools: [
    {
      name: "analyze_costs",
      description: "Analyze warehouse costs",
      parameters: z.object({
        warehouse: z.string(),
        days: z.number().default(30),
      }),
      async execute({ warehouse, days }) {
        // Implementation
        return { costs: [] }
      },
    },
  ],
})

Registering Plugins

Add plugins to your config:

{
  "plugin": [
    "@altimateai/altimate-code-plugin-example",
    "./my-local-plugin"
  ]
}

Plugin Hooks

Plugins can hook into 30+ lifecycle events:

• onSessionStart / onSessionEnd
• onMessage / onResponse
• onToolCall / onToolResult
• onFileEdit / onFileWrite
• onError
• And more...

Disabling Default Plugins

export ALTIMATE_CLI_DISABLE_DEFAULT_PLUGINS=true