Exec Agent

The exec agent runs shell commands sequentially within a pipeline phase. Each command is executed via execSync with a 2-minute timeout, and output streams to the tmux pane for visibility.

Unlike other agents, the exec agent has no LLM involvement — it is purely deterministic. No role file is required. Use it for build steps, test suites, linting, deployments, or any shell-based automation that needs structured pass/fail reporting.

---

Sample Phase

- name: test
  agent: exec
  commands:
      - name: unit-tests
        run: npm test
        escalate_on_fail: true

---

Phase Configuration

The exec agent uses a commands array on the phase declaration. Each entry defines a named shell command to run.

Phase YAML Fields

Field	Type	Required	Description
name	string	Yes	Unique phase name within the workflow
type	string	No	Defaults to "standard"
agent	string	Yes	Must be "exec"
depends_on	string[]	No	Upstream phases that must complete before this phase runs
commands	Command[]	Yes	Ordered list of shell commands to execute

Command Entry Fields

Field	Type	Required	Default	Description
name	string	Yes	—	Display name for the command (shown in logs and output)
run	string	Yes	—	Shell command to execute
escalate_on_fail	boolean	No	false	If true, stop execution and escalate the phase immediately on failure

Commands execute in order. If escalate_on_fail is not set, a failing command is recorded but execution continues to the next command.

---

Settings

No agent-specific settings required.

---

Output

Handoff Structure

{
    "data": {
        "results": [
            {
                "name": "unit-tests",
                "pass": true,
                "exit_code": 0,
                "duration_ms": 4520
            },
            {
                "name": "integration-tests",
                "pass": false,
                "exit_code": 1,
                "duration_ms": 12300
            }
        ],
        "all_passed": false,
        "total": 2,
        "failed": 1
    },
    "text": "## Exec Results\n\n✓ unit-tests (4520ms)\n✗ integration-tests — exit code 1 (12300ms)\n\n1 of 2 commands failed."
}

Field Reference

Field	Location	Description
results	data.results	Array of per-command result objects
results[].name	data.results[]	Command display name
results[].pass	data.results[]	Whether the command exited with code 0
results[].exit_code	data.results[]	Process exit code
results[].duration_ms	data.results[]	Execution time in milliseconds
all_passed	data	true if every command exited with code 0
total	data	Total number of commands executed
failed	data	Count of commands that exited non-zero

Downstream Access

commands:
    - name: check
      run: 'test $(handoff.build.data.all_passed) = true'

---

Examples

Example: Build and test before review

Run build and test steps, then pass results to a review gate.

phases:
    - name: build-and-test
      agent: exec
      commands:
          - name: install
            run: npm ci
          - name: build
            run: npm run build
            escalate_on_fail: true
          - name: unit-tests
            run: npm test
          - name: lint
            run: npm run lint

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

Example: Deploy with escalation on failure

Run deployment commands where any failure immediately escalates the pipeline.

phases:
    - name: implement
      agent: cursor

    - name: deploy
      agent: exec
      depends_on: [implement]
      commands:
          - name: docker-build
            run: docker build -t myapp:latest .
            escalate_on_fail: true
          - name: docker-push
            run: docker push registry.example.com/myapp:latest
            escalate_on_fail: true
          - name: k8s-apply
            run: kubectl apply -f k8s/
            escalate_on_fail: true

Example: Validation gate commands

Use exec as a pre-check phase that feeds into a conditional workflow.

phases:
    - name: validate
      agent: exec
      commands:
          - name: schema-check
            run: npx ajv validate -s schema.json -d config.json
          - name: security-scan
            run: npx audit-ci --moderate

    - name: implement
      agent: cursor
      depends_on: [validate]

---

Setup

No setup required. The exec agent has no external dependencies — it runs commands using the system shell available in the pipeline environment.

cliq doctor agent exec always passes.

---

See Also

• Agent Overview