# Shortcut AgentController

Shortcut is an AI agent that controls Excel spreadsheets through ShortcutXL. It runs as a terminal CLI on Windows alongside Excel.

Adapt Shortcut to your workflows, not the other way around, without having to fork and modify Shortcut internals. Extend it with TypeScript [Extensions](#extensions), [Skills](#skills), [Prompt Templates](#prompt-templates), and [Themes](#themes). Put your extensions, skills, prompt templates, and themes in [Shortcut Packages](#shortcut-packages) and share them with others via npm or git.

Shortcut runs in four modes: interactive, print or JSON, RPC for process integration, and an SDK for embedding in your own apps.

Shortcut ships with ShortcutXL. Launch it from a terminal:

```bash
shortcut
```

Authentication is handled via `/login`.

Then just talk to Shortcut. By default, Shortcut gives the model tools for reading, writing, editing files, running bash commands, and executing Python inside Excel via `excel_exec`. Add capabilities via [skills](#skills), [prompt templates](#prompt-templates), [extensions](#extensions), or [Shortcut packages](#shortcut-packages).

## Table of Contents

- [Models](#models)
- [Interactive Mode](#interactive-mode)
  - [Editor](#editor)
  - [Commands](#commands)
  - [Keyboard Shortcuts](#keyboard-shortcuts)
  - [Message Queue](#message-queue)
- [Sessions](#sessions)
  - [Branching](#branching)
  - [Compaction](#compaction)
- [Settings](#settings)
- [Context Files](#context-files)
- [Customization](#customization)
  - [Prompt Templates](#prompt-templates)
  - [Skills](#skills)
  - [Extensions](#extensions)
  - [Themes](#themes)
  - [Shortcut Packages](#shortcut-packages)
- [Programmatic Usage](#programmatic-usage)
- [Philosophy](#philosophy)
- [CLI Reference](#cli-reference)

---

## Models

Shortcut routes through the Shortcut platform (`agent.shortcut.ai`). You do not need to set API keys directly. Use `/model` or Ctrl+L to switch between available models.

---

### Editor

| Feature | How |
|---------|-----|
| File reference | Type `@` to fuzzy-search project files |
| Path completion | Tab to complete paths |
| Multi-line | Shift+Enter (or Ctrl+Enter on Windows Terminal) |
| Images | Ctrl+V to paste (Alt+V on Windows), or drag onto terminal |
| Bash commands | `!command` runs and sends output to LLM, `!!command` runs without sending |

Standard editing keybindings for delete word, undo, etc. See [docs/keybindings.md](docs/keybindings.md).

### Commands

Type `/` in the editor to trigger commands. [Extensions](#extensions) can register custom commands, [skills](#skills) are available as `/skill:name`, and [prompt templates](#prompt-templates) expand via `/templatename`.

### Keyboard Shortcuts

See `/hotkeys` for the full list. Customize via `~/.shortcut/agent/keybindings.json`. See [docs/keybindings.md](docs/keybindings.md).

### Message Queue

Submit messages while the agent is working:

- **Enter** queues a *steering* message, delivered after current tool execution (interrupts remaining tools)
- **Alt+Enter** queues a *follow-up* message, delivered only after the agent finishes all work
- **Escape** aborts and restores queued messages to editor
- **Alt+Up** retrieves queued messages back to editor

Configure delivery in [settings](docs/settings.md): `steeringMode` and `followUpMode` can be `"one-at-a-time"` (default, waits for response) or `"all"` (delivers all queued at once). `transport` selects provider transport preference (`"sse"`, `"websocket"`, or `"auto"`) for providers that support multiple transports.

---

## Sessions

Sessions are stored as JSONL files with a tree structure. Each entry has an `id` and `parentId`, enabling in-place branching without creating new files. See [docs/session.md](docs/session.md) for file format.

### Management

Sessions auto-save to `~/.shortcut/agent/sessions/` organized by working directory.

```bash
shortcut -c                  # Continue most recent session
shortcut -r                  # Browse and select from past sessions
shortcut --no-session        # Ephemeral mode (don't save)
shortcut --session <path>    # Use specific session file or ID
```

### Branching

**`/tree`** - Navigate the session tree in-place. Select any previous point, continue from there, and switch between branches. All history preserved in a single file.

- Search by typing, page with left/right arrows
- Filter modes (Ctrl+O): default, no-tools, user-only, labeled-only, all
- Press `l` to label entries as bookmarks

### Compaction

Long sessions can exhaust context windows. Compaction summarizes older messages while keeping recent ones.

**Automatic:** Enabled by default. Triggers on context overflow (recovers and retries) or when approaching the limit (proactive). Configure via `/settings` or `settings.json`.

Compaction is lossy. The full history remains in the JSONL file; use `/tree` to revisit. Customize compaction behavior via [extensions](#extensions). See [docs/compaction.md](docs/compaction.md) for internals.

---

## Settings

Use `/settings` to modify common options, or edit JSON files directly:

| Location | Scope |
|----------|-------|
| `~/.shortcut/agent/settings.json` | Global (all projects) |
| `.shortcut/settings.json` | Project (overrides global) |

See [docs/settings.md](docs/settings.md) for all options.

---

## Customization

Shortcut is aggressively extensible so it doesn't have to dictate your workflow. Features that other tools bake in can be built with [extensions](#extensions), [skills](#skills), or installed from third-party [Shortcut packages](#shortcut-packages). This keeps the core minimal while letting you shape Shortcut to fit how you work.

### Prompt Templates

Reusable prompts as Markdown files. Type `/name` to expand.

```markdown
<!-- ~/.shortcut/agent/prompts/review.md -->
Review this code for bugs, security issues, and performance problems.
Focus on: {{focus}}
```

Place in `~/.shortcut/agent/prompts/`, `.shortcut/prompts/`, or a [Shortcut package](#shortcut-packages) to share with others. See [docs/prompt-templates.md](docs/prompt-templates.md).

### Skills

On-demand capability packages following the [AgentController Skills standard](https://agentskills.io). Invoke via `/skill:name` or let the agent load them automatically.

```markdown
<!-- ~/.shortcut/agent/skills/my-skill/SKILL.md -->
# My Skill
Use this skill when the user asks about X.

## Steps
1. Do this
2. Then that
```

Place in `~/.shortcut/agent/skills/`, `~/.agents/skills/`, `.shortcut/skills/`, or `.agents/skills/` (from `cwd` up through parent directories) or a [Shortcut package](#shortcut-packages) to share with others. See [docs/skills.md](docs/skills.md).

### Extensions

TypeScript modules that extend Shortcut with custom tools, commands, keyboard shortcuts, event handlers, and UI components.

```typescript
export default function (shortcut: ExtensionAPI) {
  shortcut.registerTool({ name: "deploy", ... });
  shortcut.registerCommand("stats", { ... });
  shortcut.on("tool_call", async (event, ctx) => { ... });
}
```

**What's possible:**
- Custom tools (or replace built-in tools entirely)
- Sub-agents and plan mode
- Custom compaction and summarization
- Permission gates and path protection
- Custom editors and UI components
- Status lines, headers, footers
- Git checkpointing and auto-commit
- SSH and sandbox execution
- MCP server integration
- ...anything you can dream up

Place in `~/.shortcut/agent/extensions/`, `.shortcut/extensions/`, or a [Shortcut package](#shortcut-packages) to share with others. See [docs/extensions.md](docs/extensions.md) and [examples/extensions/](examples/extensions/).

### Themes

Built-in: `dark`, `light`. Themes hot-reload: modify the active theme file and Shortcut immediately applies changes.

Place in `~/.shortcut/agent/themes/`, `.shortcut/themes/`, or a [Shortcut package](#shortcut-packages) to share with others. See [docs/themes.md](docs/themes.md).

### Shortcut Packages

Bundle and share extensions, skills, prompts, and themes via npm or git.

> **Security:** Shortcut packages run with full system access. Extensions execute arbitrary code, and skills can instruct the model to perform any action including running executables. Review source code before installing third-party packages.

```bash
shortcut install npm:@foo/shortcut-tools
shortcut install npm:@foo/shortcut-tools@1.2.3      # pinned version
shortcut install git:github.com/user/repo
shortcut install git:github.com/user/repo@v1  # tag or commit
shortcut install git:git@github.com:user/repo
shortcut install git:git@github.com:user/repo@v1  # tag or commit
shortcut install https://github.com/user/repo
shortcut install https://github.com/user/repo@v1      # tag or commit
shortcut install ssh://git@github.com/user/repo
shortcut install ssh://git@github.com/user/repo@v1    # tag or commit
shortcut remove npm:@foo/shortcut-tools
shortcut list
shortcut update                               # skips pinned packages
shortcut config                               # enable/disable extensions, skills, prompts, themes
```

Packages install to `~/.shortcut/agent/git/` (git) or global npm. Use `-l` for project-local installs (`.shortcut/git/`, `.shortcut/npm/`).

Create a package by adding a `shortcut` key to `package.json`:

```json
{
  "name": "my-shortcut-package",
  "keywords": ["shortcut-package"],
  "shortcut": {
    "extensions": ["./extensions"],
    "skills": ["./skills"],
    "prompts": ["./prompts"],
    "themes": ["./themes"]
  }
}
```

Without a `shortcut` manifest, Shortcut auto-discovers from conventional directories (`extensions/`, `skills/`, `prompts/`, `themes/`).

See [docs/packages.md](docs/packages.md).

---

## Programmatic Usage

### SDK

```typescript
import { AuthStorage, createAgentSession, ModelRegistry, SessionManager } from "shortcutxl";

const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
  authStorage: AuthStorage.create(),
  modelRegistry: new ModelRegistry(authStorage),
});

await session.prompt("What files are in the current directory?");
```

See [docs/sdk.md](docs/sdk.md) and [examples/sdk/](examples/sdk/).

---

## Philosophy

Shortcut is aggressively extensible so it doesn't have to dictate your workflow. Features that other tools bake in can be built with [extensions](#extensions), [skills](#skills), or installed from third-party [Shortcut packages](#shortcut-packages). This keeps the core minimal while letting you shape Shortcut to fit how you work.

**No MCP.** Build CLI tools with READMEs (see [Skills](#skills)), or build an extension that adds MCP support.

**No permission popups.** Run in a container, or build your own confirmation flow with [extensions](#extensions) inline with your environment and security requirements.

**No built-in to-dos.** They confuse models. Use a TODO.md file, or build your own with [extensions](#extensions).

**No background bash.** Use tmux. Full observability, direct interaction.

---

## CLI Reference

```bash
shortcut [options] [@files...] [messages...]
```

### Package Commands

```bash
shortcut install <source> [-l]    # Install package, -l for project-local
shortcut remove <source> [-l]     # Remove package
shortcut update [source]          # Update packages (skips pinned)
shortcut list                     # List installed packages
shortcut config                   # Enable/disable package resources
```

### Modes

| Flag | Description |
|------|-------------|
| (default) | Interactive mode |
| `-p`, `--print` | Print response and exit |
| `--mode json` | Output all events as JSON lines (see [docs/json.md](docs/json.md)) |
| `--mode rpc` | RPC mode for process integration (see [docs/rpc.md](docs/rpc.md)) |
| `--export <in> [out]` | Export session to HTML |

### Model Options

| Option | Description |
|--------|-------------|
| `--provider <name>` | Provider |
| `--model <pattern>` | Model pattern or ID (supports `provider/id` and optional `:<thinking>`) |
| `--thinking <level>` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh` |
| `--list-models [search]` | List available models |

### Session Options

| Option | Description |
|--------|-------------|
| `-c`, `--continue` | Continue most recent session |
| `-r`, `--resume` | Browse and select session |
| `--session <path>` | Use specific session file or partial UUID |
| `--session-dir <dir>` | Custom session storage directory |
| `--no-session` | Ephemeral mode (don't save) |

### Resource Options

| Option | Description |
|--------|-------------|
| `-e`, `--extension <source>` | Load extension from path, npm, or git (repeatable) |
| `--no-extensions` | Disable extension discovery |
| `--skill <path>` | Load skill (repeatable) |
| `--no-skills` | Disable skill discovery |
| `--prompt-template <path>` | Load prompt template (repeatable) |
| `--no-prompt-templates` | Disable prompt template discovery |

Combine `--no-*` with explicit flags to load exactly what you need, ignoring settings.json (e.g., `--no-extensions -e ./my-ext.ts`).

### Other Options

| Option | Description |
|--------|-------------|
| `--verbose` | Force verbose startup |
| `-h`, `--help` | Show help |
| `-v`, `--version` | Show version |

### File Arguments

Prefix files with `@` to include in the message:

```bash
shortcut @prompt.md "Answer this"
shortcut -p @screenshot.png "What's in this image?"
shortcut @code.ts @test.ts "Review these files"
```

### Examples

```bash
# Interactive with initial prompt
shortcut "List all .ts files in src/"

# Non-interactive
shortcut -p "Summarize this codebase"

# Different model
shortcut --model sonnet "Help me refactor"

# Model with thinking level shorthand
shortcut --model sonnet:high "Solve this complex problem"

# High thinking level
shortcut --thinking high "Solve this complex problem"
```

### Environment Variables

| Variable | Description |
|----------|-------------|
| `SHORTCUT_CODING_AGENT_DIR` | Override config directory (default: `~/.shortcut/agent`) |
| `SHORTCUT_PACKAGE_DIR` | Override package directory |
| `SHORTCUT_SKIP_VERSION_CHECK` | Skip version check at startup |
| `VISUAL`, `EDITOR` | External editor for Ctrl+G |
