p0's native terminal coding agent.
# Peezy CLI
Peezy is a terminal coding agent by [p0 — the AI lab](https://p0.systems). As
of 0.3 it runs its own agent loop end to end: streaming chat with tool
calling, native file/search/shell tools with path confinement and approvals,
session persistence with resume, and a dot-matrix TUI. No third-party agent
binary underneath.
## Install
```bash
npm install -g @p0systems/peezy
peezy
```
Or with Homebrew:
```bash
brew install p0systems/tap/peezy
```
## Quick Start
Sign in with p0 to get free daily usage through the hosted gateway:
```bash
peezy login
peezy "summarize this repo"
```
Headless one-shots (the lane scripts and CI should use):
```bash
peezy run -p "explain @src/config.ts"
peezy run -p "fix the failing test" --json # NDJSON event stream
peezy run -p "add a README" --capture out.jsonl # full trajectory capture
```
## The agent
- **Tools**: `read_file`, `write_file`, `edit_file` (exact search/replace),
`bash` (timeouts + output caps), `list_files`, `grep` (gitignore-aware),
`todo_write`, plus gateway-backed `web_search`, `fetch_url`,
`generate_image`.
- **Approvals**: `--approvals auto|ask|plan`. Default `ask` — writes and
commands prompt first ([y]/[n]/[a]lways). `plan` is read-only exploration.
- **Confinement**: file tools are locked to the working directory (symlink
escapes included). Opt out per-config only.
- **Context**: automatic compaction as the window fills; ctx% in the status
bar.
- **Sessions**: every session is logged to `~/.peezy/sessions/.jsonl`.
`peezy --resume` (or `/resume`) picks up where you left off. Opt out with
`PEEZY_NO_SESSIONS=1` or `peezy config set sessionLogging false`.
- **Project instructions**: a `PEEZY.md` or `AGENTS.md` in your repo root is
read into the system prompt.
## TUI
- `/model [name]` — list or switch models (fuzzy matching)
- `/status` — plan, usage windows, credits
- `/resume`, `/clear`, `/approvals`, `/upgrade`, `/help`, `/quit`
- `esc` interrupts a running turn · `@` mentions files · up-arrow recalls
input history
## Peezy Go
Free login includes daily usage. Peezy Go ($5 first month, then $10/month)
unlocks the full model lineup and much higher rolling limits. `peezy upgrade`
or `/upgrade` opens checkout; when you hit the free limit the TUI shows the
subscribe screen with live pricing.
## Configuration
First run creates `~/.peezy/config.json` (0600). Browser login stores the
gateway key there — do not commit it. 0.2.x configs migrate automatically
(`sandboxMode`/`approvalPolicy` map onto `approvalMode`; old fields are
preserved on disk).
Environment overrides: `PEEZY_API_KEY`, `PEEZY_BASE_URL`, `PEEZY_MODEL`,
`PEEZY_PROVIDER`, `PEEZY_WEB_URL`, `PEEZY_NO_SESSIONS`, `PEEZY_NO_BROWSER`,
plus per-provider keys (`OPENAI_API_KEY`, `OPENROUTER_API_KEY`,
`AI_GATEWAY_API_KEY`, `CUSTOM_OPENAI_API_KEY`).
```bash
peezy config show | path
peezy config use
peezy config set apiKey
peezy providers | models | credits | sessions | tools
```
Built-in providers: `peezy`, `openai`, `openrouter`, `vercel`, `local`,
`custom` — plus any OpenAI-compatible provider from the live Models.dev feed
(`peezy providers` lists what's runnable).
## Development
```bash
npm install
npm run typecheck
npm test
npm run build
npm link && peezy --help
```
Run from source: `npm run dev -- --help`.
## Publishing
```bash
npm run typecheck && npm test && npm run build
npm audit --audit-level=high
npm pack --dry-run
npm publish
npm run release:homebrew # rewrites homebrew/peezy.rb with the published tarball sha
```
## Security
Do not commit `~/.peezy/config.json`, API keys, or `.env` files. Session
JSONL files can contain file contents from your repos — they stay local under
`~/.peezy/sessions/`. See [SECURITY.md](./SECURITY.md).
## License
MIT