@eminent337/aery 0.1.58 → 0.1.60

package/docs/usage.md

@@ -0,0 +1,275 @@
+# Using Pi
+
+This page collects day-to-day usage details that do not fit on the quickstart page.
+
+## Interactive Mode
+
+<p align="center"><img src="images/interactive-mode.png" alt="Interactive Mode" width="600"></p>
+
+The interface has four main areas:
+
+- **Startup header** - shortcuts, loaded context files, prompt templates, skills, and extensions
+- **Messages** - user messages, assistant responses, tool calls, tool results, notifications, errors, and extension UI
+- **Editor** - where you type; border color indicates the current thinking level
+- **Footer** - working directory, session name, token/cache usage, cost, context usage, and current model
+
+The editor can be replaced temporarily by built-in UI such as `/settings` or by custom extension UI.
+
+### Editor Features
+
+| Feature | How |
+|---------|-----|
+| File reference | Type `@` to fuzzy-search project files |
+| Path completion | Press Tab to complete paths |
+| Multi-line input | Shift+Enter, or Ctrl+Enter on Windows Terminal |
+| Images | Paste with Ctrl+V, Alt+V on Windows, or drag into the terminal |
+| Shell command | `!command` runs and sends output to the model |
+| Hidden shell command | `!!command` runs without sending output to the model |
+| External editor | Ctrl+G opens `$VISUAL` or `$EDITOR` |
+
+See [Keybindings](keybindings.md) for all shortcuts and customization.
+
+## Slash Commands
+
+Type `/` in the editor to open command completion. Extensions can register custom commands, skills are available as `/skill:name`, and prompt templates expand via `/templatename`.
+
+| Command | Description |
+|---------|-------------|
+| `/login`, `/logout` | Manage OAuth or API-key credentials |
+| `/model` | Switch models |
+| `/scoped-models` | Enable/disable models for Ctrl+P cycling |
+| `/settings` | Thinking level, theme, message delivery, transport |
+| `/resume` | Pick from previous sessions |
+| `/new` | Start a new session |
+| `/name <name>` | Set session display name |
+| `/session` | Show session file, ID, messages, tokens, and cost |
+| `/tree` | Jump to any point in the session and continue from there |
+| `/fork` | Create a new session from a previous user message |
+| `/clone` | Duplicate the current active branch into a new session |
+| `/compact [prompt]` | Manually compact context, optionally with custom instructions |
+| `/copy` | Copy last assistant message to clipboard |
+| `/export [file]` | Export session to HTML |
+| `/share` | Upload as private GitHub gist with shareable HTML link |
+| `/reload` | Reload keybindings, extensions, skills, prompts, and context files |
+| `/hotkeys` | Show all keyboard shortcuts |
+| `/changelog` | Display version history |
+| `/quit` | Quit pi |
+
+## Message Queue
+
+You can submit messages while the agent is still working:
+
+- **Enter** queues a steering message, delivered after the current assistant turn finishes executing its tool calls.
+- **Alt+Enter** queues a follow-up message, delivered after the agent finishes all work.
+- **Escape** aborts and restores queued messages to the editor.
+- **Alt+Up** retrieves queued messages back to the editor.
+
+On Windows Terminal, Alt+Enter is fullscreen by default. Remap it as described in [Terminal setup](terminal-setup.md) if you want pi to receive the shortcut.
+
+Configure delivery in [Settings](settings.md) with `steeringMode` and `followUpMode`.
+
+## Sessions
+
+Sessions are saved automatically to `~/.aery/agent/sessions/`, organized by working directory.
+
+```bash
+pi -c                  # Continue most recent session
+pi -r                  # Browse and select a session
+pi --no-session        # Ephemeral mode; do not save
+pi --session <path|id> # Use a specific session file or session ID
+pi --fork <path|id>    # Fork a session into a new session file
+```
+
+Useful session commands:
+
+- `/session` shows the current session file and ID.
+- `/tree` navigates the in-file session tree and can summarize abandoned branches.
+- `/fork` creates a new session from an earlier user message.
+- `/clone` duplicates the current active branch into a new session file.
+- `/compact` summarizes older messages to free context.
+
+See [Sessions](session.md), [Session Tree](tree.md), and [Compaction](compaction.md) for details.
+
+## Context Files
+
+Pi loads `AGENTS.md` or `CLAUDE.md` at startup from:
+
+- `~/.aery/agent/AGENTS.md` for global instructions
+- parent directories, walking up from the current working directory
+- the current directory
+
+Use context files for project conventions, commands, safety rules, and preferences. Disable loading with `--no-context-files` or `-nc`.
+
+### System Prompt Files
+
+Replace the default system prompt with:
+
+- `.pi/SYSTEM.md` for a project
+- `~/.aery/agent/SYSTEM.md` globally
+
+Append to the default prompt without replacing it with `APPEND_SYSTEM.md` in either location.
+
+## Exporting and Sharing Sessions
+
+Use `/export [file]` to write a session to HTML.
+
+Use `/share` to upload a private GitHub gist with a shareable HTML link.
+
+If you use pi for open source work and want to publish sessions for model, prompt, tool, and evaluation research, see [`badlogic/pi-share-hf`](https://github.com/badlogic/pi-share-hf). It publishes sessions to Hugging Face datasets.
+
+## CLI Reference
+
+```bash
+pi [options] [@files...] [messages...]
+```
+
+### Package Commands
+
+```bash
+pi install <source> [-l]     # Install package, -l for project-local
+pi remove <source> [-l]      # Remove package
+pi uninstall <source> [-l]   # Alias for remove
+pi update [source|self|pi]   # Update pi and packages; skips pinned packages
+pi update --extensions       # Update packages only
+pi update --self             # Update pi only
+pi update --extension <src>  # Update one package
+pi list                      # List installed packages
+pi config                    # Enable/disable package resources
+```
+
+See [Pi Packages](packages.md) for package sources and security notes.
+
+### Modes
+
+| Flag | Description |
+|------|-------------|
+| default | Interactive mode |
+| `-p`, `--print` | Print response and exit |
+| `--mode json` | Output all events as JSON lines; see [JSON mode](json.md) |
+| `--mode rpc` | RPC mode over stdin/stdout; see [RPC mode](rpc.md) |
+| `--export <in> [out]` | Export a session to HTML |
+
+In print mode, pi also reads piped stdin and merges it into the initial prompt:
+
+```bash
+cat README.md | pi -p "Summarize this text"
+```
+
+### Model Options
+
+| Option | Description |
+|--------|-------------|
+| `--provider <name>` | Provider, such as `anthropic`, `openai`, or `google` |
+| `--model <pattern>` | Model pattern or ID; supports `provider/id` and optional `:<thinking>` |
+| `--api-key <key>` | API key, overriding environment variables |
+| `--thinking <level>` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh` |
+| `--models <patterns>` | Comma-separated patterns for Ctrl+P cycling |
+| `--list-models [search]` | List available models |
+
+### Session Options
+
+| Option | Description |
+|--------|-------------|
+| `-c`, `--continue` | Continue the most recent session |
+| `-r`, `--resume` | Browse and select a session |
+| `--session <path\|id>` | Use a specific session file or partial UUID |
+| `--fork <path\|id>` | Fork a session file or partial UUID into a new session |
+| `--session-dir <dir>` | Custom session storage directory |
+| `--no-session` | Ephemeral mode; do not save |
+
+### Tool Options
+
+| Option | Description |
+|--------|-------------|
+| `--tools <list>`, `-t <list>` | Allowlist specific built-in, extension, and custom tools |
+| `--no-builtin-tools`, `-nbt` | Disable built-in tools but keep extension/custom tools enabled |
+| `--no-tools`, `-nt` | Disable all tools |
+
+Built-in tools: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`.
+
+### Resource Options
+
+| Option | Description |
+|--------|-------------|
+| `-e`, `--extension <source>` | Load an extension from path, npm, or git; repeatable |
+| `--no-extensions` | Disable extension discovery |
+| `--skill <path>` | Load a skill; repeatable |
+| `--no-skills` | Disable skill discovery |
+| `--prompt-template <path>` | Load a prompt template; repeatable |
+| `--no-prompt-templates` | Disable prompt template discovery |
+| `--theme <path>` | Load a theme; repeatable |
+| `--no-themes` | Disable theme discovery |
+| `--no-context-files`, `-nc` | Disable `AGENTS.md` and `CLAUDE.md` discovery |
+
+Combine `--no-*` with explicit flags to load exactly what you need, ignoring settings. Example:
+
+```bash
+pi --no-extensions -e ./my-extension.ts
+```
+
+### Other Options
+
+| Option | Description |
+|--------|-------------|
+| `--system-prompt <text>` | Replace default prompt; context files and skills are still appended |
+| `--append-system-prompt <text>` | Append to system prompt |
+| `--verbose` | Force verbose startup |
+| `-h`, `--help` | Show help |
+| `-v`, `--version` | Show version |
+
+### File Arguments
+
+Prefix files with `@` to include them in the message:
+
+```bash
+pi @prompt.md "Answer this"
+pi -p @screenshot.png "What's in this image?"
+pi @code.ts @test.ts "Review these files"
+```
+
+### Examples
+
+```bash
+# Interactive with initial prompt
+pi "List all .ts files in src/"
+
+# Non-interactive
+pi -p "Summarize this codebase"
+
+# Non-interactive with piped stdin
+cat README.md | pi -p "Summarize this text"
+
+# Different model
+pi --provider openai --model gpt-4o "Help me refactor"
+
+# Model with provider prefix
+pi --model openai/gpt-4o "Help me refactor"
+
+# Model with thinking level shorthand
+pi --model sonnet:high "Solve this complex problem"
+
+# Limit model cycling
+pi --models "claude-*,gpt-4o"
+
+# Read-only mode
+pi --tools read,grep,find,ls -p "Review the code"
+```
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `PI_CODING_AGENT_DIR` | Override config directory; default is `~/.aery/agent` |
+| `PI_PACKAGE_DIR` | Override package directory, useful for Nix/Guix store paths |
+| `PI_SKIP_VERSION_CHECK` | Skip version check at startup |
+| `PI_TELEMETRY` | Override install telemetry: `1`/`true`/`yes` or `0`/`false`/`no` |
+| `PI_CACHE_RETENTION` | Set to `long` for extended prompt cache where supported |
+| `VISUAL`, `EDITOR` | External editor for Ctrl+G |
+
+## Design Principles
+
+Pi keeps the core small and pushes workflow-specific behavior into extensions, skills, prompt templates, and packages.
+
+It intentionally does not include built-in MCP, sub-agents, permission popups, plan mode, to-dos, or background bash. You can build or install those workflows as extensions or packages, or use external tools such as containers and tmux.
+
+For the full rationale, read the [blog post](https://mariozechner.at/posts/2025-11-30-pi-coding-agent/).

package/examples/extensions/README.md

@@ -34,6 +34,7 @@ cp permission-gate.ts ~/.pi/agent/extensions/
 | `questionnaire.ts` | Multi-question input with tab bar navigation between questions |
 | `tool-override.ts` | Override built-in tools (e.g., add logging/access control to `read`) |
 | `dynamic-tools.ts` | Register tools after startup (`session_start`) and at runtime via command, with prompt snippets and tool-specific prompt guidelines |
+| `structured-output.ts` | Final structured-output tool that returns `terminate: true` so the agent can end on the tool call |
 | `built-in-tool-renderer.ts` | Custom compact rendering for built-in tools (read, bash, edit, write) while keeping original behavior |
 | `minimal-mode.ts` | Override built-in tool rendering for minimal display (only tool calls, no output in collapsed mode) |
 | `truncated-tool.ts` | Wraps ripgrep with proper output truncation (50KB/2000 lines) |
@@ -51,6 +52,7 @@ cp permission-gate.ts ~/.pi/agent/extensions/
 | `handoff.ts` | Transfer context to a new focused session via `/handoff <goal>` |
 | `qna.ts` | Extracts questions from last response into editor via `ctx.ui.setEditorText()` |
 | `status-line.ts` | Shows turn progress in footer via `ctx.ui.setStatus()` with themed colors |
+| `github-issue-autocomplete.ts` | Adds `#1234` issue completions by stacking a custom autocomplete provider that preloads open issues from `gh issue list` |
 | `widget-placement.ts` | Shows widgets above and below the editor via `ctx.ui.setWidget()` placement |
 | `hidden-thinking-label.ts` | Customizes the collapsed thinking label via `ctx.ui.setHiddenThinkingLabel()` |
 | `working-indicator.ts` | Customizes the streaming working indicator via `ctx.ui.setWorkingIndicator()` |

package/examples/extensions/antigravity-image-gen.ts

@@ -29,9 +29,9 @@ import { randomUUID } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { StringEnum } from "@eminent337/aery-ai";
 import { type ExtensionAPI, getAgentDir, withFileMutationQueue } from "@eminent337/aery";
-import { type Static, Type } from "@sinclair/typebox";
+import { StringEnum } from "@eminent337/aery-ai";
+import { type Static, Type } from "typebox";
 
 const PROVIDER = "google-antigravity";
 

package/examples/extensions/border-status-editor.ts

@@ -0,0 +1,145 @@
+import { CustomEditor, type ExtensionAPI, type ExtensionContext, type KeybindingsManager } from "@eminent337/aery";
+import type { Component, EditorTheme, TUI } from "@eminent337/aery-tui";
+import { truncateToWidth, visibleWidth } from "@eminent337/aery-tui";
+
+function fitBorder(
+	left: string,
+	right: string,
+	width: number,
+	border: (text: string) => string,
+	fill: (text: string) => string = border,
+): string {
+	if (width <= 0) return "";
+	if (width === 1) return border("─");
+
+	let leftText = left;
+	let rightText = right;
+	const fixedWidth = 2;
+	const minimumGap = 3;
+
+	while (
+		fixedWidth + visibleWidth(leftText) + visibleWidth(rightText) + minimumGap > width &&
+		visibleWidth(rightText) > 0
+	) {
+		rightText = truncateToWidth(rightText, Math.max(0, visibleWidth(rightText) - 1), "");
+	}
+	while (
+		fixedWidth + visibleWidth(leftText) + visibleWidth(rightText) + minimumGap > width &&
+		visibleWidth(leftText) > 0
+	) {
+		leftText = truncateToWidth(leftText, Math.max(0, visibleWidth(leftText) - 1), "");
+	}
+
+	const gapWidth = Math.max(0, width - fixedWidth - visibleWidth(leftText) - visibleWidth(rightText));
+	return `${border("─")}${leftText}${fill("─".repeat(gapWidth))}${rightText}${border("─")}`;
+}
+
+function formatCwd(cwd: string): string {
+	const home = process.env.HOME;
+	if (home && cwd.startsWith(home)) {
+		return `~${cwd.slice(home.length)}`;
+	}
+	return cwd;
+}
+
+function formatContext(ctx: ExtensionContext): string {
+	const usage = ctx.getContextUsage();
+	const contextWindow = usage?.contextWindow ?? ctx.model?.contextWindow;
+	if (!contextWindow || !usage || usage.percent === null) {
+		return "ctx ?";
+	}
+	return `ctx ${Math.round(usage.percent)}%/${(contextWindow / 1000).toFixed(0)}k`;
+}
+
+function formatThinking(level: string): string {
+	return level === "off" ? "off" : level;
+}
+
+class EmptyFooter implements Component {
+	render(): string[] {
+		return [];
+	}
+
+	invalidate(): void {}
+}
+
+export default function (pi: ExtensionAPI) {
+	let isWorking = false;
+	let spinnerIndex = 0;
+	let spinnerTimer: ReturnType<typeof setInterval> | undefined;
+	let activeTui: TUI | undefined;
+	const spinnerFrames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+	const stopSpinner = () => {
+		if (spinnerTimer) {
+			clearInterval(spinnerTimer);
+			spinnerTimer = undefined;
+		}
+	};
+
+	pi.on("agent_start", () => {
+		isWorking = true;
+		stopSpinner();
+		spinnerTimer = setInterval(() => {
+			spinnerIndex = (spinnerIndex + 1) % spinnerFrames.length;
+			activeTui?.requestRender();
+		}, 80);
+		activeTui?.requestRender();
+	});
+
+	pi.on("agent_end", () => {
+		isWorking = false;
+		stopSpinner();
+		activeTui?.requestRender();
+	});
+
+	pi.on("session_shutdown", () => {
+		stopSpinner();
+		activeTui = undefined;
+	});
+
+	pi.on("session_start", (_event, ctx) => {
+		ctx.ui.setWorkingVisible(false);
+		ctx.ui.setFooter(() => new EmptyFooter());
+
+		let branch: string | undefined;
+
+		const refreshBranch = async () => {
+			const result = await pi.exec("git", ["branch", "--show-current"], { cwd: ctx.cwd }).catch(() => undefined);
+			const stdout = result?.stdout.trim();
+			branch = stdout && stdout.length > 0 ? stdout : undefined;
+			activeTui?.requestRender();
+		};
+		void refreshBranch();
+
+		class BorderStatusEditor extends CustomEditor {
+			constructor(tui: TUI, theme: EditorTheme, keybindings: KeybindingsManager) {
+				super(tui, theme, keybindings, { paddingX: 0 });
+				activeTui = tui;
+			}
+
+			render(width: number): string[] {
+				const lines = super.render(width);
+				if (lines.length < 2) return lines;
+
+				const thm = ctx.ui.theme;
+				const model = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "no model";
+				const thinking = pi.getThinkingLevel();
+				const topLeft = isWorking ? thm.fg("accent", ` ${spinnerFrames[spinnerIndex]} `) : "";
+				const topRight = "";
+				const bottomLeft = thm.fg("muted", ` ${model} · ${formatThinking(thinking)} `);
+				const bottomRight = thm.fg(
+					"muted",
+					` ${formatContext(ctx)} · ${formatCwd(ctx.cwd)}${branch ? ` (${branch})` : ""} `,
+				);
+				const borderColor = (text: string) => this.borderColor(text);
+
+				lines[0] = fitBorder(topLeft, topRight, width, borderColor);
+				lines[lines.length - 1] = fitBorder(bottomLeft, bottomRight, width, borderColor);
+				return lines;
+			}
+		}
+
+		ctx.ui.setEditorComponent((tui, theme, keybindings) => new BorderStatusEditor(tui, theme, keybindings));
+	});
+}

package/examples/extensions/custom-compaction.ts

@@ -13,9 +13,9 @@
  *   pi --extension examples/extensions/custom-compaction.ts
  */
 
-import { complete } from "@eminent337/aery-ai";
 import type { ExtensionAPI } from "@eminent337/aery";
 import { convertToLlm, serializeConversation } from "@eminent337/aery";
+import { complete } from "@eminent337/aery-ai";
 
 export default function (pi: ExtensionAPI) {
 	pi.on("session_before_compact", async (event, ctx) => {

package/examples/extensions/custom-footer.ts

@@ -8,8 +8,8 @@
  * Token stats come from ctx.sessionManager/ctx.model (already accessible).
  */
 
-import type { AssistantMessage } from "@eminent337/aery-ai";
 import type { ExtensionAPI } from "@eminent337/aery";
+import type { AssistantMessage } from "@eminent337/aery-ai";
 import { truncateToWidth, visibleWidth } from "@eminent337/aery-tui";
 
 export default function (pi: ExtensionAPI) {

package/examples/extensions/custom-provider-anthropic/index.ts

@@ -23,6 +23,7 @@
 
 import Anthropic from "@anthropic-ai/sdk";
 import type { ContentBlockParam, MessageCreateParamsStreaming } from "@anthropic-ai/sdk/resources/messages.js";
+import type { ExtensionAPI } from "@eminent337/aery";
 import {
 	type Api,
 	type AssistantMessage,
@@ -43,7 +44,6 @@ import {
 	type ToolCall,
 	type ToolResultMessage,
 } from "@eminent337/aery-ai";
-import type { ExtensionAPI } from "@eminent337/aery";
 
 // =============================================================================
 // OAuth Implementation (copied from packages/ai/src/utils/oauth/anthropic.ts)

package/examples/extensions/custom-provider-anthropic/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-custom-provider",
-  "version": "0.67.68",
+  "version": "0.70.6",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-custom-provider",
-      "version": "0.67.68",
+      "version": "0.70.6",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.52.0"
       }

package/examples/extensions/custom-provider-anthropic/package.json

@@ -1,7 +1,7 @@
 {
   "name": "aery-extension-custom-provider-anthropic",
   "private": true,
-  "version": "0.67.68",
+  "version": "0.70.6",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/custom-provider-gitlab-duo/index.ts

@@ -9,6 +9,7 @@
  *   # Then /login gitlab-duo, or set GITLAB_TOKEN=glpat-...
  */
 
+import type { ExtensionAPI } from "@eminent337/aery";
 import {
 	type Api,
 	type AssistantMessageEventStream,
@@ -21,7 +22,6 @@ import {
 	streamSimpleAnthropic,
 	streamSimpleOpenAIResponses,
 } from "@eminent337/aery-ai";
-import type { ExtensionAPI } from "@eminent337/aery";
 
 // =============================================================================
 // Constants

package/examples/extensions/custom-provider-gitlab-duo/package.json

@@ -1,7 +1,7 @@
 {
   "name": "aery-extension-custom-provider-gitlab-duo",
   "private": true,
-  "version": "0.67.68",
+  "version": "0.70.6",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/custom-provider-qwen-cli/index.ts

@@ -9,8 +9,8 @@
  *   # Then /login qwen-cli, or set QWEN_CLI_API_KEY=...
  */
 
-import type { OAuthCredentials, OAuthLoginCallbacks } from "@eminent337/aery-ai";
 import type { ExtensionAPI } from "@eminent337/aery";
+import type { OAuthCredentials, OAuthLoginCallbacks } from "@eminent337/aery-ai";
 
 // =============================================================================
 // Constants

package/examples/extensions/custom-provider-qwen-cli/package.json

@@ -1,7 +1,7 @@
 {
   "name": "aery-extension-custom-provider-qwen-cli",
   "private": true,
-  "version": "0.67.68",
+  "version": "0.70.6",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/dynamic-tools.ts

@@ -8,7 +8,7 @@
  */
 
 import type { ExtensionAPI } from "@eminent337/aery";
-import { Type } from "@sinclair/typebox";
+import { Type } from "typebox";
 
 const ECHO_PARAMS = Type.Object({
 	message: Type.String({ description: "Message to echo" }),
@@ -35,7 +35,7 @@ export default function dynamicToolsExtension(pi: ExtensionAPI) {
 			label,
 			description: `Echo a message with prefix: ${prefix}`,
 			promptSnippet: `Echo back user-provided text with ${prefix.trim()} prefix`,
-			promptGuidelines: ["Use this tool when the user asks for exact echo output."],
+			promptGuidelines: ["Use echo_session when the user asks for exact echo output."],
 			parameters: ECHO_PARAMS,
 			async execute(_toolCallId, params) {
 				return {