Metadata-Version: 2.4
Name: icod
Version: 0.1.3
Summary: icod.ai — CLI coding agent (pip launcher; downloads the native binary on first run)
Author: icod.ai team
License: Proprietary
License-File: LICENSE
Keywords: ai,claude,cli,coding-agent
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# 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

```powershell
# 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

```powershell
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:

```powershell
icod --no-auto
```

---

## Multi-provider support

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

```powershell
# 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:

```powershell
# 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:

```json
{
  "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) |
