niko

A Ralph-style Codex loop CLI that iterates codex exec with checkpoints, changelogs, and configurable limits.

Overview

niko runs your AI coding agent (Codex or Claude) in a self-referential loop, similar to the Ralph Wiggum technique. Each iteration:

1. Runs verification commands (tests, typecheck, lint)
2. Runs the agent with a stable prompt
3. Creates a checkpoint with artifacts
4. Runs a review step to catch bugs and shortcuts
5. Stops when done or limits are reached

Memory persists through repo files, git history, and the .niko/ directory.

Prerequisites

• Bun runtime
• At least one of:
  • Codex CLI installed and configured
  • Claude Code CLI installed and configured
• Git (optional, for auto-commit and diff snapshots)

Installation

From npm (recommended)

# Run without installing
npx niko-ai run
# or with bun
bunx niko-ai run

# Global install
npm install -g niko-ai
# or with bun
bun add -g niko-ai

# Then run from anywhere
niko run

Note: The package is published as niko-ai but installs the niko command.

From source

git clone <repo-url>
cd niko
bun install
bun link

Now you can run niko from any directory.

Quick Start

cd /path/to/your/project

# Just run - the wizard handles everything!
niko run

The interactive wizard will:

1. Create a session (or select an existing one)
2. Offer to generate a PRD from your project description
3. Configure model, iterations, verify commands, etc.
4. Start the run

Or use the CLI directly:

niko init                                    # Initialize .niko/
niko prd --desc "Build a REST API for todos" # Generate PRD
niko run --max-iterations 25                 # Run the loop

Commands

| Command | Description | |---------|-------------| | niko run | Run the iteration loop | | niko resume | Continue an interrupted run | | niko prd | Generate PRD from description | | niko status | Show story status | | niko init | Create .niko/ directory | | niko clean | Remove old checkpoints/sessions |

Common Flags

niko run --session feature        # Named session
niko run --max-iterations 50      # Override limits
niko run --quiet                  # Suppress output
niko run --no-review              # Skip review step
niko resume --more-iterations 10  # Continue with more iterations

See the CLI Reference for all options.

Sessions

niko supports named sessions for running multiple independent projects:

niko prd --desc "Build auth" --session auth
niko run --session auth
niko status --session auth

Each session has its own PRD, progress log, and checkpoints.

Configuration

Configure via .niko/config.json:

{
  "roles": {
    "execution": { "provider": "codex", "model": "gpt-5.2-codex" },
    "review": { "provider": "codex", "model": "gpt-5.2-codex" }
  },
  "maxIterations": 20,
  "verify": { "commands": ["bun test", "bun run typecheck"] }
}

Mix providers: use Codex for execution and Claude for review, or vice versa.

Documentation

📚 Read the full documentation

• Installation - Prerequisites and setup
• Quickstart - Your first niko session
• Configuration - All config options
• CLI Reference - Complete flag reference
• Cookbook - Common setups and recipes

Development

bun test           # Run tests
bun run typecheck  # Type check
bun run lint       # Lint
bun run fmt        # Format

E2E Tests

Opt-in end-to-end tests with real LLM providers:

NIKO_E2E=1 bun test tests/e2e/codex-smoke.test.ts
NIKO_E2E_CLAUDE=1 bun test tests/e2e/claude-smoke.test.ts

License

MIT