Software factory / Agent workflows
Run a coding CLI in a step
You want Claude Code or Codex to work on your repository as it does on your own computer: read the code, edit files, run the tests, and try again. You do not want to put a model key in a container that runs repository code.
6 min read
CLI execution is currently disabled. The protected controller is in preparation. Admission refuses CLI jobs before they reserve capacity or start a VM. The repository executor also refuses CLI model and MCP requests.
The examples on this page describe CLI configuration for later activation. Use the default forge harness for live workflows. Activation requires a verified shutdown boundary and runtime proof. The prepared lifecycle connects queue admission, sessions, delegated tools, shutdown, exact backups, and protected reports. Its production gate remains closed.
Start with a working workflow: see Write your first agent workflow.
1. Pick a CLI and a model
Each CLI speaks the API of one model provider. Pick a model that this API serves:
harness | CLI | Models |
|---|---|---|
claude-code | Claude Code | anthropic, or a workers-ai model that starts with anthropic/ |
opencode | OpenCode | the same as claude-code |
codex | Codex | openai, or a workers-ai model that starts with openai/ |
grok-build | Disabled until controlled workspace routing has proof | None |
A model on your own key needs the key in the factory settings. A workers-ai model is paid by the forge.
2. Write the step
After activation, this example asks Claude Code to fix tests through delegated workspace tools. It then calls open_pr:
import { agent, defineAgentWorkflow, manual } from '@tanstack-source/ci'
const model = { provider: 'anthropic', model: 'claude-opus-5-5' } as const
export default defineAgentWorkflow('fix-tests', { on: [manual()] }).job('fix', {
permissions: { contents: 'write' },
steps: [
{ name: 'Install', run: 'pnpm install' },
agent({
name: 'Fix',
model,
harness: 'claude-code',
system: 'Keep the change small.',
prompt: 'Fix the failing tests. Run pnpm test to see them. Then open a pull request into main with open_pr.',
tools: ['open_pr'],
budget: { maxCostUsd: 3 },
}),
],
})
Save it as .source/agent-workflows/fix-tests.ts and merge it into the default branch.
3. Wait for activation
These run steps apply only after activation. The current release refuses this job.
- Start the run:
src factory workflow run fix-tests. - Open the run page, and click the cell
fix. - When the CLI ends, its output is in the log of the cell.
Expected result after activation
The executor holds the file changes. The forge opens a pull request from agent/fix-tests/<branch>. A person reviews and merges it.
What the prepared controller receives
The CLI runs in a separate controller VM. It has no checkout, repository configuration, workflow environment, or secret placeholders.
- The fixed CLI profile and the step prompt. The controller reads the prompt from a private file.
- Only the selected model, including auxiliary model calls that the CLI makes.
- Separate step credentials for the model proxy and forge MCP server. The provider key stays in the job object.
- The approved forge tool catalog. Workspace tools run in the protected repository executor.
The executor holds /workspace/repo, the workflow and job environment, and secret placeholders. Delegated run_command calls use that environment. Repository commands and Git filters must run inside the protected scope. The trusted archive helper runs outside it.
Forge tools and MCP connections
A CLI step takes tools and mcp, as a forge agent step does. The CLI gets them as one MCP server named forge:
agent({
name: 'Fix',
model,
harness: 'claude-code',
prompt: 'Fix the Linear issue, then open a pull request into main.',
tools: ['read_file', 'comment', 'open_pr'],
mcp: ['linear'],
})
- The forge tools are the same tools, with the same limits, as in a forge agent step. For example,
open_prpushes only toagent/<workflow>/<branch>, and a job withoutpermissions: { contents: 'write' }gets no write tool. - An MCP connection gives its tools only when it picks the job, as Write your first agent workflow shows. An untrusted run gets only the read-only tools.
run_commanduses the workflow and job environment, including secret placeholders, in the executor.- Each tool runs on the forge, not in the container. The credentials of the MCP connections never enter the container.
- The controller uses separate step credentials for MCP and model calls.
- A CLI shows each tool with the server name. Claude Code shows
open_prasmcp__forge__open_pr, OpenCode asforge_open_pr, and Codex asopen_prin the groupmcp__forge.
The plan refuses every grok-build step until controlled workspace routing has proof. Use Claude Code, Codex, OpenCode, or a forge step.
Limits
- A CLI step takes no
customTools,skills,codeMode,media,outputorreasoning. The plan refuses the workflow when a CLI step sets one. Use a forge agent step for them. - The controller delegates workspace work through the
forgeMCP server. Its native workspace tools are disabled or refused by the model gate. The forge refuses a model call with a tool that runs at the provider (a web search, a web fetch, code execution, an MCP server of the provider), a background or stored response, a call that goes on from a stored response, or the priority tier. The forge turns off the web search of Codex for you. - The step's
budget, the job'sbudgetand the monthly spend cap hold. Before each model call, the forge keeps back what the call can cost, and it lowers the call's largest output to what is left. At a limit, the forge refuses the CLI's next model call, and the step ends as a budget end. - A model call that the CLI stops before its end still counts. When the provider did not send its count, the forge counts an estimate: the call's largest output for a stopped call.
- When the CLI exits with an error, the step fails. The end of its output is in the log.
- The log shows the output of the CLI when it ends, not while it runs.
When execution stops
CLI execution remains disabled while the shutdown and backup boundary needs proof. The prepared path closes admissions, stops operations, and requires a full immutable workspace backup before planned replacement.
An unknown operation outcome blocks later steps and retries. Do not restart the CLI from its prompt to bypass that refusal. Inspect the operation and its effects first. A completed operation receipt can return its saved result without performing the write again.
Activation requires fresh Cloudflare capability proof for each executor image, including freeze and resume. It also requires private backup-gateway restore proof, compatible receivers after a 300-second drain, and authenticated MCP ping proof with each pinned CLI. Local tests do not meet those release gates.
The prepared isolated OpenCode profile disables its automatic title agent. Title calls have no direct tools. They cannot meet the protected tool catalog rule. Agent model calls still require the published direct tools. The controller prepares a private Codex home before CLI startup. These changes do not open the activation gates.