Skip to content

Nyia Keeper Quick Start

Get up and running with AI-powered development assistants in under 2 minutes.

Install

Linux

curl -fsSL https://raw.githubusercontent.com/KaizendoFr/nyia-keeper/main/install.sh | bash
export PATH="$HOME/.local/bin:$PATH"

macOS

curl -fsSL https://raw.githubusercontent.com/KaizendoFr/nyia-keeper/main/scripts/install-macos.sh | bash
See macOS Setup Guide for Docker Desktop installation and troubleshooting.

Windows (WSL2)

Run inside a WSL2 terminal (Ubuntu), not PowerShell — Nyia Keeper is a bash + Docker tool. Install Docker Desktop (enable the WSL2 engine + WSL Integration), then in your WSL2 terminal: 

curl -fsSL https://raw.githubusercontent.com/KaizendoFr/nyia-keeper/main/install.sh | bash
export PATH="$HOME/.local/bin:$PATH"
See Windows (WSL2) Setup Guide. (WSL1 is not supported.)

Choose Your Assistant

nyia list                    # Show available assistants

Available options: claude, gemini, codex, opencode, vibe

Setup Authentication

Each assistant requires one-time authentication:

Claude: 

nyia-claude --login          # Follow prompts to authenticate
nyia-claude --status         # Verify setup

Gemini: 

nyia-gemini --login          # OAuth setup

Codex: 

nyia-codex --login           # OAuth (ChatGPT) or --set-api-key for an OpenAI key

OpenCode: 

nyia-opencode --status       # No authentication required

Vibe (Mistral AI): 

export MISTRAL_API_KEY="your-api-key"  # Get key from console.mistral.ai
nyia-vibe --status                      # Verify setup

Start Coding

Navigate to your project directory and start an interactive session:

cd /your/project
nyia-claude                  # Or nyia-gemini, nyia-codex, etc.

Branch Management

By default, Nyia Keeper creates timestamped branches for your work:

nyia-claude                    # Creates: claude-2026-01-11-143052

For named branches:

# Create a named branch
nyia-claude --work-branch feature/my-feature --create

# Resume existing branch
nyia-claude --work-branch feature/my-feature

See docs/BRANCH_MANAGEMENT.md for detailed workflows.

Built-in Skills

All assistants include 12 built-in skills (following the Agent Skills standard), all prefixed nyia- — type /nyia- to list them. Any other slash command is the assistant CLI's own or yours.

Autocomplete tip — in Claude Code, a / at the start of a line matches fuzzily (/ck finds nyia-checkpoint), but a / typed mid-line matches by prefix only: type /nyia- and the list appears. That is the CLI's palette, not Nyia.

Skill Command Purpose
nyia-kickoff /nyia-kickoff Start a session — reconstructs state from .nyiakeeper/ and proposes the next steps
nyia-checkpoint /nyia-checkpoint Save session state before ending or when context runs long
nyia-make-a-plan /nyia-make-a-plan Turn a goal into a phased, resumable plan under .nyiakeeper/plans/
nyia-plan-review /nyia-plan-review Architect-level plan review, round-tripping between assistants
nyia-implement-plan /nyia-implement-plan Execute one plan with pre-flight checks, per-step verification, regression detection
nyia-run-plans /nyia-run-plans Execute several Ready plans in safe parallel batches
nyia-code-review /nyia-code-review Pragmatic, security-first review of the code written for a plan
nyia-plan-status /nyia-plan-status "Where are we?" — a filterable table of plans by status / roadmap label
nyia-show-decisions /nyia-show-decisions The decision trail of a plan — what was decided, by whom, why
nyia-share /nyia-share Promote / demote plans between private and team-shared
nyia-whatsup /nyia-whatsup Team news — read what changed since your last session, or publish an entry
nyia-overlay /nyia-overlay Customize the assistant's Docker image with extra packages or tools

Skills are invoked as slash commands within your assistant session.

These skills read and write execution plans under .nyiakeeper/plans/. From the host shell you can inspect the same store with nyia plans (migrate, status, decisions, …) and nyia todo (the generated plan inventory, refreshed automatically at launch and after each session) — see Plan tracking. nyia itself never runs inside the container: the skills work with the plan files directly (the file contract).

Power User Features

# Custom image overlays
mkdir -p ~/.config/nyiakeeper/claude/overlay
cat > ~/.config/nyiakeeper/claude/overlay/Dockerfile << 'EOF'
FROM ghcr.io/kaizendofr/nyiakeeper-claude:latest
RUN apt-get update && apt-get install -y python3-dev build-essential
EOF

nyia-claude --build-custom-image

Troubleshooting

Docker Issues: 

# Check Docker is running
docker --version
sudo systemctl start docker    # Linux
open -a Docker                  # macOS

Authentication Problems: 

# Reset credentials
rm -rf ~/.config/nyiakeeper/creds/
nyia-claude --login

Permission Errors: 

# Fix Docker permissions (Linux only)
sudo usermod -aG docker $USER
newgrp docker

What's Next?

Runtime distribution - optimized for production deployment