68 lines
2.5 KiB
Markdown
68 lines
2.5 KiB
Markdown
# 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.
|