iCode Agent · Guide · Automation

Automate in scripts and CI.

iCode Agent is a terminal agent, but it does not need a terminal. The same tasks you run interactively run headless with -p, and the runtime's full event stream is available as JSON.

Print mode

Run one task, print the final response, and exit:

icode-agent -p "run the tests and report failures" /path/to/project

The workspace can be given as an argument, or set with --cwd <dir>. Print mode exits 0 when the run reached a final answer and 1 otherwise — so you can branch on it in a script.

JSON event mode

Add --mode json to stream every run event as a JSON line, followed by a final result line. This is the mode for tooling: you get the agent's progress as data, not as terminal output.

icode-agent --mode json -p "find all TODO comments" /path/to/project

The stream includes events such as:

• run_start — the task and the model identity.
• iteration_start, assistant_delta — progress within each step.
• tool_call and tool_result — every tool the agent used and what it returned.
• model_response — token usage for the call, when the provider reports it.
• compaction, projection_reduced — context-management events, so cost behaviour is visible in the stream.
• run_end — the run's summary.

Each line is a complete JSON object, so standard tools — jq, a log pipeline, a CI step — can consume it directly.

Continuing a session

Workspace sessions persist automatically. Continue the most recent one, or resume a specific one by id:

# continue the most recent session in this workspace
icode-agent -c -p "now fix the issue you found" /path/to/project

# resume a specific session
icode-agent --resume <id> -p "add tests for that fix" /path/to/project

A CI example

A step that asks the agent to make the suite pass, and fails the job when it returns non-zero:

icode-agent -p "run the full test suite and fix any failures" "$PWD"
status=$?
if [ "$status" -ne 0 ]; then
  echo "iCode Agent did not reach a passing state." >&2
  exit 1
fi

Project instructions and settings

Headless runs read the same configuration as interactive ones:

• AGENTS.md (or CLAUDE.md) in the repository root is loaded into the system prompt, so CI runs follow your project's rules.
• Global settings live at ~/.icode-agent/settings.json and can be overridden per project at .icode-agent/settings.json.
• Prompt templates (.icode-agent/prompts/*.md) and skills (.icode-agent/skills/<name>/SKILL.md) load automatically.

On a CI runner with no ~/.icode-agent, point ICODE_AGENT_CONFIG_DIR at a prepared directory so the model configuration is available.