@code-first-agents/tool

TypeScript implementation of the Code-First Agents pattern. Provides a Tool base class that enforces the tool contract: deterministic CLI tools with Zod input/output schemas, JSON envelope output, self-describing introspection (--schema, --help), and always-exit-0 semantics.

Key idea: deterministic work lives in code (Tools), the LLM orchestrates judgment (Skills). This library is the Tool side.

ℹ️ This project is maintained in spare time. Issues and pull requests are very welcome — please bear with best-effort response times.

Installation

bun add @code-first-agents/tool zod@^4
# or
npm install @code-first-agents/tool zod@^4

Peer dependency: Zod v4 (^4.0.0).

Usage

A Tool registers subcommands — each with a Zod input schema, an output schema, and a handler — then dispatches via CLI args or programmatic invocation.

Minimal example

#!/usr/bin/env bun
import { z } from "zod";
import { Tool, l1Output } from "@code-first-agents/tool";

const tool = new Tool({
  name: "math",
  description: "Basic math operations",
});

tool.subcommand({
  name: "multiply",
  description: "Multiply two numbers",
  input: z.object({
    a: z.coerce.number(),
    b: z.coerce.number(),
  }).strict(),
  output: l1Output({ product: z.number() }),
  handler: ({ a, b }) => ({
    message: "multiplied",
    product: a * b,
  }),
});

tool.run(process.argv.slice(2));

Run it from the CLI:

bun run math.ts multiply --a 6 --b 7
# → {"ok":true,"message":"multiplied","product":42}

Output levels

The spec defines three output levels. Use the corresponding helper to build the output schema:

L1 — Data (raw facts for the LLM to interpret):

import { l1Output } from "@code-first-agents/tool";

tool.subcommand({
  name: "greet",
  description: "Greet someone by name",
  input: z.object({ name: z.string() }).strict(),
  output: l1Output({ greeting: z.string() }),
  handler: ({ name }) => ({
    message: `greeted ${name}`,
    greeting: `hello ${name}`,
  }),
});

L2 — Classification (a discrete category the skill can branch on):

import { l2Output } from "@code-first-agents/tool";

tool.subcommand({
  name: "report",
  description: "Emit a report classified by log level",
  input: z.object({
    level: z.enum(["info", "debug"]).default("info"),
  }).strict(),
  output: l2Output(z.enum(["info", "debug"])),
  handler: ({ level }) => ({
    message: `report generated (level=${level})`,
    classification: level,
  }),
});

L3 — Instructions (a verbatim procedure for the LLM to execute):

import { l3Output } from "@code-first-agents/tool";

tool.subcommand({
  name: "instruct",
  description: "Emit a verbatim instruction set",
  input: z.object({}).strict(),
  output: l3Output({ topic: z.string() }),
  handler: () => ({
    message: "instructions generated",
    instructions: "## Step 1\nDo the thing.",
    topic: "setup",
  }),
});

Handler contract

• Handlers return the output shape without ok — the framework stamps ok: true automatically.
• Handlers always return a message: string describing what happened.
• Input schemas should use .strict() to reject unknown flags.
• Handlers can be sync or async.

Error handling

All errors exit with code 0 and return { ok: false, error: "...", ... }. Throw ToolError for domain-specific errors:

import { ToolError } from "@code-first-agents/tool";

tool.subcommand({
  name: "validate",
  description: "Validate a config file",
  input: z.object({ path: z.string() }).strict(),
  output: l1Output({}),
  handler: ({ path }) => {
    throw new ToolError("validation_failed", `Config at '${path}' is invalid`);
  },
});

The framework also handles: unknown_subcommand, input_validation_error, schema_violation, non_object_return, and unexpected_error.

Built-in subcommands

Every tool gets schema and help for free:

bun run math.ts schema   # JSON Schema for all subcommands
bun run math.ts help     # Human-readable subcommand listing

These are auto-registered — you cannot override them.

Programmatic invocation

Use .invoke() to call a subcommand in-process (useful in tests):

const result = await tool.invoke("multiply", { a: 6, b: 7 });
// → { ok: true, message: "multiplied", product: 42 }

Examples

A complete, clonable tool lives in examples/ — run it and compare the JSON, no build step required:

bun run examples/changeset.ts size --files 12 --additions 340 --deletions 50
# → {"ok":true,"message":"changeset classified as large","classification":"large","total_lines":390}

examples/changeset.ts is one tool that demonstrates all three output levels (L1 data, L2 classification, L3 instructions). See examples/README.md for the full walkthrough.

API Reference

All exports come from the package root (@code-first-agents/tool). See the spec for the contract these implement.

| Export | Kind | Purpose | | ---------------------------- | -------- | ---------------------------------------------------------------------------------------- | | Tool | class | The orchestrator. Construct with { name, description }, register subcommands, dispatch. | | tool.subcommand(config) | method | Register a subcommand with Zod input/output schemas and a handler. | | tool.run(argv) | method | Parse CLI args, dispatch, print the JSON envelope, and process.exit(0). | | tool.invoke(name, args) | method | Call a subcommand in-process; returns the envelope object (useful in tests). | | l1Output(shape) | function | Build an L1 (data) output schema — raw signals for the LLM to interpret. | | l2Output(classification, fields?) | function | Build an L2 (classification) output schema — a discrete category to branch on. classification is any Zod type (commonly z.enum(...)). | | l3Output(fields?) | function | Build an L3 (instructions) output schema — a verbatim procedure for the LLM. Fields are optional. | | ToolError | class | Throw inside a handler for domain-specific errors: new ToolError(code, message, detail?). Optional detail (string or object) is included in the error envelope's detail field. | | schema (builtin) | command | Auto-registered. Emits JSON Schema for every subcommand. Not user-overridable. | | help (builtin) | command | Auto-registered. Emits a human-readable subcommand listing. Not user-overridable. |

Every successful result is the envelope { ok: true, message, ... }; every error is { ok: false, error, ... } with exit code 0.

Development

Prerequisites: Bun >= 1.0

git clone https://github.com/beogip/code-first-agents-tool.git
cd code-first-agents-tool
bun install

| Command | Description | | ---------------- | ------------------------------- | | bun run dev | Re-run src/index.ts on change (watch) | | bun run build | Compile to dist/ (bun + tsc) | | bun test | Run tests | | bun run check | Lint + format (Biome, auto-fix) | | bun run lint | Lint only | | bun run format | Format only |

Project Structure

src/          # Source code
tests/        # Test files (*.test.ts)
dist/         # Build output (git-ignored)

Git Hooks

Lefthook runs automatically after bun install (via the prepare script):

• pre-commit — Biome checks and auto-fixes staged files
• commit-msg — Validates Conventional Commits format

Releases

Releases are automated via semantic-release on every push to main:

• feat: → minor release
• fix: → patch release
• feat!: or BREAKING CHANGE: → major release

The CI workflow handles changelog generation, npm publishing, GitHub releases, and version bumping automatically.

The Code-First Agents Pattern

This library implements the tool contract from the Code-First Agents spec. The spec defines a separation principle:

• Tools (this library) — deterministic, no LLM calls, Zod-validated I/O, JSON envelope output.
• Skills — LLM-powered orchestrators that call tools and apply judgment.

If you're new to the pattern, start with the spec repo for the full picture of how tools, skills, and agents compose together.

License

MIT