Choose and configure a code agent

Claude Code, OpenAI Codex, Gemini CLI, Qwen Code, Goose, and Zed Agent are pluggable engines for the same agent loop. This guide tells you when to pick which.

Every Helix project uses a code agent — the software that runs inside the sandbox, reads your codebase, and makes changes. Several engines are available. They all run in the same isolated desktop, stream through the same UI, and produce pull requests the same way. The choice is about the agent's harness, model access, and workflow features.

Quick reference

Claude Code, OpenAI Codex, Gemini CLI, and Qwen Code are CLIs Helix launches inside the sandbox and connects to Zed over ACP (Agent Client Protocol) — the same integration point any ACP-compatible agent uses.

If you're not sure, start with Claude Code or Zed Agent — they're the lowest-friction choices.

Selecting an agent for a project

Set the runtime on the agent in your project YAML:

apiVersion: helix.ml/v1alpha1
kind: Project
metadata:
  name: my-app
spec:
  repositories:
    - url: "https://github.com/org/my-app"
      branch: main
      primary: true
  agent:
    name: "My Agent"
    runtime: claude_code   # or codex_cli, gemini_cli, qwen_code, goose_code, zed_agent

Claude Code

Claude Code is Anthropic's official command-line coding agent. Helix launches the claude CLI inside the sandbox and connects it to Zed over ACP.

  agent:
    name: "Claude Code"
    runtime: claude_code

Claude Code manages its own model selection internally — you don't set model or provider.

Credential modes

API key (default): Routes through the Helix proxy using your configured Anthropic provider. No client-side OAuth needed.

Subscription: Use your Claude Pro or Max subscription directly.

  agent:
    runtime: claude_code
    code_agent_credential_type: subscription

The first session walks through an OAuth flow; credentials are persisted to the sandbox for subsequent sessions.

Pick Claude Code when

• You want the latest Claude models with Anthropic's own prompt design and tool set
• You want your Claude subscription quota to power agents instead of a metered API key
• You want Claude Code ecosystem integrations (skills, MCPs, hooks) without rebuilding them

Goose

Goose is an open-source agent from the Agentic AI Foundation. Its key feature is recipes — reusable, parameterised playbooks you attach to a project once and invoke per task from a structured form.

  agent:
    name: "Goose Agent"
    runtime: goose_code
    model: claude-sonnet-4-6
    provider: anthropic

Project recipes

Recipes are YAML files in your repository. Attach them to the project, and Helix renders a parameter-capture form on the task creation screen for each one:

  agent:
    runtime: goose_code
    goose:
      recipes:
        - name: triage
          path: .goose/recipes/triage.yaml
        - name: fix-flaky-test
          path: .goose/recipes/fix-flaky-test.yaml

A recipe file looks like:

version: "1.0.0"
title: "Triage failing CI"
instructions: |
  Stay focused on the failing CI run. Produce a triage note.
prompt: |
  Investigate the failing CI run at {{ ci_url }} for branch {{ branch }}.
parameters:
  - key: ci_url
    input_type: string
    requirement: required
  - key: branch
    input_type: string
    requirement: required

Starter recipes (triage, release notes, fix-flaky-test, implement-from-spec) are available in examples/goose_recipes/.

For the full recipe configuration reference — parameter types (string, select, file), recipe_repo_url, and the spec-task form workflow — see Configure Goose recipes.

Pick Goose when

• You want to codify recurring task types ("how we triage CI failures", "how we cut release notes") as versioned, reusable recipes
• You want structured parameter capture at task creation time — no free-text prompting for context the agent always needs

Qwen Code

Qwen Code is an open-source agent that speaks the OpenAI API — so it works with any provider behind that interface, not just Qwen models.

  agent:
    name: "Qwen Coder"
    runtime: qwen_code
    model: qwen3-coder-480b
    provider: helix

Helix routes the agent through its /v1 proxy in OpenAI-compatible mode, so any provider you've configured under Account → AI Providers is available — set provider to match.

Pick Qwen Code when

• You want a fully open-source agent stack (no Anthropic dependency)
• You're running local models on a Helix runner
• You need to point the agent at a self-hosted OpenAI-compatible endpoint

Zed Agent

The Zed Agent is the built-in agent panel in the Zed editor. Helix doesn't launch a separate CLI — the user opens Zed's agent panel and interacts with it directly inside the sandbox desktop.

  agent:
    name: "Zed Agent"
    runtime: zed_agent
    model: claude-sonnet-4-6
    provider: anthropic

Like the other agents, the model routes through Helix's /v1 proxy, so any configured provider works.

Pick Zed Agent when

• You want a fully in-editor experience with no extra CLI to install or maintain
• You want to interact with the agent directly in the IDE panel rather than through a separate Helix thread

OpenAI Codex

OpenAI Codex CLI is OpenAI's official command-line coding agent. Helix launches the codex CLI inside the sandbox and connects it to Zed over ACP.

  agent:
    name: "OpenAI Codex"
    runtime: codex_cli

Like the other CLI agents, models route through Helix's proxy, so any provider you've configured under Account → AI Providers is available.

Pick OpenAI Codex when

• You want OpenAI's official coding harness and models
• Your team already builds around the Codex CLI workflow

Gemini CLI

Gemini CLI is Google's official command-line agent. Helix launches the gemini CLI inside the sandbox and connects it to Zed over ACP.

  agent:
    name: "Gemini CLI"
    runtime: gemini_cli

Models route through Helix's proxy in the same way as the other CLI agents.

Pick Gemini CLI when

• You want Google's official CLI and Gemini models
• You're standardising on the Gemini ecosystem

Switching agents

You can change a project's default agent runtime at any time by editing the project YAML. Active spec tasks continue with the agent that started them; new tasks pick up the new runtime.

To switch the agent on a running spec task without starting over, see Switch agents mid-session.

The Concepts: Agents vs code agents page explains the underlying distinction if you want to understand the model.