Choose and configure a code agent

Claude Code, Goose, Qwen Code, and Zed Agent are four 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. Four 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

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 goose_code, qwen_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

Switching agents

You can change a project's 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.

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