Metadata-Version: 2.4
Name: icod
Version: 0.1.2
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.**

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

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

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

To use Opus instead of the default Sonnet:

```powershell
icod -m claude-opus-4-7
```

To pick up where you left off in this folder:

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