Bindings

import { bindings } from "agentopology";

Bindings connect AgenTopology to specific platforms. Each binding knows how to scaffold config files, resolve model names, map permissions, and handle platform-specific events for its target platform.

Available bindings

AgenTopology ships with five built-in bindings:

import {
  claudeCodeBinding,
  codexBinding,
  geminiCliBinding,
  copilotCliBinding,
  openClawBinding,
} from "agentopology";

Binding	Platform	Import
`claudeCodeBinding`	Claude Code	`agentopology`
`codexBinding`	OpenAI Codex	`agentopology`
`geminiCliBinding`	Gemini CLI	`agentopology`
`copilotCliBinding`	GitHub Copilot CLI	`agentopology`
`openClawBinding`	OpenClaw	`agentopology`

The `bindings` registry

The bindings export is a registry that lets you look up bindings by name:

import { bindings } from "agentopology";

const binding = bindings.get("claude-code");
const files = binding.scaffold(ast, "./output");

The BindingTarget interface

Every binding implements the BindingTarget interface:

interface BindingTarget {
  name: string;

  scaffold(ast: TopologyAST, outputDir: string): GeneratedFile[];

  resolveModel(modelId: string): string;

  resolvePermission(permission: string): string;

  resolveHookEvent(event: string): string;

  validate(ast: TopologyAST): ValidationResult;
}

scaffold()

Generates platform-specific config files from a topology AST. Returns an array of GeneratedFile objects, each with a path and content.

const files = claudeCodeBinding.scaffold(ast, "./output");
// files: [{ path: "CLAUDE.md", content: "..." }, { path: "agents/researcher/CLAUDE.md", content: "..." }]

resolveModel()

Maps an AgenTopology model identifier to the platform's model name. Different platforms use different naming conventions for the same underlying models.

claudeCodeBinding.resolveModel("sonnet");   // "claude-sonnet-4-20250514"
codexBinding.resolveModel("sonnet");         // "o4-mini"
geminiCliBinding.resolveModel("sonnet");     // "gemini-2.5-flash"

resolvePermission()

Maps an AgenTopology permission level to the platform's permission system.

claudeCodeBinding.resolvePermission("read");       // "Read"
claudeCodeBinding.resolvePermission("read-write");  // "Read, Write"

resolveHookEvent()

Maps an AgenTopology hook event name to the platform's event system.

claudeCodeBinding.resolveHookEvent("on-complete");  // "PostComplete"
codexBinding.resolveHookEvent("on-complete");        // "onFinish"

validate()

Runs platform-specific validation rules in addition to the core 82 rules. Each platform may have constraints that the generic validator does not check.

const result = claudeCodeBinding.validate(ast);
if (!result.valid) {
  console.error("Platform-specific errors:", result.errors);
}

The GeneratedFile type

interface GeneratedFile {
  path: string;
  content: string;
}

Returned by scaffold(). The path is relative to the output directory. The content is the full file text.

What's next

Scaffold a topology to a specific platform
Create a custom binding for your own platform
See platform guides for platform-specific details

Bindings

On this page