iCode Agent · Guia · Automação

Automatize em scripts e na CI.

O iCode Agent é um agente de terminal, mas não precisa de um terminal. As mesmas tarefas executadas interativamente rodam headless com -p, e o stream completo de eventos do runtime fica disponível como JSON.

Modo de impressão

Execute uma tarefa, imprima a resposta final e saia:

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

O espaço de trabalho pode ser passado como argumento ou definido com --cwd <dir>. O modo de impressão sai com 0 quando a execução chegou a uma resposta final e 1 caso contrário — assim você pode ramificar com base nisso em um script.

Modo de eventos JSON

Adicione --mode json para transmitir cada evento da execução como uma linha JSON, seguida por uma linha de resultado final. Este é o modo para ferramentas: você recebe o progresso do agente como dados, não como saída de terminal.

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

O stream inclui eventos como:

  • run_start — a tarefa e a identidade do modelo.
  • iteration_start, assistant_delta — progresso dentro de cada etapa.
  • tool_call e tool_result — cada ferramenta que o agente usou e o que ela retornou.
  • model_response — uso de tokens da chamada, quando o provedor informa.
  • compaction, projection_reduced — eventos de gerenciamento de contexto, para que o comportamento de custo fique visível no stream.
  • run_end — o resumo da execução.

Cada linha é um objeto JSON completo, então ferramentas padrão — jq, um pipeline de logs, uma etapa de CI — podem consumi-lo diretamente.

Continuando uma sessão

As sessões do espaço de trabalho persistem automaticamente. Continue a mais recente ou retome uma específica pelo 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

Um exemplo de CI

Uma etapa que pede ao agente para fazer a suíte passar e faz o job falhar quando ele retorna diferente de 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

Instruções e configurações do projeto

Execuções headless leem a mesma configuração que as interativas:

  • O AGENTS.md (ou CLAUDE.md) na raiz do repositório é carregado no prompt de sistema, para que as execuções de CI sigam as regras do seu projeto.
  • As configurações globais ficam em ~/.icode-agent/settings.json e podem ser substituídas por projeto em .icode-agent/settings.json.
  • Modelos de prompt (.icode-agent/prompts/*.md) e skills (.icode-agent/skills/<name>/SKILL.md) são carregados automaticamente.

Em um runner de CI sem ~/.icode-agent, aponte ICODE_AGENT_CONFIG_DIR para um diretório preparado, para que a configuração do modelo esteja disponível.