iCode Agent · 가이드 · 자동화

스크립트와 CI에서 자동화하세요.

iCode Agent는 터미널 에이전트지만 터미널이 필요하지는 않습니다. 대화형으로 실행하는 작업을 -p로 헤드리스 실행할 수 있고, 런타임의 전체 이벤트 스트림을 JSON으로 받을 수 있습니다.

프린트 모드

작업 하나를 실행하고 최종 응답을 출력한 뒤 종료하세요:

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

워크스페이스는 인수로 지정하거나 --cwd <dir>로 설정할 수 있습니다. 프린트 모드는 실행이 최종 답변에 도달하면 0, 아니면 1로 종료되므로 스크립트에서 분기할 수 있습니다.

JSON 이벤트 모드

--mode json을 추가하면 모든 실행 이벤트가 JSON 줄로 스트리밍되고 마지막에 결과 줄이 이어집니다. 도구용 모드로, 에이전트의 진행 상황을 터미널 출력이 아닌 데이터로 받습니다.

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

스트림에는 다음과 같은 이벤트가 포함됩니다:

  • run_start — 작업과 모델 식별 정보.
  • iteration_start, assistant_delta — 각 단계 내 진행 상황.
  • tool_call 및 tool_result — 에이전트가 사용한 모든 도구와 그 반환 값.
  • model_response — 공급자가 보고하는 경우 해당 호출의 토큰 사용량.
  • compaction, projection_reduced — 컨텍스트 관리 이벤트로, 비용 동작을 스트림에서 확인할 수 있습니다.
  • run_end — 실행 요약.

각 줄은 완전한 JSON 객체이므로 jq, 로그 파이프라인, CI 단계 같은 표준 도구에서 바로 사용할 수 있습니다.

세션 이어가기

워크스페이스 세션은 자동으로 유지됩니다. 가장 최근 세션을 이어가거나 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

CI 예시

에이전트에게 스위트를 통과시키라고 요청하고, 0이 아닌 값을 반환하면 작업을 실패시키는 단계:

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

프로젝트 지침과 설정

헤드리스 실행은 대화형 실행과 같은 구성을 읽습니다:

  • 저장소 루트의 AGENTS.md(또는 CLAUDE.md)가 시스템 프롬프트에 로드되므로 CI 실행이 프로젝트 규칙을 따릅니다.
  • 전역 설정은 ~/.icode-agent/settings.json에 있으며, 프로젝트별로 .icode-agent/settings.json에서 재정의할 수 있습니다.
  • 프롬프트 템플릿(.icode-agent/prompts/*.md)과 스킬(.icode-agent/skills/<name>/SKILL.md)은 자동으로 로드됩니다.

~/.icode-agent가 없는 CI 러너에서는 준비된 디렉터리를 ICODE_AGENT_CONFIG_DIR로 지정해 모델 구성을 사용할 수 있게 하세요.