# pi-amplike

[Pi](https://github.com/badlogic/pi-mono) skills and extensions that give Pi similar capabilities to [Amp Code](https://ampcode.com/) out of the box.

<p align="center">
<img src="demo.gif" alt="Pi subagents and /btw in action" width="700" />
</p>

## Features

### Session Management
- **Handoff** - Create a new focused session with AI-generated context transfer:
  - **`/handoff <goal>`** command - Manually create a handoff session (potentially with `-mode <name>` / `-model <name>` parameter to switch models for the new session)
  - **`handoff` tool** - The agent can invoke this (with optional `mode`/`model` parameters) when you explicitly request a handoff
- **`session_query`** tool - The agent in handed-off sessions automatically gets the ability to query the parent session for context, decisions, or code changes; analysis uses the queried session's own model
- Use `/resume` to switch between and navigate handed-off sessions

### Subagents and BTW
- **`subagent`** tool - The agent can create one or multiple parallel task-focused, non-interactive subagents to save context and speed up work
- **`/btw <prompt>`** command - Same semantics as in Claude Code, basically a user-triggered subagent running and finishing asynchronously and independently on the main agent

### Permissions
- **`/permissions`** command toggles bash command allow/deny permissions, directly read from AmpCode's configuration files.

### Prompt Modes
- **`/mode`** command with interactive mode selector/configuration UI (a mode is a model + thinking + color preset, active mode is shown in prompt editor border)
- **Shortcuts**:
  - **`Ctrl+Shift+S`** - mode selector
  - **`Ctrl+Space`** - cycle modes

### Web Access
- **web-search** - Search the web via Jina Search API
- **visit-webpage** - Extract webpage content as markdown (using Jina API), or download images

### Amp Skill Compatibility
- Auto-loads Amp skill directories when present:
  - `~/.config/agents/skills`
  - `~/.config/amp/skills`
  - `.agents/skills` (project-local)

## Installation

### Option A: Install from npm (recommended)

```bash
pi install npm:pi-amplike
```

### Option B: Install from git

```bash
pi install https://github.com/pasky/pi-amplike
```

### Option C: Local development

```bash
git clone https://github.com/pasky/pi-amplike ~/.pi/packages/pi-amplike
cd ~/.pi/packages/pi-amplike
npm install
```

Then add `"packages/pi-amplike"` to the `"packages"` array in `~/.pi/agent/settings.json`.

## Setup

Get a Jina API key for web skills (optional, works with rate limits without it):

```bash
export JINA_API_KEY="your-key"  # Add to ~/.profile or ~/.zprofile
```

Get an API key at [jina.ai](https://jina.ai/). Even if you charge only the minimum credit, it's going to last approximately forever.

## Usage

### Session Handoff

When your conversation gets long or you want to branch off to a focused task, you can use handoff in two ways:

**Manual handoff via command:**
```
/handoff now implement this for teams as well
/handoff -mode rush execute phase one of the plan
/handoff -model anthropic/claude-haiku-4-5 check other places that need this fix
```

Optional flags (can be combined):
- `-mode <name>` — start the new session in a named mode (e.g. `rush`, `smart`, `deep`)
- `-model <provider/id>` — start the new session with a specific model (e.g. `anthropic/claude-haiku-4-5`)

Without these flags, `/handoff` keeps the current model and thinking level in the new session.

The handoff summary is always generated with the *current* session's model before switching.

**Agent-invoked handoff:**
The agent can also initiate a handoff when you explicitly ask for it:
```
"Please hand this off to a new session to implement the fix"
"Create a handoff session to execute phase one"
```

The `handoff` tool also accepts optional `mode` and `model` parameters.

Both methods create a new session with:
- AI-generated summary of relevant context from the current conversation
- List of relevant files that were discussed or modified
- Clear task description based on your goal
- Reference to parent session (accessible via `session_query` tool)

#### Session Navigation

Use Pi's built-in `/resume` command to switch between sessions, including handed-off sessions. The handoff creates sessions with descriptive names that make them easy to find.

#### Querying Past Sessions

The `session_query` tool lets the model look up information from previous sessions. It's automatically used when a handoff includes parent session reference, but can also be invoked directly. The analysis call uses the queried session's own model (falling back to the current model if unavailable):

```
session_query("/path/to/session.jsonl", "What files were modified?")
session_query("/path/to/session.jsonl", "What approach was chosen?")
```


### Subagents

Ask your agent to "use subagents to ..." whenever you know you have a context-hungry task ahead that you would like to run isolated from the main context window.

Subagents run their own `AgentSession` with **no extensions loaded** — extensions keep module-level state and register on a shared runtime, so binding the whole set inside a second in-process session corrupts the parent's. If you have an extension that *configures* a session (the typical case: picking the system prompt for the model's provider), opt it in explicitly in `~/.pi/agent/amplike.json`:

```json
{
  "subagent": {
    "extensions": ["extensions/provider-system-prompt.ts"]
  }
}
```

This is pi's own `--no-extensions --extension <path>` semantics: nothing is discovered, only what you list is loaded. It runs inside the subagent session, so it sees the subagent's own model — which is the point, since a subagent may run a different model than the session that spawned it. Relative paths resolve against `~/.pi/agent`, `~` is expanded, and load failures are reported in the subagent's output. Only opt in extensions that keep no per-session state at module scope (pi caches extension factories per path, so the parent session and the subagent share one module instance).

When your agent is working on something and you suddenly got a question, use `/btw` to ask it. Of course, you can even ask multiple questions in parallel. The `/btw` subagent is ephemeral like tool subagents, but unlike tool subagents it sees the full contxt of your session (besides the fact that it can also use tools to read files).

### Permissions

The permissions extension enforces Amp-style bash command permissions automatically. Use the `/permissions` command to toggle modes:

```
/permissions    # toggles between enabled and yolo
```

- **enabled** (default): Amp permission rules from `~/.config/amp/settings.json` are enforced
- **yolo**: All bash commands are allowed without any checks; `YOLO mode` shown in status bar

The selected mode is persisted in `~/.pi/agent/amplike.json` and restored on the next pi invocation.

### Prompt Modes

```text
/mode              # mode picker
/mode configure    # open mode configuration UI
/mode <name>       # switch directly
/mode store <name> # store current model+thinking into a mode
```

Notes:
- The extension bootstraps with default modes are `rush`, `smart`, and `deep`; they somewhat mirror Amp defaults.
- Modes config is loaded from `.pi/modes.json` (project), falling back to `~/.pi/agent/modes.json` (global).
- Deleting all modes or setting `"modes": {}` in your modes file disables mode overlay behavior (shortcuts + editor mode border), while keeping `/mode` config UI available.

### Web Search

```bash
~/.pi/packages/pi-amplike/skills/web-search/search.py "python async tutorial"
```

### Visit Webpage

```bash
~/.pi/packages/pi-amplike/skills/visit-webpage/visit.py https://docs.example.com/api
```

## Components

| Component | Type | Description |
|-----------|------|-------------|
| [amp-skills](extensions/amp-skills.ts) | Extension | Adds Amp-compatible skill discovery paths (`~/.config/agents/skills`, `~/.config/amp/skills`, `.agents/skills`) |
| [permissions](extensions/permissions.ts) | Extension | Reads `amp.commands.allowlist` and `amp.permissions` from `~/.config/amp/settings.json` (and `.agents/settings.json`) and intercepts bash tool calls accordingly; `/permissions` toggles between `enabled` and `yolo` (all commands allowed, status bar indicator, persisted in `~/.pi/agent/amplike.json`) |
| [handoff](extensions/handoff.ts) | Extension | `/handoff [-mode <name>] [-model <provider/id>] <goal>` command + `handoff` tool (with `mode`/`model` params) for AI-powered context transfer |
| [modes](extensions/modes.ts) | Extension | Prompt mode manager with model/thinking/color presets, editor border overlay, and shortcuts |
| [session-query](extensions/session-query.ts) | Extension | `session_query` tool for querying parent sessions; uses the queried session's own model for analysis |
| [session-query](skills/session-query/) | Skill | Instructions for using the session_query tool |
| [web-search](skills/web-search/) | Skill | Web search via Jina API |
| [visit-webpage](skills/visit-webpage/) | Skill | Webpage content extraction |

## Why "AmpCode-like"?

Amp Code has excellent session management built-in - you can branch conversations, reference parent context, and navigate session history. This package brings similar workflows to Pi:

- **Context handoff** → Amp's conversation branching
- **Session querying** → Amp's ability to reference parent context

## Web Skills Origin

The web-search and visit-webpage skills were extracted from [pasky/muaddib](https://github.com/pasky/muaddib). The original implementations have additional features (rate limiting, multiple backends, async execution) that aren't needed for Pi's skill system.

## License

MIT