# Isolated Pi instance

This directory is the user/config directory for an isolated [Pi coding agent](https://pi.dev) instance. The `launch` script sets `PI_CODING_AGENT_DIR` to this directory before invoking the installed `pi` executable.

## Start Pi

From this directory:

```bash
./launch
```

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

```bash
/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:

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

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

```bash
export PI_CODING_AGENT_DIR="$PWD"
```

## Authenticate and configure

```text
/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:

```bash
./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.