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/ + examples/python/fallback_chain.py). See GOALS.md for the why.

Install

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.

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

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 / always).

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

Development

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