icod 0.1.1

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

icod

icod.ai — a CLI coding agent.

This pip package is a thin launcher for the icod CLI. On first run it downloads the platform-native icod binary, caches it locally, and re-executes that binary on every subsequent invocation.

Install

pip install icod

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, commits it]

❯ ^C    (Ctrl+C to exit)

By default, icod auto-approves every tool call (file reads, edits, shell commands). This matches the Claude Code feel — 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.

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-git	Disable the auto-commit / git review integration
--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

Other commands

There are a handful of helper subcommands:

Command	Purpose
icod chat "..."	One-shot question (sends one message, prints reply, exits)
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 undo / diff / log	Git operations on icod commits
icod init	Generate ICOD.md for the current workspace
icod --help	See everything

Prerequisites

For the best experience, install ripgrep (rg) on your PATH. Some icod tools use it for fast file searches; without it, those tools fall back to slower OS commands and the first call may print a (non-fatal) error.

OS / Package manager	Command
Windows + winget	winget install BurntSushi.ripgrep.MSVC
Windows + Chocolatey	choco install ripgrep
Windows + Scoop	scoop install ripgrep
Windows manual	Download from https://github.com/BurntSushi/ripgrep/releases
macOS + Homebrew	brew install ripgrep
Linux + apt	sudo apt install ripgrep
Linux + dnf	sudo dnf install ripgrep

After installing, open a new terminal so PATH refreshes.

For icod undo / diff / log and git auto-commit features, you also need git on your PATH.

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-workspace session storage: SQLite under .icod/ in each workspace