Metadata-Version: 2.4
Name: kittykode
Version: 0.1.0
Summary: A kawaii terminal coding agent that runs on free model tiers.
Author: Chimi the Creator
License: MIT
Project-URL: Homepage, https://github.com/Chimthuwu/kittykode
Project-URL: Repository, https://github.com/Chimthuwu/kittykode
Project-URL: Issues, https://github.com/Chimthuwu/kittykode/issues
Keywords: ai,agent,cli,coding-assistant,llm,free-tier,openrouter
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.0
Requires-Dist: prompt_toolkit>=3.0
Dynamic: license-file

# KittyKode 🐾

```
       ✧･ﾟ: *✧･ﾟ:* KittyKode v1   *:･ﾟ✧*:･ﾟ✧
             ♡  By Chimi the Creator!!  ♡
```

**A kawaii terminal coding agent that runs entirely on free model tiers** — and
doesn't fall over the first time it hits a quota wall.

KittyKode is the cute front door on top of a serious resilience layer: a
verified fallback chain of free models with key rotation, provider failover, and
failure classification (that's [`freeagent/`](freeagent/README.md) +
[`examples/python/fallback_chain.py`](examples/python/fallback_chain.py)). See
[`GOALS.md`](GOALS.md) for the *why*.

---

## Install

```bash
uvx kittykode              # try it now, nothing installed
# — or keep it around —
pipx install kittykode     # (or: uv tool install kittykode)
```

The first run walks you through **setup**: paste a free key (no card) for any
providers you have — OpenRouter, Groq, Google AI Studio, Cerebras, Mistral.
**Each key is one independent quota bucket**; when one runs dry, kitty hops to
the next. Keys are saved to `~/.kittykode/.env` and work from any directory.

```bash
kitty                       # open the interface
kitty setup                 # add / replace provider keys any time
kitty setup --all           # also offer NVIDIA, Cohere
kitty --task "explain scripts/discover_free_models.py"   # one task, then exit
kitty --cwd path/to/project # work somewhere else
kitty --yes                 # auto-approve every action (headless)
```

No key at all? `kitty` still opens — the interface works, it just can't run a
model until you finish `kitty setup`.

### From source

```bash
git clone https://github.com/Chimthuwu/kittykode && cd kittykode
pip install -e .
kitty setup
```

## What you see

Banner → welcome box → a status strip (`9 free models across 2 buckets ready`) →
a prompt. Type a coding task; kitty reads, edits, and runs commands with a
kawaii approval screen (a coloured diff for edits, the command for shell runs —
`y` / `n` / `a`lways).

| Command | Does |
|---|---|
| `/help` | the command list |
| `/models` | the fallback chain and which entry is serving |
| `/setup` | add / update provider keys (buckets) |
| `/doctor` | per-entry state: ready / cooling / disabled |
| `/reset` | forget the conversation (chain + approvals stay) |
| `/approvals` | clear remembered "always allow" choices |
| `/quit` | bye bye~ |

When a task is too big for one turn, kitty stops with progress kept — type
`continue` to resume.

## What it inherits from `freeagent`

- **Key rotation** — multiple keys per provider rotate before any model switch
- **Independent buckets** — a second provider's key in `.env` (Groq, Gemini,
  Cerebras…) becomes a chain entry that survives OpenRouter's account-wide
  daily cap
- **Failure classification** — dead models disabled for the session, spent keys
  rotated away from, transient errors napped; empty 200s count as failures
- **Provider-neutral history** — a mid-task switch to another provider just works

Five tools, confined to the working directory: `list_dir`, `read_file`,
`write_file`, `edit_file`, `bash`. Writes/edits/commands need approval;
`--yes` skips that for headless runs.

## Honest limits

- Free tiers are slow and small-context; long histories get trimmed to the most
  recent ~30k tokens.
- If every chain entry shares one quota bucket, a daily cap still stops
  everything — add another provider's key to `.env`.
- Free endpoints may log or train on prompts. **Hobby work only** — never point
  it at credentials or client code.

## Layout

| Path | What |
|---|---|
| `kitty/` | the `kitty` command — `cli.py`, `banner.py`, `ui.py` (kawaii toolkit), `screen.py` (screens/onboarding), `engine.py` (bridge to freeagent) |
| `freeagent/` | the agent engine — tools, agent loop, chain builder |
| `examples/python/fallback_chain.py` | the resilient chain itself |
| `scripts/discover_free_models.py` | probe free models, write `models.json` |
| `models.json` | the current verified chain |
| `TODO.md` | build progress + the channel the build agents coordinate through |

## Development

```bash
python -m pytest kitty/tests      # UI + screen tests
python -m kitty --no-banner       # skip the banner while iterating
NO_COLOR=1 python -m kitty        # plain output
```
