A full-screen TUI CLI agent powered by local LLMs via Docker Model Runner
paikea docs tutorials getting-started.md
2.7 kB · 85 lines
Markdown
at main

Getting started #

This tutorial takes you from nothing to a running paikea session and your first OpenSpec change. Follow every step in order; by the end you will have chatted with a local model and switched between workflow steps.

You will need Docker Desktop with Model Runner enabled. To install from source you also need Bun (v1.3+) — the Homebrew install below needs neither.

1. Pull a model #

paikea talks to whatever models Docker Model Runner has loaded. Pull one:

docker model pull ai/qwen3

2. Install and run #

The quickest way is Homebrew, which installs the prebuilt binary:

brew install gouz/tools/paikea
paikea

Prefer to build from source? From the project directory:

bun install
bun run dev

The full-screen interface opens. Along the top you see the masthead (🏄 paikea and the active model), then the workflow frise — a row of steps (Discuss, Proposal, Design, …). At the bottom is the prompt, showing cast off — set a course….

3. Have a conversation #

Type a question and press Enter:

What does this project do?

The response streams into the response pane. Responses are direct by default — the model answers without a visible reasoning step.

4. Turn on reasoning (optional) #

Press Ctrl+P to open the command palette, move to Model Thinking: on with the arrow keys, and press Enter. Ask another question — this time a thinking pane appears above the response and shows the model reasoning before it answers. Press Ctrl+T to move scroll focus to the thinking pane, then ↑/↓ to scroll through it.

Toggle it back off from the palette when you want speed again.

5. Move through the workflow #

The frise mirrors the OpenSpec lifecycle. Switch to a step by typing a slash command. Type / and watch the suggestion appear; press Tab to complete /proposal, then Enter:

/proposal

The selected step in the frise moves to Proposal, and the status bar shows cap proposal. Nothing was sent to the model — a slash command only changes the step, which in turn changes the prompt suggestions and the guidance paikea gives the model. Try /discuss to go back.

6. Quit #

Press Esc once (paikea asks you to confirm), then Esc again.

Where to go next #