Delegate to coding agents

Your lead agent plans the work, but you want Claude Code or Codex to do the edits, because they are good at code and you already use them. codingAgents gives the lead model one tool per coding agent. Each agent works in a sandbox and keeps its own session between calls.

1. Add the plugin

shell

npm i @tanstack/ai-harness @tanstack/ai-sandbox @tanstack/ai-sandbox-local-process @tanstack/ai-claude-code @tanstack/ai-codex

shell

pnpm add @tanstack/ai-harness @tanstack/ai-sandbox @tanstack/ai-sandbox-local-process @tanstack/ai-claude-code @tanstack/ai-codex

shell

yarn add @tanstack/ai-harness @tanstack/ai-sandbox @tanstack/ai-sandbox-local-process @tanstack/ai-claude-code @tanstack/ai-codex

shell

bun add @tanstack/ai-harness @tanstack/ai-sandbox @tanstack/ai-sandbox-local-process @tanstack/ai-claude-code @tanstack/ai-codex

import { defineHarness } from '@tanstack/ai-harness'
import { permissions } from '@tanstack/ai-harness/plugins'
import { claudeCodeText } from '@tanstack/ai-claude-code'
import { codexText } from '@tanstack/ai-codex'
import { openaiText } from '@tanstack/ai-openai'
import { defineSandbox, defineWorkspace, localSource } from '@tanstack/ai-sandbox'
import { codingAgents } from '@tanstack/ai-sandbox/harness'
import { localProcessSandbox } from '@tanstack/ai-sandbox-local-process'

const repo = '/path/to/your/repo'

export const lead = defineHarness({
  name: 'acme/lead',
  adapter: openaiText('gpt-6.1-sol'),
  plugins: () => [
    permissions(),
    codingAgents({
      sandbox: defineSandbox({
        id: 'repo',
        provider: localProcessSandbox({ dir: repo }),
        workspace: defineWorkspace({ source: localSource(repo) }),
      }),
      agents: {
        claude_code: {
          adapter: claudeCodeText('claude-opus-4-8', { permissionMode: 'acceptEdits' }),
          description: 'Larger changes, refactors, and reviews',
        },
        codex: {
          adapter: codexText('gpt-5.3-codex', { sandboxMode: 'workspace-write' }),
          description: 'Quick fixes and tests',
        },
      },
    }),
  ],
})

localProcessSandbox({ dir: repo }) works in your repo folder itself, so every thread and every agent shares that folder. Leave out dir to give each sandbox its own copy of the repo.

The lead model now has a claude_code tool and a codex tool. Each tool takes one task: the whole job, in words. The agent sees only that text and the files in its sandbox.

2. Ask for work

Open a session, and give the lead a task for both agents:

import { createHarnessHost } from '@tanstack/ai-harness'
import { memoryPersistence } from '@tanstack/ai-persistence'

const host = createHarnessHost({ persistence: memoryPersistence() })
const session = await host.open(lead, { threadId: 'date-parser' })

const turn = await session.send(
  'Have claude_code add a test for the date parser, then have codex fix what fails.',
)
console.log(turn.text)

The lead calls claude_code with a task, and gets back its answer. Then it calls codex. Each agent works in the same sandbox, one after the other.

Sessions

Each agent keeps its own session per harness thread. The next task for claude_code resumes the same Claude Code session, so it still knows the files it read. The session ids live in the plugin state, so they also survive a restart of the host.

To start over, run /fresh claude_code, or /fresh for every agent.

Workspaces

workspace chooses where the agents work:

Value	Where each agent works	At the same time
'shared' (default)	One sandbox per harness thread	One agent at a time
'per-agent'	A sandbox per agent	Yes

Use 'shared' when the agents build on each other's changes. Use 'per-agent' when they work on separate copies and you merge the results.

Only the host that owns the log of the thread runs its agents. So with many servers, 'shared' still runs one agent at a time.

Plan mode

When the permissions() plugin is in plan mode, the agents start read-only:

Claude Code gets permissionMode: 'plan'.
Codex gets sandboxMode: 'read-only'.
Any other agent gets its planModelOptions, for example { permissionMode: 'default' } for an ACP agent that asks before each edit.
An agent with no planModelOptions does not run in plan mode. Its tool call gets an error.

Other agents and sandboxes

adapter takes any coding-agent adapter: grokBuildText from @tanstack/ai-grok-build, or acpCompatibleText from @tanstack/ai-acp for any ACP agent.
sandbox takes any sandbox provider. Sandbox providers lists them.
modelOptions on an agent is added to every call, for example a fixed permissionMode.