pi-gitbox 0.1.0

package/LICENSE.md

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Gabriel Sanhueza (https://github.com/gsanhueza)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,135 @@
+# pi-gitbox
+
+A [Pi Coding Agent](https://pi.dev/) 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](https://github.com/containers/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 appear as empty placeholders (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
+
+```bash
+npm install pi-gitbox
+```
+
+or
+
+```bash
+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:
+
+```json
+{
+  "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 verifies that `git` is available and checks if the current directory is a git repository
+2. **Gitignored Path Detection** — Uses git-specific commands to discover all gitignored files and directories
+3. **Gitbox Creation** — 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
+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 |

package/index.ts

@@ -0,0 +1,77 @@
+import {
+  ExtensionCommandContext,
+  ExtensionContext,
+  ToolCallEvent,
+  type ExtensionAPI,
+} from "@earendil-works/pi-coding-agent";
+import { CommandManager } from "./src/commands";
+import { BASE_ALLOWED_PATHS } from "./src/defaults";
+import { Detector } from "./src/detector";
+import { Gitbox } from "./src/gitbox";
+import { Impersonator } from "./src/impersonator";
+import { askUserOrBlock } from "./src/prompts";
+import { settings } from "./src/settings";
+
+export default async (pi: ExtensionAPI) => {
+  const impersonator = new Impersonator();
+  const gitbox = new Gitbox(impersonator);
+
+  const commandManager = new CommandManager(gitbox);
+
+  // Command registration
+  pi.registerCommand("gitbox", {
+    description: "Open settings menu to configure Gitbox options",
+    getArgumentCompletions: commandManager.getArgumentCompletions,
+    handler: async (args: string, ctx: ExtensionCommandContext) =>
+      await commandManager.runGitbox(args, ctx),
+  });
+
+  // Events
+  pi.on("session_start", async (_, ctx: ExtensionContext) => {
+    await gitbox.initialize(ctx);
+  });
+
+  pi.on("session_shutdown", async (_, ctx: ExtensionContext) => {
+    await gitbox.shutdown(ctx);
+  });
+
+  pi.on("tool_call", async (event: ToolCallEvent, ctx: ExtensionContext) => {
+    const { config } = await settings.getConfig();
+
+    const resolvedDirs = [...BASE_ALLOWED_PATHS, ...config.allowedPaths];
+
+    if (gitbox.isBashEvent(event)) {
+      const { command } = event.input;
+
+      // First, scan if we can even access the paths
+      if (!config.bypassPaths) {
+        const paths = await impersonator.extractFromCommand(command);
+
+        for (const path of paths) {
+          if (Detector.isPathAllowed(resolvedDirs, path, ctx)) continue;
+
+          const response = await askUserOrBlock(ctx, path);
+          if (response.block) return response;
+        }
+      }
+
+      // Then, impersonate the command
+      if (!config.bypassGitbox)
+        event.input.command = await gitbox.resolveCommand(command, ctx);
+    } else if (gitbox.isPathEvent(event)) {
+      const { path } = event.input as { path: string };
+
+      // First, scan if we can even access the paths
+      if (!config.bypassPaths) {
+        if (!Detector.isPathAllowed(resolvedDirs, path, ctx)) {
+          const response = await askUserOrBlock(ctx, path);
+          if (response.block) return response;
+        }
+      }
+
+      // Then, impersonate the path
+      if (!config.bypassGitbox)
+        event.input.path = await gitbox.resolvePath(path, ctx);
+    }
+  });
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "pi-gitbox",
+  "version": "0.1.0",
+  "description": "Pi extension that impersonates gitignored paths to reduce secrets exposure.",
+  "keywords": [
+    "pi",
+    "pi-package",
+    "pi-extension"
+  ],
+  "author": "Gabriel Sanhueza",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gsanhueza/pi-gitbox.git"
+  },
+  "homepage": "https://github.com/gsanhueza/pi-gitbox#readme",
+  "bugs": {
+    "url": "https://github.com/gsanhueza/pi-gitbox/issues"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "prettier": {
+    "plugins": [
+      "prettier-plugin-organize-imports"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "@types/shell-quote": "^1.7.5",
+    "prettier-plugin-organize-imports": "^4.3.0"
+  },
+  "dependencies": {
+    "shell-quote": "^1.8.4"
+  }
+}

package/src/commands.ts

@@ -0,0 +1,168 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { getSettingsListTheme } from "@earendil-works/pi-coding-agent";
+import {
+  AutocompleteItem,
+  SettingsList,
+  type SettingItem,
+} from "@earendil-works/pi-tui";
+import { GitboxConfig } from "./config-types";
+import { Gitbox } from "./gitbox";
+import { settings } from "./settings";
+
+/**
+ * Configuration options
+ */
+enum Options {
+  STATUS_BAR = "statusBar",
+  DELETE_ON_EXIT = "deleteOnExit",
+  BYPASS_GITBOX = "bypassGitbox",
+  BYPASS_PATHS = "bypassPaths",
+}
+
+/**
+ * Handles commands for the pi-gitbox extension.
+ */
+export class CommandManager {
+  constructor(private readonly gitbox: Gitbox) {}
+
+  /**
+   * Sets up the argument completions for the `/gitbox` command
+   *
+   * @param prefix Prefix written by the user
+   * @returns Completions with that prefix
+   */
+  getArgumentCompletions(prefix: string): AutocompleteItem[] | null {
+    const available = [
+      {
+        value: "paths",
+        label: "paths",
+        description: "Show impersonated paths",
+      },
+    ];
+    const filtered = available.filter((a) => a.value.startsWith(prefix));
+    return filtered.length > 0 ? filtered : null;
+  }
+
+  /**
+   * Handles the `/gitbox` command — opens a SettingsList or shows impersonated paths
+   *
+   * @param args The subcommand argument (e.g. "paths")
+   * @param ctx The extension context
+   */
+  async runGitbox(args: string, ctx: ExtensionCommandContext): Promise<void> {
+    if (args === "paths") {
+      return await this.runGitboxPaths(ctx);
+    }
+
+    const { config } = await settings.getConfig();
+    const items = this.buildSettingsItems(config);
+
+    await ctx.ui.custom<void>((_tui, _theme, _kb, done) =>
+      this.createSettingsList(
+        items,
+        async (id, newValue) => this.handleSettingChange(id, newValue, ctx),
+        done,
+      ),
+    );
+  }
+
+  /**
+   * Handles the `/gitbox paths` subcommand — shows impersonated paths
+   *
+   * @param ctx The extension context
+   */
+  private async runGitboxPaths(ctx: ExtensionCommandContext): Promise<void> {
+    const mapper = this.gitbox.getMapper(ctx);
+
+    const lines = Object.entries(mapper)
+      .map(([source, target]) => `  ${source} -> ${target}`)
+      .join("\n");
+
+    const content = lines
+      ? `Impersonated paths:\n${lines}`
+      : "No impersonated paths available.";
+
+    ctx.ui.notify(content);
+  }
+
+  /**
+   * Handles a settings value change — writes the new value and re-renders.
+   *
+   * @param id The setting identifier
+   * @param newValue The new value to apply
+   * @param ctx The extension command context
+   */
+  private async handleSettingChange(
+    id: string,
+    newValue: string,
+    ctx: ExtensionCommandContext,
+  ): Promise<void> {
+    const key: string = Object.values(Options).find((o) => o === id)!;
+    await settings.setConfig({ [key]: newValue === "on" });
+
+    // Update the status bar with the new status
+    await this.gitbox.setStatus(ctx);
+  }
+
+  /**
+   * Creates the SettingsList for the menu.
+   *
+   * @param items The settings items to display
+   * @param onChange Callback when a setting value changes
+   * @param onClose Callback when the dialog closes
+   * @returns The configured SettingsList instance
+   */
+  private createSettingsList(
+    items: SettingItem[],
+    onChange: (id: string, newValue: string) => void,
+    onClose: () => void,
+  ): SettingsList {
+    return new SettingsList(
+      items,
+      items.length,
+      getSettingsListTheme(),
+      onChange,
+      onClose,
+    );
+  }
+
+  /**
+   * Builds the SettingsList items for the menu.
+   *
+   * @param config The resolved configuration
+   * @returns The array of SettingItem objects
+   */
+  private buildSettingsItems(config: GitboxConfig): SettingItem[] {
+    return [
+      {
+        id: Options.STATUS_BAR,
+        label: "Show in status bar",
+        description: "Shows gitbox status in the status bar",
+        currentValue: config.statusBar ? "on" : "off",
+        values: ["on", "off"],
+      },
+      {
+        id: Options.DELETE_ON_EXIT,
+        label: "Delete on exit",
+        description: "When exiting Pi, delete the gitbox",
+        currentValue: config.deleteOnExit ? "on" : "off",
+        values: ["on", "off"],
+      },
+      {
+        id: Options.BYPASS_GITBOX,
+        label: "Bypass impersonation",
+        description:
+          "Skip impersonation of gitignored paths (keeps original paths)",
+        currentValue: config.bypassGitbox ? "on" : "off",
+        values: ["on", "off"],
+      },
+      {
+        id: Options.BYPASS_PATHS,
+        label: "Bypass directories",
+        description: "Bypass the restrictions on allowed directories",
+        currentValue: config.bypassPaths ? "on" : "off",
+        values: ["on", "off"],
+      },
+    ];
+  }
+}

package/src/config-types.ts

@@ -0,0 +1,23 @@
+/**
+ * Configuration for the pi-gitbox extension.
+ * All fields can be overridden via ~/.pi/agent/settings.json under the "gitbox" key.
+ */
+export interface GitboxConfig {
+  baseDir: string;
+  statusBar: boolean;
+  deleteOnExit: boolean;
+  bypassGitbox: boolean;
+  bypassPaths: boolean;
+  allowedPaths: string[];
+}
+
+/**
+ * Texts for the status bar
+ */
+export enum Status {
+  ENABLED = "Enabled",
+  AVAILABLE = "Available",
+  NOT_REQUIRED = "Not required",
+  UNAVAILABLE = "Unavailable",
+  BYPASSED = "Bypassed",
+}

package/src/defaults.ts

@@ -0,0 +1,55 @@
+import { getAgentDir, getPackageDir } from "@earendil-works/pi-coding-agent";
+import { join } from "node:path";
+
+/**
+ * Identifier for the status bar entry
+ */
+export const STATUS_KEY = "gitbox";
+
+/**
+ * Default base directory for gitboxes
+ */
+export const GITBOX_BASEDIR = join(getAgentDir(), "gitbox");
+
+/**
+ * Whether to add a text in the status bar
+ */
+export const GITBOX_STATUSBAR = true;
+
+/**
+ * Whether to delete the gitbox when the extension exits
+ */
+export const DELETE_ON_EXIT = false;
+
+/**
+ * Default paths that are always allowed.
+ */
+export const BASE_ALLOWED_PATHS: string[] = [
+  // The current working directory
+  process.cwd(),
+
+  // Pi's agent library location,
+  getPackageDir(),
+
+  // User settings
+  getAgentDir(),
+
+  // Common paths
+  "/dev/null",
+];
+
+/**
+ * Allowed paths, configurable by the user
+ * Extra paths can be added via `allowedPaths` in settings.
+ */
+export const ALLOWED_PATHS: string[] = [];
+
+/**
+ * Whether to bypass path restrictions
+ */
+export const BYPASS_PATHS = false;
+
+/**
+ * Whether to bypass impersonation entirely
+ */
+export const BYPASS_GITBOX = false;

package/src/detector.ts

@@ -0,0 +1,131 @@
+import { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { execSync } from "child_process";
+import { access } from "fs/promises";
+import { homedir } from "node:os";
+import { resolve, sep } from "node:path";
+
+export class Detector {
+  /**
+   * Determines if the user has `git` as a usable command
+   *
+   * @returns True if git exists
+   */
+  static isGitAvailable(): boolean {
+    try {
+      execSync("git -v", { stdio: "pipe" });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Determines if the current working directory is a git repository
+   * @returns True if it's a git repo
+   */
+  static isGitProject(): boolean {
+    try {
+      execSync("git rev-parse --is-inside-work-tree", { stdio: "pipe" });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Returns all gitignored files
+   *
+   * @returns Relative paths for files
+   */
+  static getGitignoredFiles = () => {
+    const paths = Detector.getGitignoredPaths();
+
+    return paths.filter((path) => !path.endsWith("/"));
+  };
+
+  /**
+   * Returns all gitignored directories
+   *
+   * @returns Relative paths for directories
+   */
+  static getGitignoredDirectories = () => {
+    const paths = this.getGitignoredPaths();
+
+    return paths.filter((path) => path.endsWith("/"));
+  };
+
+  /**
+   * Runs the git command to get all git-ignored paths (both files and directories).
+   * Returns an array of paths that are ignored by git.
+   *
+   * @returns Array of git-ignored paths (relative to repo root)
+   */
+  private static getGitignoredPaths(): string[] {
+    try {
+      const command =
+        "git ls-files --directory --no-empty-directory --others --ignored --exclude-standard";
+      const output = execSync(command, {
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "ignore"],
+      });
+      const lines = output
+        .trim()
+        .split("\n")
+        .filter((line) => line.length > 0);
+      return lines;
+    } catch (error) {
+      // Silently ignore if not a git repository
+      return [];
+    }
+  }
+
+  /**
+   * Checks if a path exists
+   *
+   * @param path The path to check
+   * @returns True if path exists
+   */
+  static async pathExists(path: string): Promise<boolean> {
+    try {
+      await access(path);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Checks if a path is contained within any of the allowed directories.
+   * The check is recursive: if `/a` is allowed, then `/a/b/c` also passes.
+   *
+   * @param dirs Allowed directories
+   * @param path The path to check (will be resolved relative to cwd)
+   * @param ctx The extension context
+   * @returns True if the path is within at least one allowed directory
+   */
+  static isPathAllowed(
+    dirs: string[],
+    path: string,
+    ctx: ExtensionContext,
+  ): boolean {
+    // Expand ~ to home directory before resolving
+    const normalizedPath = Detector.normalizePath(path);
+    const absPath = resolve(ctx.cwd, normalizedPath);
+    const absDirs = dirs.map((dir) =>
+      resolve(ctx.cwd, Detector.normalizePath(dir)),
+    );
+
+    return absDirs.some(
+      (dir) => absPath === dir || absPath.startsWith(dir + sep),
+    );
+  }
+
+  /**
+   * Normalizes the path when it comes with a tilde (representing HOME)
+   * @param path The path
+   * @returns A normalized path
+   */
+  private static normalizePath(path: string): string {
+    return path.replace(/^~\//g, homedir() + sep);
+  }
+}

package/src/gitbox.ts

@@ -0,0 +1,180 @@
+import {
+  BashToolCallEvent,
+  ExtensionContext,
+  isToolCallEventType,
+  ToolCallEvent,
+} from "@earendil-works/pi-coding-agent";
+import { mkdir, rm } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+import { GitboxConfig, Status } from "./config-types";
+import { Detector } from "./detector";
+import { Impersonator } from "./impersonator";
+import { Renderer } from "./renderer";
+import { settings } from "./settings";
+
+export class Gitbox {
+  constructor(private readonly impersonator: Impersonator) {}
+
+  async initialize(ctx: ExtensionContext) {
+    await this.verifySettings(ctx);
+
+    if (!Detector.isGitAvailable()) {
+      await this.setStatus(ctx);
+      return;
+    }
+
+    await this.impersonator.initialize(ctx);
+    await this.getOrCreate(ctx);
+    await this.setStatus(ctx);
+  }
+
+  async shutdown(ctx: ExtensionContext) {
+    const { config } = await settings.getConfig();
+    const { deleteOnExit } = config;
+
+    if (deleteOnExit) await this.removeGitbox(ctx);
+  }
+
+  /**
+   * Determines if the event is a "bash" tool call
+   * @param event The event
+   * @returns True if "bash" event
+   */
+  isBashEvent(event: ToolCallEvent): event is BashToolCallEvent {
+    return isToolCallEventType("bash", event);
+  }
+
+  /**
+   * Determines if the event is a tool call where "path" exists
+   * @param event The event
+   * @returns True if "path" exists
+   */
+  isPathEvent(event: ToolCallEvent): boolean {
+    const pathTools = ["read", "edit", "write", "find", "grep", "ls"];
+    return pathTools.some((tool) => isToolCallEventType(tool, event));
+  }
+
+  /**
+   * Impersonates the bash command, if possible
+   *
+   * @param cmd The bash command whose paths will be impersonated
+   * @param ctx The extension context
+   * @returns The command with impersonated paths
+   */
+  async resolveCommand(cmd: string, ctx: ExtensionContext): Promise<string> {
+    return await this.impersonator.resolveCommand(cmd, ctx);
+  }
+
+  /**
+   * Impersonates the path, if possible
+   *
+   * @param path The path to be impersonated
+   * @param ctx The extension context
+   * @returns The impersonated path, if available
+   */
+  async resolvePath(path: string, ctx: ExtensionContext): Promise<string> {
+    return await this.impersonator.resolvePath(path, ctx);
+  }
+
+  /**
+   * Returns the mapper used by the impersonator.
+   * Delegates to impersonator instance
+   *
+   * @param ctx The extension context
+   * @returns The source -> target path mapping
+   */
+  getMapper(ctx: ExtensionContext): Record<string, string> {
+    return this.impersonator.getMapper(ctx.cwd);
+  }
+
+  /**
+   * Validates the configuration settings
+   *
+   * @param ctx The extension context
+   * @returns The validated configuration
+   */
+  private async verifySettings(ctx: ExtensionContext): Promise<GitboxConfig> {
+    const { config, errors } = await settings.getConfig();
+    if (errors.length > 0) {
+      const message = ["[pi-gitbox]", ...errors].join("\n");
+      ctx.ui.notify(message, "warning");
+    }
+
+    return config;
+  }
+
+  /**
+   * Creates the base gitbox
+   *
+   * @param ctx The extension context
+   * @returns The path for the gitbox
+   */
+  private async getOrCreate(ctx: ExtensionContext): Promise<string> {
+    const { config } = await settings.getConfig();
+    const { baseDir } = config;
+    const cwd = basename(ctx.cwd);
+
+    const impersonationDir = resolve(baseDir, cwd);
+    if (await Detector.pathExists(impersonationDir)) return impersonationDir;
+
+    try {
+      await mkdir(impersonationDir, { recursive: true });
+      return impersonationDir;
+    } catch (error) {
+      throw new Error(`Failed to create gitbox: ${error}`);
+    }
+  }
+
+  /**
+   * Removes the gitbox
+   *
+   * @param ctx The extension context
+   */
+  private async removeGitbox(ctx: ExtensionContext): Promise<void> {
+    const gitboxPath = await this.getOrCreate(ctx);
+
+    if (!(await Detector.pathExists(gitboxPath))) return;
+    try {
+      await rm(gitboxPath, { recursive: true });
+    } catch (error) {
+      ctx.ui.notify(`Failed to remove gitbox: ${error}`, "error");
+    }
+  }
+
+  /**
+   * Determines the current status of the gitbox based on its existence.
+   *
+   * @returns Status
+   * - "BYPASSED" if bypassGitbox is enabled
+   * - "ENABLED" if the gitbox was created and gitignored paths exist
+   * - "AVAILABLE" if the gitbox was created, but there are no gitignored paths
+   * - "NOT_REQUIRED" if the current working directory is not a git repository
+   * - "UNAVAILABLE" if `git` command is not found
+   */
+  private async getStatus(): Promise<Status> {
+    const { config } = await settings.getConfig();
+    const { bypassGitbox } = config;
+
+    // If bypass mode is enabled, return bypassed status
+    if (bypassGitbox) return Status.BYPASSED;
+
+    if (!Detector.isGitAvailable()) return Status.UNAVAILABLE;
+    if (!Detector.isGitProject()) return Status.NOT_REQUIRED;
+
+    const paths = Detector.getGitignoredFiles();
+    if (paths.length === 0) return Status.AVAILABLE;
+
+    return Status.ENABLED;
+  }
+
+  /**
+   * Sets the current status in the status bar.
+   * No-op if the settings prevent it.
+   *
+   * @param ctx The extension context
+   */
+  async setStatus(ctx: ExtensionContext) {
+    const status = await this.getStatus();
+    await Renderer.setStatus(ctx, status);
+  }
+}

package/src/impersonator.ts

@@ -0,0 +1,264 @@
+import { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { mkdir, writeFile } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { parse } from "shell-quote";
+import { Detector } from "./detector";
+import { settings } from "./settings";
+
+export class Impersonator {
+  private mapper: Record<string, string> = {};
+
+  /**
+   * Fills the mapper with paths that are gitignored
+   *
+   * @param ctx The extension context
+   */
+  async initialize(ctx: ExtensionContext): Promise<void> {
+    this.mapper = {};
+    const { config } = await settings.getConfig();
+
+    await this.initializeDirectories(config.baseDir, ctx);
+    await this.initializeFiles(config.baseDir, ctx);
+  }
+
+  /**
+   * Initializes the mapper for directories
+   *
+   * @param baseDir Gitbox basedir
+   * @param ctx The extension context
+   */
+  private async initializeDirectories(baseDir: string, ctx: ExtensionContext) {
+    const gitignoredDirectories = Detector.getGitignoredDirectories();
+    const projectDir = join(baseDir, basename(ctx.cwd));
+
+    for (const path of gitignoredDirectories) {
+      const impersonation = await this.createDirectory(path, projectDir, ctx);
+      const absPath = resolve(ctx.cwd, path);
+
+      if (impersonation) {
+        this.mapper[absPath] = impersonation;
+      }
+    }
+  }
+
+  /**
+   * Initializes the mapper for files
+   *
+   * @param baseDir Gitbox basedir
+   * @param ctx The extension context
+   */
+  private async initializeFiles(baseDir: string, ctx: ExtensionContext) {
+    const gitignoredFiles = Detector.getGitignoredFiles();
+    const projectDir = join(baseDir, basename(ctx.cwd));
+
+    for (const path of gitignoredFiles) {
+      const impersonation = await this.createFile(path, projectDir, ctx);
+      const absPath = resolve(ctx.cwd, path);
+
+      if (impersonation) {
+        this.mapper[absPath] = impersonation;
+      }
+    }
+  }
+
+  /**
+   * Creates an impersonated directory for a git-ignored path.
+   *
+   * @param relativePath The original path
+   * @param parentDir The parent path to use with relativePath
+   * @param ctx The extension context
+   * @returns Absolute path to impersonated directory
+   */
+  private async createDirectory(
+    relativePath: string,
+    parentDir: string,
+    ctx: ExtensionContext,
+  ): Promise<string> {
+    // Setup the gitbox for the project
+    const impersonatingPath = resolve(parentDir, relativePath);
+
+    // Create directory if it doesn't exist
+    if (!(await Detector.pathExists(impersonatingPath))) {
+      try {
+        await mkdir(impersonatingPath, { recursive: true });
+      } catch (error) {
+        ctx.ui.notify(
+          `Failed to create impersonated directory: ${error}`,
+          "error",
+        );
+        return relativePath;
+      }
+    }
+
+    return impersonatingPath;
+  }
+
+  /**
+   * Creates an impersonated file for a git-ignored path.
+   *
+   * @param relativePath The original path
+   * @param parentDir The parent path to use with relativePath
+   * @param ctx The extension context
+   * @returns Absolute path to impersonated file
+   */
+  private async createFile(
+    relativePath: string,
+    parentDir: string,
+    ctx: ExtensionContext,
+  ): Promise<string> {
+    // Create the impersonated file
+    const content = relativePath.endsWith(".json") ? "{}" : " ";
+
+    // Setup the gitbox for the project
+    const impersonatingPath = resolve(parentDir, relativePath);
+
+    // Create file if it doesn't exist
+    if (!(await Detector.pathExists(impersonatingPath))) {
+      try {
+        // Ensure parent directories exist first
+        const parentDir = resolve(dirname(impersonatingPath));
+        await mkdir(parentDir, { recursive: true });
+
+        await writeFile(impersonatingPath, content);
+      } catch (error) {
+        ctx.ui.notify(`Failed to create impersonated file: ${error}`, "error");
+        return relativePath;
+      }
+    }
+
+    return impersonatingPath;
+  }
+
+  /**
+   * Returns a copy of the current mapper of impersonated paths.
+   * Sources are relative paths from the base directory to the original file/directory.
+   *
+   * @param baseDir The base directory to resolve relative paths against
+   * @returns The source -> target path mapping
+   */
+  getMapper(baseDir: string): Record<string, string> {
+    const result: Record<string, string> = {};
+
+    for (const [absSource, target] of Object.entries(this.mapper)) {
+      result[relative(baseDir, absSource)] = target;
+    }
+
+    return result;
+  }
+
+  /**
+   * Impersonates the bash command, if possible
+   *
+   * @param cmd The bash command whose paths will be impersonated
+   * @param ctx The extension context
+   * @returns The command with impersonated paths
+   */
+  async resolveCommand(cmd: string, ctx: ExtensionContext): Promise<string> {
+    const paths = await this.extractFromCommand(cmd);
+
+    let response = cmd;
+    for (const path of paths) {
+      const impersonation = await this.resolvePath(path, ctx);
+      response = response.replace(path, impersonation);
+    }
+
+    return response;
+  }
+
+  /**
+   * Impersonates the path, if possible
+   *
+   * @param path The path to be impersonated
+   * @param ctx The extension context
+   * @returns The impersonated path, if available
+   */
+  async resolvePath(path: string, ctx: ExtensionContext): Promise<string> {
+    // Path could be a file
+    const absPath = resolve(ctx.cwd, path);
+    if (this.mapper[absPath]) return this.mapper[absPath];
+
+    // Part of the path could be in the mapper too
+    // E.g.: `.vscode/launch.json` when only `.vscode/` is gitignored)
+    const dirPath = dirname(absPath);
+
+    for (const [source, target] of Object.entries(this.mapper)) {
+      if (dirPath.includes(source)) {
+        // We've found a gitignored `source`
+        // Let's shoehorn it as the candidate
+        const candidateDir = dirPath.replace(source, target);
+        const baseName = basename(absPath);
+
+        // If the file was not in the mapper, we'll need to create it on-the-fly here
+        const response = await this.createFile(baseName, candidateDir, ctx);
+        this.mapper[absPath] = response;
+
+        return response;
+      }
+    }
+
+    // Couldn't find anything to impersonate, return the original path
+    return path;
+  }
+
+  /**
+   * Extracts potential file paths from a bash command string.
+   *
+   * @param command - The bash command string to parse
+   * @returns Array of path arguments found in the command
+   */
+  async extractFromCommand(command: string): Promise<string[]> {
+    // Tokenize the command using shell-quote
+    const tokens = parse(command);
+
+    // Collect tokens that are not operators or globs - these could be paths
+    const paths = tokens
+      .filter((token) => typeof token === "string")
+      .filter(this.isPathLike);
+
+    return paths;
+  }
+
+  /**
+   * Detects if a string is a possible path (heuristic approach)
+   *
+   * Takes a cautious approach, only rejecting candidates that are
+   * impossible to be paths.
+   *
+   * @param candidate Candidate path to check
+   * @returns True if it looks like a path
+   */
+  private isPathLike(candidate: string): boolean {
+    // Empty strings
+    if (!candidate) return false;
+
+    // Command flags and options
+    if (candidate.startsWith("-")) return false;
+
+    // Pure numbers (e.g., 42, 3.14, -0)
+    if (/^-?\d+(\.\d+)?$/.test(candidate)) return false;
+
+    // URLs (e.g., https://example.com, ftp://...)
+    if (/^[a-z]+:\/\//i.test(candidate)) return false;
+
+    // Environment variable assignments (e.g., NODE_ENV=production)
+    if (/^[A-Z_]+=/.test(candidate)) return false;
+
+    // Shell reserved words and syntax keywords that can never be file paths.
+    const shellReservedWords = new Set([
+      "then",
+      "else",
+      "fi",
+      "do",
+      "done",
+      "esac",
+      "endif",
+      "end",
+      "true",
+      "false",
+    ]);
+    if (shellReservedWords.has(candidate)) return false;
+
+    // Default: assume it's path-like (prefer false positives)
+    return true;
+  }
+}

package/src/prompts.ts

@@ -0,0 +1,48 @@
+import { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { settings } from "./settings";
+
+/**
+ * Prompt options
+ */
+enum Options {
+  ALLOW = "Allow",
+  DENY = "Deny",
+  BYPASS_SESSION = "Bypass (session only)",
+  BYPASS_SAVE = "Bypass (saved globally)",
+}
+
+/**
+ * Asks the user if they want to allow access to a path outside the allowed directories.
+ * If the user denies, or if UI is not available, the function blocks with a reason.
+ *
+ * @param ctx The extension context
+ * @param path The path to check
+ * @returns An object with `block: true` and a `reason` if blocked, or `{ block: false }` if allowed
+ */
+export async function askUserOrBlock(
+  ctx: ExtensionContext,
+  path: string,
+): Promise<{ block: boolean; reason?: string }> {
+  const reason = `Path "${path}" is outside allowed directories and was denied.`;
+
+  // Check if UI is available
+  const { config } = await settings.getConfig();
+  if (!ctx.hasUI) {
+    return { block: true, reason };
+  }
+
+  const prompt = `[pi-gitbox]: Allow "${path}" to be accessed?`;
+  const allowed = await ctx.ui.select(prompt, Object.values(Options));
+
+  // Process the selected option
+  if (!allowed || allowed === Options.DENY) return { block: true, reason };
+
+  // Handle the bypass options.
+  if (allowed === Options.BYPASS_SESSION) {
+    config.allowedPaths = [...config.allowedPaths, path];
+  } else if (allowed === Options.BYPASS_SAVE) {
+    await settings.setConfig({ allowedPaths: [...config.allowedPaths, path] });
+  }
+
+  return { block: false };
+}

package/src/renderer.ts

@@ -0,0 +1,65 @@
+import { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Status } from "./config-types";
+import { STATUS_KEY } from "./defaults";
+import { settings } from "./settings";
+
+export class Renderer {
+  private static lastStatus: string = "";
+
+  /**
+   * Sets the status of the gitbox in the extension UI.
+   * @param ctx The extension context.
+   * @param status The status to set
+   */
+  static async setStatus(ctx: ExtensionContext, status: Status): Promise<void> {
+    // Color the status with HEX codes
+    const colorMapper: Record<Status, string> = {
+      [Status.ENABLED]: "#00ff88",
+      [Status.AVAILABLE]: "#ffaa00",
+      [Status.NOT_REQUIRED]: "#ff8800",
+      [Status.UNAVAILABLE]: "#ff4444",
+      [Status.BYPASSED]: "#44ddff",
+    };
+
+    const theme = ctx.ui.theme;
+    const coloredStatus = Renderer.colorHex(status, colorMapper[status]);
+
+    Renderer.lastStatus = `${theme.fg("dim", "📦 Gitbox:")} ${coloredStatus}`;
+    await this.update(ctx);
+  }
+
+  /**
+   * Updates the status bar with the current status and any bypass indicators.
+   *
+   * @param ctx The extension context
+   */
+  static async update(ctx: ExtensionContext): Promise<void> {
+    const { config } = await settings.getConfig();
+    const { statusBar, bypassPaths } = config;
+
+    // Verify bypass status to announce it in status bar
+    let statusText = Renderer.lastStatus;
+    if (bypassPaths) statusText += " (unrestricted)";
+
+    if (statusBar) {
+      ctx.ui.setStatus(STATUS_KEY, statusText);
+    } else {
+      ctx.ui.setStatus(STATUS_KEY, undefined);
+    }
+  }
+
+  /**
+   * Applies a custom hex color using 24-bit truecolor ANSI escape codes.
+   *
+   * @param text The text to colorize
+   * @param hex The hex color string, e.g. "#abcdef"
+   * @returns The colored text
+   */
+  private static colorHex(text: string, hex: string): string {
+    const r = parseInt(hex.slice(1, 3), 16);
+    const g = parseInt(hex.slice(3, 5), 16);
+    const b = parseInt(hex.slice(5, 7), 16);
+
+    return `\x1b[38;2;${r};${g};${b}m${text}\x1b[0m\u200b`;
+  }
+}

package/src/settings.ts

@@ -0,0 +1,134 @@
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { GitboxConfig } from "./config-types";
+import {
+  ALLOWED_PATHS,
+  BYPASS_GITBOX,
+  BYPASS_PATHS,
+  DELETE_ON_EXIT,
+  GITBOX_BASEDIR,
+  GITBOX_STATUSBAR,
+  STATUS_KEY,
+} from "./defaults";
+
+/**
+ * Manages Gitbox configuration: defaults, user settings, validation,
+ * caching, and persistence to ~/.pi/agent/settings.json.
+ */
+class Settings {
+  private cachedConfig: GitboxConfig | null = null;
+  private cachedErrors: string[] = [];
+
+  /**
+   * Manages Gitbox configuration: defaults, user settings, validation,
+   * caching, and persistence to ~/.pi/agent/settings.json.
+   *
+   * @internal Use the exported `settings` singleton instead.
+   */
+  constructor(
+    private readonly path: string = join(getAgentDir(), "settings.json"),
+  ) {}
+
+  /**
+   * Retrieves the default configuration object.
+   *
+   * @returns The default configuration.
+   */
+  private getDefaultConfig(): GitboxConfig {
+    return {
+      baseDir: GITBOX_BASEDIR,
+      statusBar: GITBOX_STATUSBAR,
+      deleteOnExit: DELETE_ON_EXIT,
+      bypassGitbox: BYPASS_GITBOX,
+      bypassPaths: BYPASS_PATHS,
+      allowedPaths: ALLOWED_PATHS,
+    };
+  }
+
+  /**
+   * Resolves the final config, merging user settings with built-in defaults,
+   * validating, and caching the result.
+   */
+  async getConfig(): Promise<{ config: GitboxConfig; errors: string[] }> {
+    if (this.cachedConfig)
+      return { config: this.cachedConfig, errors: this.cachedErrors };
+
+    const defaults = this.getDefaultConfig();
+    const userSettings = await this.readExtensionSettings();
+
+    this.cachedConfig = { ...defaults, ...userSettings };
+
+    return { config: this.cachedConfig, errors: this.cachedErrors };
+  }
+
+  /**
+   * Writes a partial GitboxConfig, invalidating the cache.
+   */
+  async setConfig(partial: Partial<GitboxConfig>): Promise<void> {
+    await this.writeExtensionSettings(partial);
+    this.resetConfigCache();
+  }
+
+  /**
+   * Resets the cached config, forcing a fresh read from disk on the next call.
+   */
+  resetConfigCache(): void {
+    this.cachedConfig = null;
+    this.cachedErrors = [];
+  }
+
+  /**
+   * Reads ~/.pi/agent/settings.json and extracts the "gitbox" settings block.
+   *
+   * @returns The Gitbox settings object.
+   */
+  private async readExtensionSettings(): Promise<GitboxConfig> {
+    const settings = await this.readSettings();
+    return (settings[STATUS_KEY] || {}) as GitboxConfig;
+  }
+
+  /**
+   * Writes a partial GitboxConfig to ~/.pi/agent/settings.json,
+   * merging it with existing values.
+   *
+   * @param partial The partial GitboxConfig to write.
+   */
+  private async writeExtensionSettings(
+    partial: Partial<GitboxConfig>,
+  ): Promise<void> {
+    const settings = await this.readSettings();
+    const current = (settings[STATUS_KEY] as Record<string, unknown>) || {};
+    settings[STATUS_KEY] = { ...current, ...partial };
+
+    await this.writeSettings(settings);
+  }
+
+  /**
+   * Reads and parses a JSON file.
+   *
+   * @returns The parsed JSON object, or an empty object on failure.
+   */
+  async readSettings(): Promise<Record<string, unknown>> {
+    try {
+      const raw = await readFile(this.path, "utf-8");
+      return JSON.parse(raw) as Record<string, unknown>;
+    } catch {
+      return {};
+    }
+  }
+
+  /**
+   * Writes a JSON object to the file with 2-space indentation.
+   *
+   * @param data The object to serialize and write.
+   */
+  async writeSettings(data: Record<string, unknown>): Promise<void> {
+    await writeFile(this.path, JSON.stringify(data, null, 2), "utf-8");
+  }
+}
+
+/**
+ * Shared singleton instance used across the extension.
+ */
+export const settings = new Settings();

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["*.ts", "src/**/*.ts"]
+}