iCode Agent · Get started

Install iCode Agent.

One package, one install. iCode Agent runs on Node.js 22 or newer, on Windows, macOS and Linux.

1. Install

Install globally, then run it in any project:

npm install -g @icodehq/icode-agent
cd ~/my-project
icode-agent

Prefer not to install? Run it once with npx @icodehq/icode-agent.

2. Configure a model

On first launch iCode Agent sets up a model before the workspace opens. It speaks the openai and anthropic protocols, so it works with the official APIs and any compatible endpoint.

• Choose an existing configuration or add one: protocol, endpoint, model name, API key.
• A real connection test must pass before anything is saved.
• Configuration is stored locally at ~/.icode-agent/models.json.

Switch models any time with /model or Ctrl+P.

3. Give it a task

Type a task in plain language and press Enter:

Fix the failing tests in this repository.

iCode Agent explores the code, makes changes, runs your commands, and verifies its own work. Watch it live and steer it whenever you want.

Non-interactive use

For scripts and CI:

icode-agent -p "run the tests and report failures"   # print the final response
icode-agent --mode json -p "find TODO comments"      # stream events as JSON lines
icode-agent -c -p "now fix what you found"           # continue the last session

Troubleshooting

• The workspace never opens — no model is active yet. Finish the setup flow, or write ~/.icode-agent/models.json directly.
• A command fails immediately — on Windows, commands run in PowerShell by default; set "shell": "cmd" in settings to use CMD.
• A long task slows down — iCode Agent summarizes older context to keep requests bounded; it will tell you when it does.

Cross-platform compatibility is implemented; automated verification is performed on Linux, and native Windows and macOS verification is pending.

Still stuck? Open an issue.