An interactive AI agent in your terminal — like Claude Code.
One-liner (recommended — no Python needed):
curl -fsSL https://raw.githubusercontent.com/PaellaAI/paella/main/install.sh | shHomebrew:
brew tap PaellaAI/tap
brew install paellapip (if you already have Python):
pip install paella-aiAll three install the paella command.
Just run paella (or paella chat) to start an interactive session:
paellaOn 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.
| Command / prefix | Description |
|---|---|
/help |
show available commands |
/model [name] |
switch model (Claude/OpenAI); no name opens a picker |
/clear |
reset the context window |
/copy |
copy the last reply to the clipboard |
/compact |
summarize older turns to shrink context |
/tools |
list the tools the agent can call |
/exit, /quit |
leave (or exit, or ctrl+c twice) |
!<cmd> |
run a shell command directly |
@<path> |
attach a file (opens a file picker) |
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).
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).
paella --version
paella config set|get|list|pathThis 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 suiteuv build # produces wheel + sdist in dist/
uv publish # upload to PyPIMIT