Claude Code Binding

Status: Stable

The Claude Code binding generates a complete multi-agent workspace from your .at topology file. Each agent becomes a markdown instruction file, MCP servers are wired up, and permissions are mapped to Claude Code's access model.

Scaffolding

agentopology scaffold my-topology.at --target claude-code

Generated File Structure

.claude/
  agents/
    researcher/
      AGENT.md          # Agent instructions with frontmatter
    writer/
      AGENT.md
    reviewer/
      AGENT.md
  commands/
    run-topology.md     # Orchestrator entry point (if orchestrator pattern)
  settings.json         # Permissions and tool access
.mcp.json               # MCP server configurations

Agent Files

Each agent produces an AGENT.md file with Claude Code frontmatter:

---
model: claude-sonnet-4-20250514
permissionMode: plan
tools:
  - Read
  - Grep
  - WebSearch
description: Researches codebase and gathers context for the writing phase
---

# Researcher

You are the researcher agent in the code-review topology.

## Instructions

Analyze the codebase using Read, Grep, and WebSearch tools. Gather all relevant
context before passing findings to the writer agent.

Model Mapping

AgenTopology model names map to Claude Code model identifiers:

AgenTopology	Claude Code
`opus`	`claude-opus-4-20250514`
`sonnet`	`claude-sonnet-4-20250514`
`haiku`	`claude-haiku-3-5-20241022`

Permission Mapping

The permissions field on agents maps to Claude Code's permissionMode frontmatter:

AgenTopology	Claude Code	Behavior
`autonomous`	`auto`	Agent runs without asking for permission
`supervised`	`plan`	Agent presents a plan before executing
`interactive`	`confirm`	Agent asks before each tool use
`unrestricted`	`bypass`	Agent bypasses all permission checks

Example

topology code-review : [pipeline] {
  settings {
    permissions: supervised
  }

  agent researcher {
    model: sonnet
    permissions: autonomous
    tools: [Read, Grep]
  }
}

Generates settings.json with the topology-level default, while the researcher agent overrides with permissionMode: auto in its own AGENT.md frontmatter.

Hook Mapping

AgenTopology hook events translate to Claude Code hook triggers:

AgenTopology Event	Claude Code Hook
`AgentStart`	`SubagentStart`
`AgentStop`	`SubagentStop`
`ToolUse`	`PreToolUse` / `PostToolUse`

Example

topology monitored : [supervisor] {
  hooks {
    on AgentStart { log "Agent starting: $agent.name" }
    on ToolUse    { validate tool.input }
  }
}

Generates hook entries in settings.json:

{
  "hooks": {
    "SubagentStart": [
      {
        "type": "command",
        "command": "echo 'Agent starting: $AGENT_NAME'"
      }
    ],
    "PreToolUse": [
      {
        "type": "command",
        "command": "validate-input.sh"
      }
    ]
  }
}

MCP Server Configuration

MCP servers defined in your topology generate entries in .mcp.json:

topology with-servers : [supervisor] {
  mcp {
    server github {
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-github"]
      env: { GITHUB_TOKEN: "$GITHUB_TOKEN" }
    }
  }
}

Produces:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "$GITHUB_TOKEN"
      }
    }
  }
}

Orchestrator Commands

When the topology uses a supervisor or pipeline pattern, the binding generates a commands/ directory with an orchestrator entry point. This lets you invoke the full topology with a single /run-topology slash command in Claude Code.

Limitations

Claude Code does not support true parallel agent execution. Fan-out patterns are emulated sequentially.
Hook commands run as shell scripts. Complex hook logic should be extracted to standalone scripts.
The scale block is ignored since Claude Code runs locally.

Claude Code

On this page