Documentation

What is Piko?

Piko creates isolated dev environments for parallel feature work. Each one gets its own worktree, tmux session, and optional Docker containers. No stashing, no branch juggling, only switching.

Install

go install github.com/bearsignals/piko@latest

Quick Start

# Initialize piko in your project
cd ~/projects/myapp
piko init

# Create an isolated environment
piko create feature-auth

# You're now in a tmux session with:
# - A git worktree at .piko/worktrees/feature-auth
# - Containers running (if docker-compose.yml exists)
# - Environment variables set (PIKO_*)

# Later, reattach to the session
piko attach feature-auth

# When done, tear it all down
piko destroy feature-auth

Understanding Modes

Piko auto-detects which mode to use based on your project structure.

Docker Mode

If your project has docker-compose.yml, piko automatically:

Creates an isolated Docker network per environment
Allocates unique ports dynamically
Sets PIKO_DB_PORT for database access

Simple Mode

Without Docker Compose, piko provides:

Git worktrees for code isolation
Tmux sessions for terminal management
Data directories for state isolation
Environment variables for port derivation

Commands

Environment Management

piko init	Initialize piko in the current project
piko create <name>	Create a new environment (worktree + containers + tmux)
piko attach <name>	Attach to an existing environment's tmux session
piko destroy <name>	Tear down environment (removes worktree, stops containers)
piko env ls	List all environments in the current project
piko env run <name>	Execute the `run` script from .piko.yml in an environment

Server & Tools

piko server	Start the web UI and API server
piko doctor	Check system dependencies and hook status
piko project ls	List all registered projects

Claude Code

piko cc init

Set up Claude Code hooks in the current directory

Configuration

Piko works without configuration, but you can create .piko.yml in your project root to hook into the environment lifecycle.

Lifecycle Hooks

setup	Runs once after `piko create`. The environment is ready but your app may need dependencies installed or config files linked.
run	Executed by `piko env run <name>`. Use this to start your dev server with environment-specific settings.

All scripts run inside the worktree directory with PIKO_* environment variables available. See Recipes for practical examples.

Environment Variables

These variables are available in your tmux session and scripts:

PIKO_ENV_NAME	Environment name (e.g., "feature-auth")
PIKO_ENV_ID	Unique integer, useful for port derivation
PIKO_ENV_PATH	Path to the worktree
PIKO_DATA_DIR	Path to data directory for databases, caches
PIKO_ROOT	Project root path
PIKO_DB_PORT	Allocated database port (Docker mode only)

Recipes

Common problems and how to solve them with piko primitives.

Installing Dependencies

Problem

Each new environment needs dependencies installed before you can work.

Solution

Use the setup hook to run install commands once when the environment is created.

# .piko.yml
scripts:
  setup: |
    npm install

Starting Your Dev Server

Problem

You want a consistent way to start your app across environments.

Solution

Define a run script and use piko env run <name>.

# .piko.yml
scripts:
  run: |
    npm run dev

Sharing Config Files

Problem

Secrets and config files live in the project root, but each worktree needs access.

Solution

Symlink shared files from PIKO_ROOT during setup.

# .piko.yml
scripts:
  setup: |
    ln -sf "$PIKO_ROOT/.env.local" .env.local
    ln -sf "$PIKO_ROOT/.env.development" .env.development

Avoiding Port Conflicts

Problem

Multiple environments running simultaneously fight over the same port.

Solution

Use PIKO_ENV_ID to derive unique ports per environment.

# .piko.yml
scripts:
  run: |
    npm run dev -- --port $((3000 + PIKO_ENV_ID))

Or configure it directly in your build tool:

# vite.config.js
export default {
  server: {
    port: 3000 + parseInt(process.env.PIKO_ENV_ID || 0)
  }
}

Isolating Databases

Problem

Environments share the same database, causing data conflicts.

Solution

Use PIKO_DATA_DIR for file-based databases or PIKO_DB_PORT for Docker-managed databases.

# SQLite - each environment gets its own database file
DATABASE_URL=sqlite:${PIKO_DATA_DIR}/dev.db

# Postgres (Docker mode) - piko allocates a unique port
DATABASE_URL=postgres://localhost:${PIKO_DB_PORT}/dev

Full Example

A complete .piko.yml combining multiple recipes:

scripts:
  setup: |
    npm install
    ln -sf "$PIKO_ROOT/.env.local" .env.local
    npx prisma migrate dev

  run: |
    npm run dev -- --port $((3000 + PIKO_ENV_ID))

Web Dashboard

Piko includes a web dashboard for monitoring and managing your environments.

Starting the Server

piko server

This starts the web UI at http://localhost:19876. The dashboard provides:

Overview of all your piko projects and environments
Real-time status of running environments
Quick actions to attach, destroy, or manage environments

Diagnostics

piko doctor

Check system dependencies, server status, and hook configurations across all environments.

Claude Code Integration

Orchestrate and manage your Claude Code agents directly from the piko dashboard instead of the terminal.

How It Works

When Claude Code requests permission (file edit, bash command, etc.), the request appears in the web dashboard where you can approve or deny it. This lets you:

Manage multiple agents across different environments from one place
Review permission requests without switching terminal windows
Keep your terminal free for other work while agents run

How to setup the claude code integration

Run this in each environment before starting Claude Code:

piko cc init

This creates .claude/settings.json with hooks that route notifications to piko. Make sure piko server is running to receive them.