paella

An interactive AI agent in your terminal — like Claude Code.

Installation

One-liner (recommended — no Python needed):

curl -fsSL https://raw.githubusercontent.com/PaellaAI/paella/main/install.sh | sh

Homebrew:

brew install PaellaAI/tap/paella

pip (if you already have Python):

pip install paella-ai

All three install the paella command.

The interactive agent

Just run paella (or paella chat) to start an interactive session:

paella

On a real terminal this opens a full-screen app (scrolling transcript + anchored input). Piped/non-interactive input falls back to a line REPL automatically; force it with paella chat --classic.

You get a streaming chat loop with tool use — the agent can read files, list directories, run shell commands (with your approval), and search the web. Responses render as Markdown with syntax-highlighted code blocks; extended thinking is streamed inline.

Slash commands & prefixes

Models

Run /model for a picker across Claude (Opus 4.8, Fable 5, Sonnet 5, Haiku 4.5) and OpenAI (GPT-5 Codex, GPT-5, o4-mini), or /model <name> to switch directly — the backend is inferred from the id (gpt-*/o* → OpenAI, claude-* → Anthropic; or force with openai:<id>). Switching starts a fresh session.

Set credentials via environment variables or config:

export ANTHROPIC_API_KEY=sk-ant-...     # or: paella config set anthropic_api_key ...
export OPENAI_API_KEY=sk-...            # or: paella config set openai_api_key ...

Config is stored at ~/.config/paella/config.json. Relevant keys: backend, model, anthropic_api_key, openai_api_key, web (default on).

Context compaction

Long sessions are kept from overflowing the model's context window by auto-summarization: when the transcript grows past a threshold, the oldest turns are replaced by a single summary while the most recent turns are kept verbatim. Run /compact to trigger it manually. It rewrites history rarely and in one batch, so the compacted prefix stays cache-friendly. Config keys: compact (default true), compact_threshold_tokens (120000), compact_keep_tokens (40000).

Other commands

paella --version
paella config set|get|list|path

Development

This project uses uv.

uv sync                   # install deps into a local venv
uv run paella             # run the agent from source
uv run pytest             # run the test suite

Building & publishing

uv build                  # produces wheel + sdist in dist/
uv publish                # upload to PyPI

License

MIT