kimiko-agent/README.md

Isolated Pi instance

This directory is the user/config directory for an isolated Pi coding agent instance. The launch script sets PI_CODING_AGENT_DIR to this directory before invoking the installed pi executable.

Start Pi

From this directory:

./launch

The launcher is relocatable and can be called while working in another project:

/path/to/kimiko-agent/launch

Pi keeps that project's working directory while storing this instance's credentials, settings, sessions, packages, and global resources here. The launcher also passes --no-builtin-tools, so Pi starts without the built-in read, bash, edit, or write tools while retaining tools registered by extensions.

To use the environment variable directly instead:

export PI_CODING_AGENT_DIR="$(pwd -P)"
pi

To make the setting directory-local with direnv, create an untracked .envrc containing:

export PI_CODING_AGENT_DIR="$PWD"

Authenticate and configure

/login       Manage credentials; writes auth.json here
/settings    Change common settings
/model       Select a model

Or use provider API-key environment variables before starting Pi. auth.json, trust decisions, sessions, generated model metadata, and installed package contents are intentionally ignored by Git.

Layout

• settings.json — instance-wide Pi settings
• models.json — custom providers/models
• keybindings.json — keybinding overrides
• extensions/ — global extensions for this instance
• skills/ — global skills for this instance
• prompts/ — global prompt templates for this instance
• themes/ — global themes for this instance
• sessions/ — generated conversation history
• npm/, git/ — Pi-managed package installations
• auth.json — generated credentials (secret; never commit)
• trust.json — generated project trust decisions

Install a package into only this instance by using the launcher:

./launch install npm:<package>
./launch list

Isolation boundary

PI_CODING_AGENT_DIR isolates Pi's user config, credentials, sessions, model config, and managed packages from ~/.pi/agent. It is not an OS sandbox. Pi can still use inherited environment variables and shell/user configuration, and—when trusted—load project-local .pi resources. Pi also discovers the cross-agent global skill location ~/.agents/skills; use --no-skills when you need to suppress all automatic skill discovery for a run.