icod 0.1.3

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.

Tell icod what you want — it reads your code, plans the changes, edits the files, and runs the commands to get it done. Just you and the agent, in the terminal, on your project.

---

Features at a glance

• Agent session — conversational session with full context of your project; keep going until the task is done
• Whole-project awareness — reads, writes, edits, and searches across every file in your repo
• Multi-provider — Anthropic Claude, OpenAI, Google Gemini, Groq, Mistral, OpenRouter, DeepSeek, xAI, Cohere — one tool, every major LLM
• Model catalog with pricing — live vendor and model list from models.dev with per-token cost shown in the picker
• Never lose work — every agent turn is checkpointed; /revert rolls back files, conversation, or both
• Fast file search — ripgrep bundled inside the binary; no separate install needed
• Semantic search — build an embeddings index over your project with icod index for deep cross-file queries
• Auto-approve by default — no per-action prompts slowing you down; opt into review with --no-auto
• Session continuity — resume exactly where you left off with -c or --session
• Workspace init — auto-generates an ICOD.md briefing for the agent on first use
• Cost tracking — /cost and icod stats show token usage and USD spend per session and across all sessions
• Permission rules — define allow/deny patterns in icod.json to tighten or relax what the agent can touch

---

Install

pip install icod

On first run, icod downloads and caches the native binary automatically.

---

Quickstart

Work on your current project

# Navigate to your project, then just run:
icod

icod uses your current working directory as the workspace by default. The agent can see, edit, and run everything inside it.

Point icod at a specific folder

icod --dir C:\repos\my-project

# Short form
icod -d C:\repos\my-project

That's all it takes — no config files required.

First-time setup

The very first time you run icod, it guides you through setup automatically:

1. Pick a provider — an arrow-key menu lists every supported vendor:

     Provider
   
   ❯ Anthropic
     Google Gemini
     Groq
     Mistral
     OpenAI
     OpenRouter
     …
   

2. Pick a model — the list for that vendor appears with live per-token pricing.
3. Enter your API key — hidden prompt; saved once to ~/.icod/credentials.json.

From then on, icod drops straight into the agent session. No setup screen again.

---

Agent session

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 reads the project, explains what it found]

❯ add input validation to the registration endpoint
[agent edits the relevant files]

❯ also write a test for it
[agent adds the test]

❯ /cost
  Total: $0.023   input 18,400   output 1,250

❯ ^C

The agent session keeps a live conversation thread with full project context. The agent remembers what it did in previous turns — just keep talking.

By default every tool call (read, write, shell command) is auto-approved. Pass --no-auto to confirm each action manually:

icod --no-auto

---

Multi-provider support

Switch provider with the interactive command-line picker or pass flags directly:

# Interactive: arrow-key vendor → model → API key
icod provider

# Inline flags
icod --provider openai --model gpt-4o
icod --provider google --model gemini-1.5-pro
icod --provider groq   --model llama-3.3-70b-versatile
icod --provider mistral --model mistral-large-latest

# Switch mid-session (no restart needed)
# type inside the agent session:
/provider

Supported providers: Anthropic, OpenAI, Google Gemini, Groq, Mistral, OpenRouter, DeepSeek, xAI, Cohere — and any other backend litellm supports.

API keys are stored per-vendor in ~/.icod/credentials.json. Each vendor also reads from its standard environment variable as an override:

Vendor	Environment variable
anthropic	ANTHROPIC_API_KEY
openai	OPENAI_API_KEY
google	GEMINI_API_KEY
openrouter	OPENROUTER_API_KEY
groq	GROQ_API_KEY
mistral	MISTRAL_API_KEY
deepseek	DEEPSEEK_API_KEY
xai	XAI_API_KEY
cohere	COHERE_API_KEY

---

Revert agent changes

icod checkpoints your files before every turn. Use /revert inside the agent session to undo:

❯ 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

Command	What it does
/revert	Interactive two-step wizard: pick a checkpoint, pick what to restore
/revert <N>	Undo back to turn N — files + conversation
/revert <N> code	Restore only the files; leave the conversation intact
/revert <N> chat	Drop only the conversation back to turn N; leave files as they are

Checkpoints are stored in ~/.icod/snapshots/ and never touch your project's git history. Requires git on your PATH — icod tells you if it isn't available.

---

Flags

Flag	What it does
--dir <path> / -d <path>	Workspace folder to use (default: current directory)
--provider <vendor> / -p <vendor>	LLM vendor: anthropic, openai, google, groq, …
--model <name> / -m <name>	Model to use: claude-opus-4-7, gpt-4o, gemini-1.5-pro, …
--no-auto	Ask y/N before each tool call
--continue / -c	Resume the most recent session in this folder
--session <id> / -s <id>	Resume a specific session by ID
--file <path> / -f <path>	Run a one-shot task from a file, then exit
--thinking	Stream the model's reasoning steps inline
--no-init	Skip ICOD.md auto-generation
--verbose / -v	Debug logging — helpful for bug reports
--help	Full flag list

---

Agent session commands

Command	Purpose
/provider	Switch provider and model for this session (arrow-key picker)
/model [name]	Switch model inline — picker if no name given
/models	List available models for the current provider with pricing
/revert [N] [code|chat]	Undo a turn — files, conversation, or both
/cost	Token usage and USD 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 reference
/help	Show this command list
/exit / /quit	Exit the session

---

Subcommands

Run these outside the agent session:

Command	Purpose
icod provider	Interactive vendor + model + key setup
icod login	Save or overwrite an API key
icod logout	Remove a stored API key
icod models	Browse and set a default model
icod stats	Token usage and cost across all sessions
icod session list	Show all saved sessions
icod session delete <id>	Delete a session
icod init	Generate ICOD.md for the current workspace
icod index	Build or refresh the semantic search index
icod config	Show resolved configuration
icod version	Print icod version

---

Session continuity

icod persists every session. Pick up right where you left off:

# Resume the most recent session in this folder
icod -c

# Resume a specific session by ID
icod --session 01KT8G7WPBFC66GXH182843HT2

# List all sessions
icod session list

---

Workspace configuration

Drop an icod.json (or .icod/config.json) in your project root to set project-level defaults:

{
  "model": "claude-opus-4-7",
  "provider": { "name": "anthropic" },
  "auto_approve": true,
  "permission_rules": [
    { "action": "deny", "tool": "bash", "pattern": "rm -rf" }
  ]
}

Global defaults live in ~/.icod/config.json and are overridden by the project config, which is in turn overridden by CLI flags.

---

Requirements

• Windows x64 (macOS and Linux support planned)
• Python 3.8+ — only needed for the pip launcher; the agent itself is a self-contained binary
• git — optional, enables the /revert checkpoint system; icod works fine without it

---

Storage

Path	Contents
~/.icod/bin/	Cached native binary
~/.icod/credentials.json	API keys (one per vendor)
~/.icod/config.json	Global provider / model defaults
~/.icod/snapshots/	Per-session revert checkpoints
.icod/ in each workspace	Session database (SQLite)