pi-agent-toolkit 0.1.0

package/dist/dotfiles/extensions/tools.ts

@@ -0,0 +1,146 @@
+/**
+ * Tools Extension
+ *
+ * Provides a /tools command to enable/disable tools interactively.
+ * Tool selection persists across session reloads and respects branch navigation.
+ *
+ * Usage:
+ * 1. Copy this file to ~/.pi/agent/extensions/ or your project's .pi/extensions/
+ * 2. Use /tools to open the tool selector
+ */
+
+import type { ExtensionAPI, ExtensionContext, ToolInfo } from "@mariozechner/pi-coding-agent";
+import { getSettingsListTheme } from "@mariozechner/pi-coding-agent";
+import { Container, type SettingItem, SettingsList } from "@mariozechner/pi-tui";
+
+// State persisted to session
+interface ToolsState {
+	enabledTools: string[];
+}
+
+export default function toolsExtension(pi: ExtensionAPI) {
+	// Track enabled tools
+	let enabledTools: Set<string> = new Set();
+	let allTools: ToolInfo[] = [];
+
+	// Persist current state
+	function persistState() {
+		pi.appendEntry<ToolsState>("tools-config", {
+			enabledTools: Array.from(enabledTools),
+		});
+	}
+
+	// Apply current tool selection
+	function applyTools() {
+		pi.setActiveTools(Array.from(enabledTools));
+	}
+
+	// Find the last tools-config entry in the current branch
+	function restoreFromBranch(ctx: ExtensionContext) {
+		allTools = pi.getAllTools();
+
+		// Get entries in current branch only
+		const branchEntries = ctx.sessionManager.getBranch();
+		let savedTools: string[] | undefined;
+
+		for (const entry of branchEntries) {
+			if (entry.type === "custom" && entry.customType === "tools-config") {
+				const data = entry.data as ToolsState | undefined;
+				if (data?.enabledTools) {
+					savedTools = data.enabledTools;
+				}
+			}
+		}
+
+		if (savedTools) {
+			// Restore saved tool selection (filter to only tools that still exist)
+			const allToolNames = allTools.map((t) => t.name);
+			enabledTools = new Set(savedTools.filter((t: string) => allToolNames.includes(t)));
+			applyTools();
+		} else {
+			// No saved state - sync with currently active tools
+			enabledTools = new Set(pi.getActiveTools());
+		}
+	}
+
+	// Register /tools command
+	pi.registerCommand("tools", {
+		description: "Enable/disable tools",
+		handler: async (_args, ctx) => {
+			// Refresh tool list
+			allTools = pi.getAllTools();
+
+			await ctx.ui.custom((tui, theme, _kb, done) => {
+				// Build settings items for each tool
+				const items: SettingItem[] = allTools.map((tool) => ({
+					id: tool.name,
+					label: tool.name,
+					currentValue: enabledTools.has(tool.name) ? "enabled" : "disabled",
+					values: ["enabled", "disabled"],
+				}));
+
+				const container = new Container();
+				container.addChild(
+					new (class {
+						render(_width: number) {
+							return [theme.fg("accent", theme.bold("Tool Configuration")), ""];
+						}
+						invalidate() {}
+					})(),
+				);
+
+				const settingsList = new SettingsList(
+					items,
+					Math.min(items.length + 2, 15),
+					getSettingsListTheme(),
+					(id, newValue) => {
+						// Update enabled state and apply immediately
+						if (newValue === "enabled") {
+							enabledTools.add(id);
+						} else {
+							enabledTools.delete(id);
+						}
+						applyTools();
+						persistState();
+					},
+					() => {
+						// Close dialog
+						done(undefined);
+					},
+				);
+
+				container.addChild(settingsList);
+
+				const component = {
+					render(width: number) {
+						return container.render(width);
+					},
+					invalidate() {
+						container.invalidate();
+					},
+					handleInput(data: string) {
+						settingsList.handleInput?.(data);
+						tui.requestRender();
+					},
+				};
+
+				return component;
+			});
+		},
+	});
+
+	// Restore state on session start
+	pi.on("session_start", async (_event, ctx) => {
+		restoreFromBranch(ctx);
+	});
+
+	// Restore state when navigating the session tree
+	pi.on("session_tree", async (_event, ctx) => {
+		restoreFromBranch(ctx);
+	});
+
+	// Restore state after forking
+	pi.on("session_fork", async (_event, ctx) => {
+		restoreFromBranch(ctx);
+	});
+}

package/dist/dotfiles/extensions/uv.ts

@@ -0,0 +1,123 @@
+/**
+ * UV Extension - Redirects Python tooling to uv equivalents
+ *
+ * This extension wraps the bash tool to prepend intercepted-commands to PATH,
+ * which contains shim scripts that intercept common Python tooling commands
+ * and redirect agents to use uv instead.
+ *
+ * Intercepted commands:
+ * - pip/pip3: Blocked with suggestions to use `uv add` or `uv run --with`
+ * - poetry: Blocked with uv equivalents (uv init, uv add, uv sync, uv run)
+ * - python/python3: Redirected through `uv run` to a real interpreter path,
+ *   with special handling to block `python -m pip`, `python -m venv`, and
+ *   `python -m py_compile`
+ *
+ * The shim scripts are located in the intercepted-commands directory and
+ * provide helpful error messages with the equivalent uv commands.
+ *
+ * Note: PATH shims are bypassable via explicit interpreter paths
+ * (for example `.venv/bin/python`). To close that gap, this extension also
+ * blocks disallowed invocations at bash spawn time.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { createBashTool } from "@mariozechner/pi-coding-agent";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const interceptedCommandsPath = join(__dirname, "..", "intercepted-commands");
+
+function getBlockedCommandMessage(command: string): string | null {
+  // Match commands at the start of a shell segment (start/newline/; /&& /|| /|)
+  const pipCommandPattern = /(?:^|\n|[;|&]{1,2})\s*(?:\S+\/)?pip\s*(?:$|\s)/m;
+  const pip3CommandPattern = /(?:^|\n|[;|&]{1,2})\s*(?:\S+\/)?pip3\s*(?:$|\s)/m;
+  const poetryCommandPattern = /(?:^|\n|[;|&]{1,2})\s*(?:\S+\/)?poetry\s*(?:$|\s)/m;
+
+  // Match python invocations including explicit paths like .venv/bin/python
+  // and .venv/bin/python3.12.
+  const pythonPipPattern =
+    /(?:^|\n|[;|&]{1,2})\s*(?:\S+\/)?python(?:3(?:\.\d+)?)?\b[^\n;|&]*(?:\s-m\s*pip\b|\s-mpip\b)/m;
+  const pythonVenvPattern =
+    /(?:^|\n|[;|&]{1,2})\s*(?:\S+\/)?python(?:3(?:\.\d+)?)?\b[^\n;|&]*(?:\s-m\s*venv\b|\s-mvenv\b)/m;
+  const pythonPyCompilePattern =
+    /(?:^|\n|[;|&]{1,2})\s*(?:\S+\/)?python(?:3(?:\.\d+)?)?\b[^\n;|&]*(?:\s-m\s*py_compile\b|\s-mpy_compile\b)/m;
+
+  if (pipCommandPattern.test(command)) {
+    return [
+      "Error: pip is disabled. Use uv instead:",
+      "",
+      "  To install a package for a script: uv run --with PACKAGE python script.py",
+      "  To add a dependency to the project: uv add PACKAGE",
+      "",
+    ].join("\n");
+  }
+
+  if (pip3CommandPattern.test(command)) {
+    return [
+      "Error: pip3 is disabled. Use uv instead:",
+      "",
+      "  To install a package for a script: uv run --with PACKAGE python script.py",
+      "  To add a dependency to the project: uv add PACKAGE",
+      "",
+    ].join("\n");
+  }
+
+  if (poetryCommandPattern.test(command)) {
+    return [
+      "Error: poetry is disabled. Use uv instead:",
+      "",
+      "  To initialize a project: uv init",
+      "  To add a dependency: uv add PACKAGE",
+      "  To sync dependencies: uv sync",
+      "  To run commands: uv run COMMAND",
+      "",
+    ].join("\n");
+  }
+
+  if (pythonPipPattern.test(command)) {
+    return [
+      "Error: 'python -m pip' is disabled. Use uv instead:",
+      "",
+      "  To install a package for a script: uv run --with PACKAGE python script.py",
+      "  To add a dependency to the project: uv add PACKAGE",
+      "",
+    ].join("\n");
+  }
+
+  if (pythonVenvPattern.test(command)) {
+    return [
+      "Error: 'python -m venv' is disabled. Use uv instead:",
+      "",
+      "  To create a virtual environment: uv venv",
+      "",
+    ].join("\n");
+  }
+
+  if (pythonPyCompilePattern.test(command)) {
+    return [
+      "Error: 'python -m py_compile' is disabled because it writes .pyc files to __pycache__.",
+      "",
+      "  To verify syntax without bytecode output: uv run python -m ast path/to/file.py >/dev/null",
+      "",
+    ].join("\n");
+  }
+
+  return null;
+}
+
+export default function (pi: ExtensionAPI) {
+  const cwd = process.cwd();
+  const bashTool = createBashTool(cwd, {
+    commandPrefix: `export PATH="${interceptedCommandsPath}:$PATH"`,
+    spawnHook: (ctx) => {
+      const blockedMessage = getBlockedCommandMessage(ctx.command);
+      if (blockedMessage) {
+        throw new Error(blockedMessage);
+      }
+      return ctx;
+    },
+  });
+
+  pi.registerTool(bashTool);
+}

package/dist/dotfiles/global-skills/brainstorm/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: brainstorm
+description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "brainstorm".
+---
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.

package/dist/dotfiles/global-skills/cli-detector/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: cli-detector
+description: >
+  Scan a repository to discover all external SaaS tools and services it integrates with,
+  then determine whether each has an official CLI. Use this skill whenever the user asks
+  to find CLIs for their project, audit third-party service integrations, discover what
+  external services a codebase depends on, check for official CLI tools, or wants to know
+  "what services does this repo use." Also trigger when the user asks about automating
+  service management, scripting deployments, or wants to interact with their project's
+  services from the terminal.
+---
+
+# CLI Detector
+
+Analyze a repository to identify every external SaaS service it integrates with, then
+research whether each service provides an official CLI tool.
+
+The workflow has three phases: **Detect**, **Verify**, **Report**. Do not skip or
+reorder these phases.
+
+## Phase 1: Detect services
+
+Scan the repository using all applicable detection vectors below. Each vector catches
+services the others miss, so work through every one that applies to this project's
+language ecosystem.
+
+### What counts as an "external service"
+
+An external service is a hosted platform or SaaS product that the application connects
+to over the network. The company behind it manages the infrastructure.
+
+**Include:** Stripe, Sentry, Clerk, Auth0, Vercel, AWS S3, Twilio, SendGrid, Resend,
+Datadog, LaunchDarkly, Algolia, Supabase, Neon, PlanetScale, Upstash, DigitalOcean,
+Cloudflare, Firebase, GitHub (as a service), Netlify, Fly.io, Render, Railway, etc.
+
+**Exclude (these are never external services):**
+- Generic database clients: `mysql2`, `pg`, `psycopg2`, `database/sql`, `SQLAlchemy`
+- Generic protocols: SSH libraries, HTTP clients (`axios`, `requests`, `fetch`)
+- Frameworks: Next.js, Django, Rails, Express, FastAPI
+- ORMs: Drizzle, Prisma, TypeORM, ActiveRecord
+- UI libraries: React, Vue, Tailwind, Bootstrap
+- Build tools, runtimes, test runners, linters, formatters
+
+The test: if removing the integration means losing access to a *third-party managed
+platform* (not just a protocol or library), it is an external service.
+
+### Vector 1: Package manager manifests
+
+Read dependency files for SDK packages from known service vendors.
+
+| Ecosystem | Files |
+|-----------|-------|
+| Node.js / TypeScript | `package.json` |
+| Python | `pyproject.toml`, `requirements.txt`, `setup.py`, `Pipfile` |
+| Go | `go.mod` |
+| Ruby | `Gemfile` |
+| Rust | `Cargo.toml` |
+| Java / Kotlin | `build.gradle`, `pom.xml` |
+| PHP | `composer.json` |
+| .NET | `*.csproj`, `packages.config` |
+
+Vendor-namespaced packages are strong signals: `@sentry/nextjs`, `@clerk/nextjs`,
+`stripe`, `boto3`, `google-cloud-storage`.
+
+### Vector 2: Environment variables
+
+Search source code for env var access patterns and collect all variable names.
+
+| Language | Search pattern |
+|----------|---------------|
+| Node.js / TypeScript | `process.env.VARIABLE_NAME` |
+| Python | `os.environ`, `os.getenv()` |
+| Go | `os.Getenv("VARIABLE")` |
+| Ruby | `ENV["VARIABLE"]`, `ENV.fetch` |
+
+Also check `.env.example`, `.env.sample`, `.env.template` files.
+
+Variable names reveal services: `STRIPE_SECRET_KEY` -> Stripe, `SENTRY_DSN` -> Sentry,
+`CLERK_SECRET_KEY` -> Clerk, `RESEND_API_KEY` -> Resend, `DO_API_TOKEN` -> DigitalOcean,
+`UPSTASH_REDIS_REST_URL` -> Upstash, `AWS_ACCESS_KEY_ID` -> AWS, etc.
+
+### Vector 3: Configuration files
+
+Service-specific config files at the project root:
+
+`sentry.*.config.ts` -> Sentry, `vercel.json` / `.vercel/` -> Vercel,
+`firebase.json` -> Firebase, `netlify.toml` -> Netlify, `fly.toml` -> Fly.io,
+`wrangler.toml` -> Cloudflare Workers, `serverless.yml` -> check provider field,
+`render.yaml` -> Render, `railway.json` -> Railway
+
+### Vector 4: Source code imports and API URLs
+
+Search for direct SDK imports and hardcoded API base URLs:
+
+```bash
+# Service SDK imports (adapt patterns to the project's language)
+grep -r "from '@sentry\|from \"@sentry\|require('@sentry" src/
+grep -r "api.digitalocean.com\|api.stripe.com\|api.sendgrid.com" src/
+```
+
+### Vector 5: Implicit / indirect signals
+
+Some services leave clues without explicit SDK imports. **Actively search** for these
+patterns rather than waiting to stumble on them:
+
+```bash
+# Vercel signals
+grep -r "maxDuration" src/ --include="*.ts" --include="*.tsx" -l
+grep -r "CRON_SECRET" src/ --include="*.ts" --include="*.tsx" -l
+ls vercel.json .vercel/ 2>/dev/null
+
+# Heroku signals
+ls Procfile app.json 2>/dev/null
+
+# Hosting platform from git remote
+git remote -v 2>/dev/null
+```
+
+- **Vercel**: `maxDuration` exports in API route files are Vercel-specific serverless
+  config. `CRON_SECRET` is a Vercel Cron Jobs feature. `@vercel/*` packages.
+- **GitHub**: git remote pointing to github.com, `.github/` directory with workflows.
+- **GitLab**: git remote pointing to gitlab.com, `.gitlab-ci.yml`.
+- **Heroku**: `Procfile`, `app.json`.
+
+### Vector 6: CI/CD pipelines
+
+Scan pipeline configs for service references not visible in application code:
+
+- `.github/workflows/*.yml`: `uses:` actions, secrets references
+- `.gitlab-ci.yml`, `.circleci/config.yml`, `Jenkinsfile`
+
+## Phase 2: Verify CLI existence with Exa
+
+This phase is mandatory. Do not determine CLI status from memory or training data.
+
+Service CLIs are launched and deprecated frequently. Training data is often wrong
+about whether a specific service has a CLI, especially for newer or smaller services.
+The only reliable way to determine CLI status is to check externally.
+
+### What qualifies as an "official CLI"
+
+All four criteria must be met:
+- Created and maintained by the service provider (not a community wrapper)
+- Purpose-built to interact with that specific service
+- Has official documentation from the provider
+- Available through standard package managers (npm, brew, apt, pip, etc.)
+
+### Verification procedure
+
+For **every** service identified in Phase 1, call `exa_search` with the `answer`
+endpoint:
+
+```
+exa_search endpoint=answer query="Does [SERVICE_NAME] have an official CLI tool?"
+```
+
+This returns the CLI name, install command, and source links. If the answer is
+ambiguous or uncertain, follow up with a targeted doc-site search:
+
+```
+exa_search endpoint=search query="[SERVICE_NAME] CLI"
+  includeDomains=["official-docs-domain.com"]
+```
+
+Do not mark any service as "No CLI" without first running an Exa query for it.
+Even services that seem unlikely to have a CLI (auth providers, email services,
+newer startups) should be verified. CLI tooling is expanding rapidly and assumptions
+from training data are frequently wrong.
+
+## Phase 3: Report
+
+Present findings in two tables.
+
+### Primary table: services with CLI status
+
+| # | Service | Usage in This Repo | Official CLI? | CLI Name | Install |
+|---|---------|-------------------|:---:|----------|---------|
+| 1 | **Stripe** | Payment processing (`stripe` SDK, `STRIPE_SECRET_KEY`) | Yes | `stripe` | `brew install stripe/stripe-cli/stripe` |
+| 2 | **SomeService** | Feature flags (`SOMESERVICE_API_KEY`) | No | N/A | N/A |
+
+The "Usage in This Repo" column should include:
+- What the service is used for (brief)
+- How it was detected (SDK name, env var, config file)
+
+### Secondary table: excluded items
+
+| Tool | Reason excluded |
+|------|----------------|
+| MySQL (`mysql2`) | Generic database client, not an external service |
+
+This table shows the user you considered these tools and correctly filtered them.
+It demonstrates thoroughness.

package/dist/dotfiles/global-skills/gh-issue-creator/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: gh-issue-creator
+description: Use when creating GitHub issues via the `gh` CLI. Covers body structure, issue type classification (bug, feature, task), label selection, and consistent formatting. Triggers on requests to file, create, open, or submit a GitHub issue.
+---
+
+# GitHub Issue Creator
+
+Create well-structured GitHub issues using the `gh` CLI with consistent formatting, appropriate labels, and type-specific body templates.
+
+## Ground rules
+
+- Always use `gh issue create` with `--title`, `--body`, and `--label` flags
+- Auto-detect the repo from the current git context (do not ask the user to specify unless `gh` cannot resolve it)
+- Never include AI attribution or emojis in issue titles or bodies
+- Use imperative mood in titles (e.g., "Add retry logic" not "Added retry logic")
+
+## Issue types and label mapping
+
+Classify every issue into one of three types based on user intent. Map to the corresponding GitHub label:
+
+| User intent | GitHub label | When to use |
+|---|---|---|
+| **Bug** | `bug` | Something is broken, produces wrong results, or crashes |
+| **Feature** | `enhancement` | New capability, improvement, or behavioral change |
+| **Task** | context-dependent | Maintenance, refactoring, docs, infra work, chores |
+
+If the user says "feature request", "new feature", or "enhancement", use `enhancement`.
+If the user says "bug", "broken", "regression", or "not working", use `bug`.
+If the user says "task", "chore", "refactor", or "cleanup", pick the most fitting existing label (e.g., `documentation` for docs work) or omit `--label` entirely when nothing fits. Do not force a label.
+
+When uncertain, ask the user which type fits before creating the issue.
+
+## Title guidelines
+
+- Short and descriptive, max 72 characters
+- Imperative mood: "Add X", "Fix Y", "Update Z"
+- Include the affected area when it adds clarity: "fix(routing): handle missing advertiser ID"
+- No trailing punctuation
+
+## Body structure by type
+
+### Feature request (`enhancement`)
+
+```markdown
+## Summary
+
+One paragraph describing what the feature does and why it matters.
+
+## Motivation
+
+- Why this is needed
+- What problem it solves
+- What is painful or missing today
+
+## Proposed Changes
+
+### Before
+
+Show the current state -- code, config, architecture, or behavior.
+Use code blocks when showing concrete artifacts.
+
+### After
+
+Show the proposed state with the same level of detail.
+Before/after should be directly comparable.
+
+## Implementation Phases
+
+Numbered list of major steps if the work spans multiple PRs or stages.
+Skip this section for small, single-PR features.
+
+## Affected Files
+
+List the key files or areas of the codebase that will change.
+Group by category (runtime, config, tests, etc.) when helpful.
+
+## Acceptance Criteria
+
+- [ ] Checklist of conditions that must be true for the work to be complete
+- [ ] Each item should be independently verifiable
+- [ ] Include both functional and testing criteria
+```
+
+**Optional sections** (include when relevant):
+- **Rollback Strategy** -- for risky or reversible changes
+- **Risks** -- known risks and mitigations
+- **References** -- links to external docs, RFCs, or related issues
+
+### Bug report (`bug`)
+
+```markdown
+## Summary
+
+One paragraph describing the bug and its impact.
+
+## Steps to Reproduce
+
+1. Numbered steps to trigger the bug
+2. Be specific about inputs, environment, and timing
+3. Include commands, config snippets, or screenshots as needed
+
+## Expected Behavior
+
+What should happen.
+
+## Actual Behavior
+
+What happens instead. Include error messages, logs, or stack traces in code blocks.
+
+## Environment
+
+- OS / runtime version
+- Relevant dependency versions
+- Any environment-specific context (staging vs prod, specific client config, etc.)
+
+## Possible Cause
+
+If known or suspected, describe the likely root cause.
+Skip this section if unknown.
+
+## Acceptance Criteria
+
+- [ ] Bug no longer reproduces under the described steps
+- [ ] Regression test added
+```
+
+### Task (no label or contextual label)
+
+```markdown
+## Summary
+
+One paragraph describing the task and why it needs to happen.
+
+## Context
+
+Background information, motivation, or link to the broader initiative.
+
+## Requirements
+
+- Bulleted list of what the task must accomplish
+- Be specific and verifiable
+
+## Acceptance Criteria
+
+- [ ] Checklist of done conditions
+```
+
+## Workflow
+
+1. **Determine the issue type** from the user's request or ask if ambiguous
+2. **Map to the correct label** using the table above
+3. **Check existing labels** on the repo with `gh label list` to confirm the label exists
+4. **Gather enough context** -- if the user's request is brief, check the codebase for relevant details (file paths, current behavior, config shapes) before drafting. Do not ask the user for information you can find yourself.
+5. **Draft the title and body** using the appropriate template
+6. **Create the issue** -- for short bodies use `gh issue create --title "..." --body "..." --label "..."`. For longer or complex bodies, write to a temp file and use `--body-file` to avoid shell escaping issues.
+7. **Report the issue URL** back to the user
+
+## Adapting the template
+
+The body templates above are starting points. Adjust based on the content:
+
+- **Drop empty sections** -- if there is no rollback strategy or the feature is trivial, omit those sections rather than leaving them blank
+- **Add before/after blocks** -- whenever the change involves a concrete artifact (config, API shape, schema, data format), show the before and after states with code blocks
+- **Scale detail to complexity** -- a one-line bug fix needs a shorter body than a multi-phase architectural change
+- **Preserve the user's language** -- if the user provides specific wording or context, use it rather than rephrasing into generic template language
+
+## What NOT to do
+
+- Do not create issues without `--title` and `--body` flags (no interactive mode)
+- Do not guess labels that do not exist on the repo
+- Do not include a References section unless the user explicitly provides links or references to include
+- Do not pad the body with boilerplate when the issue is simple
+- Do not ask the user to specify the repo -- detect it from git context