pi-gitbox

A Pi Coding Agent extension that automatically redirects gitignored files and directories into an isolated gitbox — a local impersonation layer that makes them accessible to the AI agent without exposing your secrets. ("gitbox" is a portmanteau of "git" + "sandbox".)

⚠️ DISCLAIMER: This extension uses best-effort impersonation of gitignored paths. It is your responsibility to verify that secrets are not exposed to the agent. If absolute isolation is required, consider using a local model, bubblewrap, or a fully isolated environment.

Security considerations

After enabling gitbox, verify that impersonations are working correctly:

1. Check impersonated files — Open ~/.pi/agent/gitbox/<project>/ and confirm that gitignored files contain a single space (or {} for .json files).
2. Test with a local model — Ask the agent to read a known-secret file. It should report the file as empty (or {} if JSON), confirming the impersonation is active.

Features

• Gitignored file impersonation — gitignored files and directories are automatically mirrored into a private gitbox directory
• Command & path interception — bash commands and file operations (read, edit, write, find, grep, ls) are internally redirected to the impersonated paths
• Directory access control — restricts agent access to allowed directories by default; prompts for approval when accessing paths outside the allowed list
• Configurable directory bypass — optionally disable directory restrictions
• Status bar indicators — color-coded status showing whether the gitbox is enabled, available, not required, unavailable or bypassed
• Auto cleanup — optionally delete the gitbox when the session exits

Status Bar

The status bar displays 📦 Gitbox: followed by the current status:

| Status | Meaning | Color | | ------------ | ----------------------------------------------- | ------------------ | | Enabled | Gitbox active — gitignored paths exist | #00ff88 (green) | | Available | Gitbox created but no gitignored paths detected | #ffaa00 (orange) | | Not required | Current directory is not a git repository | #ff8800 (orange) | | Unavailable | git command not found | #ff4444 (red) | | Bypassed | Impersonation disabled by configuration | #44ddff (cyan) |

When bypassPaths is enabled, the status bar appends (unrestricted) to indicate that directory access restrictions are disabled.

Installation

This package is a Pi extension. Install it with

npm install pi-gitbox

or

pi install https://github.com/gsanhueza/pi-gitbox

Configuration

You can customize Gitbox options via the interactive menu (/gitbox) for common settings, or by adding a gitbox section to your ~/.pi/agent/settings.json for all options:

{
  "gitbox": {
    "baseDir": "~/.pi/agent/gitbox",
    "statusBar": true,
    "deleteOnExit": false,
    "bypassGitbox": false,
    "bypassPaths": false,
    "allowedPaths": []
  }
}

Configuration Options

| Option | Type | Default | Description | | -------------- | -------- | -------------------- | ----------------------------------------- | | baseDir | string | ~/.pi/agent/gitbox | Base directory where gitboxes are created | | statusBar | boolean | true | Show gitbox status in the status bar | | deleteOnExit | boolean | false | Delete the gitbox when the session exits | | bypassGitbox | boolean | false | Skip impersonation of gitignored paths | | bypassPaths | boolean | false | Bypass path access restrictions entirely | | allowedPaths | string[] | [] | Additional paths to allow access to |

Note: The interactive menu (/gitbox) exposes statusBar, deleteOnExit, bypassGitbox, and bypassPaths. The remaining options (baseDir, allowedPaths) must be configured directly in settings.json.

Directory Access

By default, the extension allows access to:

• The current working directory (process.cwd())
• The Pi agent directory (~/.pi/agent)
• The extension package directory
• /dev/null

If the agent attempts to access a path outside these allowed directories, a confirmation dialog appears:

[pi-gitbox]: Allow "/some/path" to be accessed?

Options:

• Allow — Access the path for this session
• Deny — Block access
• Bypass (session only) — Add the path to allowed paths for this session
• Bypass (saved globally) — Add the path to allowed paths permanently

Set bypassPaths: true to skip this check entirely.

Note: When Pi doesn't have access to a UI, access will be automatically blocked.

Commands

| Command | Description | | --------------- | ------------------------------------------------- | | /gitbox | Open settings menu — configure gitbox options | | /gitbox paths | Show impersonated paths (source → target mapping) |

How It Works

1. Session Start — On session_start, the extension checks whether the current directory is a git repository with git available
2. Gitignored Path Detection — Uses git-specific commands to discover all gitignored files and directories
3. Gitbox Creation — If the directory is a git repository, creates a private directory at ~/.pi/agent/gitbox/<project-name> and mirrors gitignored paths into it: files get placeholder content ({} for .json and (empty space) for others)
4. Path Mapping — Builds a mapper from original absolute paths to their impersonated counterparts
5. Event Interception — On every tool_call event:
   • Bash commands — Extracts paths from the command using shell-quote, checks directory restrictions, then rewrites paths to their impersonated versions
   • Path-based tools (read, edit, write, find, grep, ls) — Checks directory restrictions, then resolves the path to its impersonated equivalent
   • Dynamic fallback — If a path wasn't detected during initialization, the extension performs a real-time git check-ignore lookup and creates the impersonation on the fly
6. Status Bar — Updates the status bar with the current gitbox state (enabled, available, not required, or unavailable)
7. Session Shutdown — Optionally removes the gitbox directory if deleteOnExit is enabled

Dependencies

| Peer dependency | Purpose | | --------------------------------- | ------------------- | | @earendil-works/pi-coding-agent | Pi Coding Agent SDK | | @earendil-works/pi-tui | Pi TUI SDK |

| Dependency | Purpose | | ------------- | ------------------- | | shell-quote | Parse bash commands |