icod 0.1.2

icod.ai — CLI coding agent (pip launcher; downloads the native binary on first run)

icod

A fast, native AI coding agent that lives in your terminal.

Point icod at any project, tell it what you want, and it reads your code, makes the edits, and runs the commands to get it done — right where you already work.

• Native binary — quick startup, no heavy runtime to manage
• Whole-project aware — reads, writes, and runs code across your repo
• Never lose work — every turn is checkpointed; /revert rolls back files, the conversation, or both
• Stays out of your way — auto-approves actions by default (opt into per-step review with --no-auto)

Install

pip install icod

The first time you run icod, it downloads the native binary (~500 MB) and caches it locally — every run after that starts instantly.

First run

cd C:\path\to\your\project
icod

That's the entire first-time setup. You do NOT need to run icod login first — icod asks for your API key automatically the first time it needs one.

Here's what happens behind the scenes when you type icod for the very first time:

1. The launcher downloads the native binary (~500 MB) into ~/.icod/bin/.
2. icod sees there's no API key stored and shows:

   Welcome to icod.  First-time setup:
   Paste your Anthropic API key. It will be saved to C:\Users\<you>\.icod\credentials
   API key: ********
   

3. You paste your Anthropic key (starts with sk-ant-...). Input is hidden for safety.
4. icod saves the key and drops you straight into the REPL.

From the second run onward, just typing icod skips both the download and the key prompt — it goes straight to the REPL.

Note: icod login and icod logout still exist for the rare cases when you want to overwrite an existing key or remove one — but you should never need them for first-time setup.

Daily usage

The interactive REPL is the main way to use icod. Inside it:

PS C:\repos\my-project> icod

  ▲  icōd.ai CLI  │ claude-sonnet-4-6
     session 01KT8G7WPBFC66GXH182843HT2  │  /help  │  ctrl-c

❯ what's in this codebase?
[agent uses tools, explains the project]

❯ add a python script that prints today's date
[agent creates the file]

❯ ^C    (Ctrl+C to exit)

By default, icod auto-approves every tool call (file reads, edits, shell commands) and applies changes directly to your files. Fast, no per-action prompts.

If you'd rather review each action, use --no-auto:

icod --no-auto

icod will then pause and ask approve? [y/N] before each read, write, or shell command.

Rewind / revert changes

icod keeps a per-session checkpoint of your files before each turn, so you can undo the agent's work at any point with the /revert command inside the REPL:

❯ refactor auth.py to use bcrypt
[agent edits auth.py]

❯ actually also add rate limiting
[agent edits 3 more files]

❯ /revert
↶ reverted to before "actually also add rate limiting"
  files restored, that turn dropped from the conversation

/revert understands a few forms:

Command	What it does
/revert	Undo the most recent turn — restore files and drop that turn from the conversation
/revert <N>	Undo back to turn N (everything after N is rolled back)
/revert <N> code	Restore only the files for turn N; leave the conversation intact
/revert <N> chat	Drop only the conversation back to turn N; leave files as they are

Checkpoints live in ~/.icod/snapshots/ and never touch your project's own git history. (Requires git on your PATH — if git isn't installed, /revert is disabled and icod tells you so.)

Useful flags

All flags go directly on icod (no subcommand):

Flag	What it does
--dir <path> / -d <path>	Workspace folder (default: current directory)
--no-auto	Ask before each tool call (instead of auto-approving)
--model <name> / -m <name>	Use a specific Claude model (e.g., claude-opus-4-7)
--continue / -c	Resume the most recent session in this folder
--session <id> / -s <id>	Resume a specific session by ID
--file <path> / -f <path>	Read prompt from a file (runs one-shot, then exits)
--no-init	Skip the ICOD.md auto-generation step
--verbose / -v	Show debug logging — helpful for bug reports
--help	Full list of flags

For example, to point icod at a project elsewhere on disk:

icod --dir C:\repos\some-other-project

To use Opus instead of the default Sonnet:

icod -m claude-opus-4-7

To pick up where you left off in this folder:

icod -c

REPL slash commands

Inside the interactive session:

Command	Purpose
/revert [N] [code|chat]	Undo a turn — files, conversation, or both
/model <name>	Switch model for this session
/models	List available models
/cost	Token usage and cost for this session
/new	Start a fresh session (clears history)
/session	Print the current session ID
/clear	Clear the screen
/commands	Full CLI usage guide
/help	Show the command list
/exit / /quit	Quit the session

Other commands

A handful of helper subcommands (run outside the REPL):

Command	Purpose
icod login	Re-save / overwrite your API key
icod logout	Remove the stored API key
icod models	List available Claude models / pick a default
icod stats	Token usage and cost statistics
icod session list / delete	Manage saved sessions
icod init	Generate ICOD.md for the current workspace
icod index	Build / refresh the semantic search index
icod config	Validate icod.json and show resolved config
icod version	Print version
icod --help	See everything

Requirements

icod is self-contained — ripgrep is bundled inside the binary, so there's nothing to install for fast file search.

The only optional dependency is git, used by the /revert checkpoint system. If git is on your PATH, /revert works. If it isn't, icod runs normally and simply disables /revert (it tells you so). Most developers already have git installed.

Supported platforms

• Windows x64

Other platforms will fail at first run with a clear error. macOS and Linux support is planned.

Configuration

Environment variable	Purpose
ICOD_BINARY_URL	Override the base URL the launcher downloads from
ICOD_BINARY_PATH	Skip the download entirely and use an existing local binary
ICOD_BINARY_VERSION	Pin to a specific binary version
ANTHROPIC_API_KEY	API key (alternative to icod login)

Storage

• Native binary cache: ~/.icod/bin/<version>/icod.exe
• API key: ~/.icod/credentials (created on first run)
• Per-session rewind checkpoints: ~/.icod/snapshots/<session-id>/
• Per-workspace session storage: SQLite under .icod/ in each workspace