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 5 built-in skills (following the Agent Skills standard):

Skill Command Purpose
kickoff /kickoff Start a session - reconstructs state from .nyiakeeper/ files
make-a-plan /make-a-plan Create a phased execution plan with atomic steps
implement-plan /implement-plan Execute a plan with pre-flight validation, per-step verification, and regression detection
plan-review /plan-review Architect-level plan review between agents (e.g., Claude reviews Codex's plan)
checkpoint /checkpoint Save session state before context compaction or shutdown

Skills are invoked as slash commands within your assistant session.

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