Home/Docs/Code-Execution Mode

Code-Execution Mode

Load Planwright tool definitions on demand instead of all 14 upfront. Based on Anthropic's code-execution-with-MCP guidance — up to 98.7% token savings.

How it works

Standard MCP mode loads all 14 Planwright tool schemas into the agent's context window at session start. This is reliable but expensive — every tool definition costs tokens even if the agent only needs two of them.

Code-execution mode flips this: the agent reads a lightweight manifest (planwright://tools/index.ts), then imports only the tools it needs. The agent writes TypeScript code that calls typed wrapper functions. Intermediate results stay in the code sandbox instead of passing through the context window.

Token comparison

Standard mode

~4,200 tokens

14 tool schemas loaded into context at session start. Every request pays the full definition tax.

Code-execution mode

~800 tokens

Only the manifest + imported tool definitions. Agent loads 2-3 tools per run instead of 14.

Available resources

planwright://tools/
├── index.ts    — manifest listing all tools with descriptions
├── tools.ts    — typed wrappers for all 14 tools
└── client.ts   — callTool bridge function declaration

Read these via the MCP resources/read API on your existing Planwright connection.

Example agent workflow

// 1. Read the manifest to discover available tools
const manifest = await readResource("planwright://tools/index.ts");

// 2. Import only what you need
import { setRepo, listObjectives, claimObjective,
         appendPlan, recordDiff, requestAcceptance
       } from './tools';

// 3. Execute the workflow
await setRepo({ githubRepo: "acme/backend" });
const { objectives } = await listObjectives({ lane: "scheduled" });
const work = objectives[0];

const { agentRunId } = await claimObjective({
  objectiveId: work.id,
  agentKind: "claude-code",
});

await appendPlan({ agentRunId, planMarkdown: "## Plan\n..." });

// ... do the work ...

await recordDiff({
  agentRunId,
  diffSummary: "Added OAuth login flow",
  filesChanged: 3,
  testsPassed: true,
});

await requestAcceptance({
  objectiveId: work.id,
  agentRunId,
  summary: "OAuth flow implemented and tested.",
});

When to use each mode

Use standard mode when:

- Your agent runtime doesn't support code execution
- You want the simplest possible setup (just connect and go)
- Token cost isn't a concern for your use case

Use code-execution mode when:

- You're running many agent sessions and want to minimize token cost
- Your agent only needs 2-3 tools per run (e.g. claim + diff + accept)
- Your runtime supports TypeScript code execution (Claude Code, Codex)
- You want intermediate results to stay in the sandbox, not context