Claude Code Agent

The claude-code agent wraps Anthropic’s Claude Code CLI (claude binary) to execute coding tasks within your workflow. It receives a prompt assembled from the phase role and upstream context, runs Claude Code against your workspace, and captures the response.

Claude Code is a terminal-based AI coding assistant that can read and write files, run commands, and reason about your codebase. As a cliq agent, it operates non-interactively — receiving its full instructions via the assembled prompt and returning results through the handoff envelope.

Sample Phase

- name: implement
  agent: claude-code
  role: developer
  depends_on: [architect]

Phase Configuration

The claude-code agent supports two phase types:

Phase Type	Description
`standard`	Code generation, implementation, refactoring, documentation
`gate`	Code review, architectural review, quality verdicts

Phase YAML Fields

Field	Type	Required	Description
`name`	`string`	Yes	Unique phase name within the workflow
`type`	`string`	No	`"standard"` (default) or `"gate"`
`agent`	`string`	Yes	Must be `"claude-code"`
`role`	`string`	Yes	Role file name (without `.md`) from `.cliq/roles/`
`depends_on`	`string[]`	No	Upstream phases that must complete before this phase runs
`model`	`string`	No	Model override (e.g., `"claude-sonnet-4-20250514"`)

The role field is required — it tells the agent what persona to adopt and what kind of work to perform. Without a role, the agent has no instructions.

The model field is specified directly on the phase YAML, not in settings. This lets you use different models for different phases in the same pipeline.

Gate Behavior

When used as a gate agent, claude-code reviews the upstream work and produces a verdict parsed from its output:

Verdict	Meaning
`PASS`	Work meets quality bar — pipeline continues
`ROUTE`	Work needs changes — routes back to a prior phase with feedback
`ESCALATE`	Work requires human intervention — pipeline halts

Settings

Key	Required	Default	Description
`agents.claude-code.api_key`	Yes	—	Anthropic API key for the Claude CLI

Configure via:

echo $ANTHROPIC_API_KEY | cliq settings agents.claude-code.api_key --stdin --global

Output

The claude-code agent writes code directly to the workspace and produces a natural language summary of the work performed. It does not produce structured data — its value is in the files it modifies and the explanation it provides.

Handoff Structure

{
    "data": null,
    "text": "The agent's natural language response and summary of work performed."
}

The text field is automatically injected into downstream phases’ prompts, giving subsequent agents full context of what was implemented.

Gate Output

When running as a gate phase, the handoff includes the verdict:

{
    "data": null,
    "text": "Review complete. The implementation correctly handles edge cases for empty arrays and null inputs. Test coverage is comprehensive. PASS"
}

The orchestrator parses the verdict keyword from the response and routes the pipeline accordingly.

Examples

Example: Claude Code as the primary implementation agent

Set claude-code as the implementation agent for a feature pipeline with automated review.

phases:
    - name: implement
      agent: claude-code
      role: developer
      model: claude-sonnet-4-20250514

    - name: review
      type: gate
      agent: claude-code
      role: reviewer
      depends_on: [implement]

    - name: finalize
      agent: git
      action: create_pr
      depends_on: [review]

Example: Mixed-agent pipeline

Use claude-code for implementation with a different agent for review — agents are interchangeable.

phases:
    - name: fetch-requirements
      agent: jira
      action: get_issue
      sources:
          - name: ticket.json
            ref: $(inputs.ticket)

    - name: implement
      agent: claude-code
      role: developer
      depends_on: [fetch-requirements]

    - name: review
      type: gate
      agent: hug
      role: reviewer
      depends_on: [implement]
      review:
          reviewer: [tech-lead]
          artifacts:
              - src/**/*.ts

Example: Set as the team default

To use claude-code for all phases without specifying it on each one, set it as the default agent:

cliq settings default_agent claude-code --global

Then phases without an explicit agent: field will use claude-code:

phases:
    - name: implement
      role: developer

    - name: review
      type: gate
      role: reviewer
      depends_on: [implement]

Setup

1. Install Claude Code

npm install -g @anthropic-ai/claude-code

Verify the binary is available:

claude --version

2. Configure the API key

echo $ANTHROPIC_API_KEY | cliq settings agents.claude-code.api_key --stdin --global

3. Validate

cliq doctor agent claude-code

This checks that the claude binary is on PATH and the API key is configured.