gouz.dev / paikea
A full-screen TUI CLI agent powered by local LLMs via Docker Model Runner
Star 0
Fork 0
Watch
TypeScript 100%
54 1 6
.github
docs
openspec
src
.gitignore
biome.json
build.ts
bun.lock
index.ts
LICENSE
package.json
README.md
tsconfig.json
README.md

πŸ„ Paikea #

A full-screen TUI CLI agent powered by local LLMs via Docker Model Runner.

paikea

The name. In Māori tradition, Paikea is the whale rider β€” an ancestor who, thrown into the ocean, survived by riding a whale to shore. The name sets the tone for the whole tool: an ocean voyage you steer, hence the πŸ„ masthead, the marine themes, and the nautical vocabulary throughout ("cast off", "calm seas", the workflow frise).

Documentation #

Full docs live in docs/, organized with the DiΓ‘taxis framework:

Features #

  • Full-screen TUI β€” React/Ink components with flexbox layout
  • Local LLMs β€” streams via Docker Model Runner (OpenAI-compatible API at localhost:12434)
  • Model switching β€” Tab / Shift+Tab cycles through available models, or M to pick from a list
  • Marine themes β€” five ocean palettes (deep-sea, dawn, storm, lagoon, polar-night) with nautical iconography, switchable from the command palette
  • Thinking support β€” detects and renders chain-of-thought from Qwen3, DeepSeek-R1, OpenAI o-series
  • Markdown rendering β€” responses render inline emphasis (bold, italic, code) as well as headings, bullets, and code blocks, while leaving fenced code untouched
  • OpenSpec integration β€” detects discuss β†’ proposal β†’ design β†’ specs β†’ tasks β†’ apply β†’ archive workflow
  • Git workflow β€” the openspec-git skill ties git to the lifecycle: a feat/<name> branch on proposal, a commit per finished task, and a merge into main on archive
  • Skills & rules β€” loads from bundled defaults + .paikea/ + .claude/ project overrides
  • Session persistence β€” saves conversation history to .paikea/sessions/
  • Project scaffolding β€” paikea init creates a full dev environment with a git repo, devcontainer, OpenSpec, an Obsidian vault, and DiΓ‘taxis docs
  • DiΓ‘taxis docs β€” paikea doc generates tutorials, how-to, reference, and explanation documentation
  • Single binary β€” compiles to a self-contained executable via bun build --compile

Configuration #

paikea reads ~/.paikea/config.json. All fields are optional:

{
  "theme": "deep-sea",
  "dmrScheme": "http",
  "dmrHost": "localhost",
  "dmrPort": 12434,
  "thinking": false
}
Field Default Description
theme terminal-detected Active marine theme (see below)
dmrScheme http Scheme of the Docker Model Runner API. Only https overrides the default.
dmrHost localhost Host of the DMR API (hostname or IP, no scheme). A blank value falls back to the default.
dmrPort 12434 Port of the DMR API. An out-of-range or non-integer value falls back to the default.
thinking false Whether thinking-capable models reason before answering. Left off for faster, direct responses; set true (or toggle from Ctrl+P) to re-enable chain-of-thought.

The scheme/host/port form the base URL <scheme>://<host>:<port>/engines/v1 β€” point paikea at a remote or containerised runner by setting these.

Speed & context #

Responses are gated by two things on small local models: prompt-eval time (how many tokens the model must read every turn) and the model's context window. paikea keeps the system prompt small β€” skill instructions are loaded on demand via the read_skill tool rather than injected in full β€” and leaves model reasoning off by default (thinking: false). The context window itself is fixed when Docker Model Runner loads the model; raise it with:

docker model configure <model> --context-size 16384

Prerequisites #

  • Docker Desktop with Model Runner enabled
  • At least one model pulled (e.g. ai/qwen3)
  • Bun (v1.3+) β€” only to build from source (not needed for the Homebrew install)
  • (optional) OpenSpec CLI β€” npm i -g @fission-ai/openspec β€” to drive the workflow frise. Without it, paikea runs as a plain chat with a single Discuss step.

Install #

brew install gouz/tools/paikea

This installs the prebuilt paikea binary and puts it on your PATH. Upgrade later with brew upgrade gouz/tools/paikea.

From source #

bun install          # install dependencies
bun run build        # compile to dist/paikea

Development #

bun run dev          # run in development mode
bun run build        # compile to dist/paikea
bun run check        # typecheck + lint + test
bun run lint         # biome check
bun run lint:fix     # biome check --write
bun run format       # biome format --write
bun run test         # run tests

Usage #

Interactive TUI #

paikea

Keyboard shortcuts #

Key Action
Enter Submit prompt
Escape Cancel generation (while streaming) Β· Quit (when idle)
Ctrl+C / Ctrl+D Cancel generation, or quit
Tab Accept suggestion, or next model when there is none
Shift+Tab Previous model
Ctrl+P Open command palette (models, themes, steps…)
/discuss, /proposal, /design, /specs, /tasks, /apply, /archive Switch OpenSpec step β€” type the command (Tab autocompletes) and press Enter. A unique prefix works too (/pro β†’ proposal).
Alt+←/Alt+β†’ Previous / next OpenSpec step (if your terminal forwards Alt+arrows)
←/β†’ Move cursor in prompt
Home/End Β· Ctrl+A/Ctrl+E Jump to start/end of prompt
Ctrl+W / Ctrl+U Delete previous word / to line start
↑/↓ Β· PageUp/PageDown Β· Shift+↑/Shift+↓ Scroll the focused pane (anchored to the latest output)
Ctrl+T Switch scroll focus between the thinking and response panes

The workflow frise is read from the OpenSpec CLI: Discuss (a free-form step that never touches OpenSpec) followed by the active change's real artifacts (Proposal β†’ Design β†’ Specs β†’ Tasks, from openspec status), then Apply (task implementation progress) and Archive. paikea tracks the most recently modified in-progress change; if the CLI isn't installed or the repo isn't an OpenSpec project, only the Discuss step is shown.

The selected step drives the session: prompt suggestions, the step-matching openspec-* skills injected into the system prompt, and step-specific guidance (openspec new change, openspec validate, openspec archive…). It defaults to the current step and refreshes after each turn.

Initialize a project #

paikea init

Creates a new directory with:

  • Project structure β€” src/, package.json, README.md, .gitignore
  • Devcontainer β€” Dockerfile + docker-compose.yml + devcontainer.json
  • OpenSpec β€” openspec/changes/, openspec/specs/ directories
  • Obsidian vault β€” .paikea/vault/ with index.md + logs/, skills/, rules/, specs/, templates/, openable with obsidian .paikea/vault
  • Skills β€” .paikea/skills/: obsidian-cli, openspec-git, conventional-commits…
  • Rules β€” .paikea/rules/: obsidian link conventions, devcontainer…
  • AGENTS.md β€” workflow rules and vault conventions
  • Docs β€” DiΓ‘taxis documentation scaffold under docs/
  • Git repository β€” git init on branch main + an initial commit of the scaffold (skipped if already a repo)

See CLI reference β€” paikea init for the full vault layout.

Generate documentation #

paikea doc                    # generate docs in ./docs
paikea doc -o ./my-docs       # custom output directory
paikea doc -s src             # scope to src/ only

Architecture #

src/
β”œβ”€β”€ cli/
β”‚   β”œβ”€β”€ index.ts              # CLI entry (clipse)
β”‚   β”œβ”€β”€ commands/
β”‚   β”‚   β”œβ”€β”€ init.ts           # paikea init
β”‚   β”‚   β”œβ”€β”€ doc.ts            # paikea doc
β”‚   β”‚   └── run.ts            # paikea (TUI)
β”‚   └── prompts/
β”‚       └── stack-questions.ts # init wizard (language, framework, db, services)
β”œβ”€β”€ tui/
β”‚   β”œβ”€β”€ index.tsx             # TUI entry (Ink render)
β”‚   β”œβ”€β”€ App.tsx               # Main app component + agent loop
β”‚   β”œβ”€β”€ theme.tsx             # colors, symbols, frise palette
β”‚   └── components/
β”‚       β”œβ”€β”€ Header.tsx        # top bar with logo + model pill
β”‚       β”œβ”€β”€ Timeline.tsx      # OpenSpec step progress
β”‚       β”œβ”€β”€ ThinkingPane.tsx  # chain-of-thought display
β”‚       β”œβ”€β”€ AgentSteps.tsx    # tool call/result visualization
β”‚       β”œβ”€β”€ ResultPane.tsx    # LLM response rendering
β”‚       β”œβ”€β”€ PromptInput.tsx   # text input with suggestions
β”‚       β”œβ”€β”€ StatusBar.tsx     # bottom bar (tokens, toolbar)
β”‚       └── CommandPalette.tsx # action palette overlay
β”œβ”€β”€ services/
β”‚   β”œβ”€β”€ dmr-client.ts         # Docker Model Runner API (SSE streaming)
β”‚   β”œβ”€β”€ model-registry.ts     # model fetching + cycling
β”‚   β”œβ”€β”€ thinking-parser.ts    # thinking model detection
β”‚   β”œβ”€β”€ openspec-hook.ts      # OpenSpec step detection
β”‚   β”œβ”€β”€ devcontainer.ts       # Dockerfile/compose/devcontainer generation
β”‚   β”œβ”€β”€ project-scaffold.ts   # directory + file scaffolding
β”‚   └── doc-generator.ts      # DiΓ‘taxis doc generation
β”œβ”€β”€ skills/
β”‚   └── registry.ts           # loads SKILL.md from subdirectories
β”œβ”€β”€ rules/
β”‚   └── registry.ts           # loads *.md rule files
β”œβ”€β”€ state/
β”‚   └── session.ts            # session save/load
└── types.ts                  # shared types

Stack #

Layer Library
CLI parser clipse
Interactive prompts @clack/prompts
TUI rendering Ink + TermUI
LLM backend Docker Model Runner
Linter/formatter Biome
Runtime Bun

License #

MIT