Metadata-Version: 2.4
Name: icod
Version: 0.1.1
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

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

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

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

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