pi-container-use

A pi package that routes pi's built-in coding tools through container-use.

What it does

This package overrides pi's built-in coding tools so file and shell actions run inside a Container Use environment instead of directly on the host machine.

Overridden tools:

• bash
• read
• write
• edit
• ls
• find
• grep
• user ! shell commands

It also adds these slash commands:

• /container-use — show the active and recent Container Use environments for the current pi session
• /container-use-switch <env-id> — switch to a recent compatible Container Use environment
• /container-use-new [title] — create a fresh Container Use environment for the current pi session

Requirements

• container-use installed and available in PATH
• a git repository as the working directory
• pi 0.75.5 or newer recommended

Install container-use:

# macOS
brew install dagger/tap/container-use

# all platforms
curl -fsSL https://raw.githubusercontent.com/dagger/container-use/main/install.sh | bash

Install as a pi package

From a local checkout

pi install .

From npm

pi install npm:@morenol/pi-container-use

From git

pi install git:github.com/OWNER/pi-container-use

Usage

After installing the package, start pi in a git repository and work normally. The extension will create or reopen a single-tenant Container Use environment and route tool calls through it.

The pi status bar shows the active Container Use environment as CU: <env-id>, with extra markers such as img, df, or warn when relevant.

User ! shell commands also include a visible header in their output showing the active environment id.

Use the container-use CLI on the host with the environment id shown by /container-use.

If you want to move between recent environments inside pi, use /container-use-switch <env-id>. For safety, switching is only allowed to environments created with the same active Container Use configuration.

Useful commands include:

• container-use log <env-id>
• container-use diff <env-id>
• container-use checkout <env-id>

Custom image or Dockerfile

You can configure the environment used for new Container Use sessions in any of these ways:

1. environment variables
2. .pi-container-use.json in the repo root
3. package.json config

Precedence is:

• PI_CONTAINER_USE_* environment variables
• .pi-container-use.json
• package.json

Environment variables

export PI_CONTAINER_USE_IMAGE=ghcr.io/OWNER/IMAGE:TAG

Or with a Dockerfile:

export PI_CONTAINER_USE_DOCKERFILE=.devcontainer/Dockerfile
export PI_CONTAINER_USE_CONTEXT=.

.pi-container-use.json

Use either an image:

{
  "image": "ghcr.io/OWNER/IMAGE:TAG"
}

Or a Dockerfile:

{
  "dockerfile": ".devcontainer/Dockerfile",
  "context": "."
}

package.json

{
  "pi": {
    "containerUse": {
      "image": "ghcr.io/OWNER/IMAGE:TAG"
    }
  }
}

Or:

{
  "pi": {
    "containerUse": {
      "dockerfile": ".devcontainer/Dockerfile",
      "context": "."
    }
  }
}

Notes:

• Configure either image or dockerfile, not both.
• context defaults to . when dockerfile is set.
• dockerfile and context must stay inside the current repository.
• If you change the configuration, create a fresh environment with /container-use-new.
• This package inspects the installed container-use MCP schema and passes supported image/dockerfile fields to environment_create. If your container-use version does not expose compatible inputs, environment creation will fail with a descriptive error.
• /container-use shows the current environment plus recent persisted environments for the session, so you can see the latest one used.
• /container-use-switch only allows switching to environments with the same configuration signature as the current session.

Notes and limitations

• Paths are restricted to the current project root.
• find and grep prefer fd and rg inside the environment when available, with shell fallbacks when they are not.
• The package depends on the container-use CLI, not just raw Dagger.
• This package currently talks to container-use stdio --single-tenant directly over MCP using the official MCP SDK.

Development

npm install
npm run check
npm run pack:check

For local testing without publishing:

pi install .
# or
pi -e .