shortcutxl 0.2.0

package/README.md

@@ -0,0 +1,59 @@
+# Shortcut Desktop Agent
+
+A general agent that lives on your computer and has Excel superpowers through [Shortcut](https://shortcut.ai).
+
+```bash
+npm install -g shortcutxl
+shortcut
+```
+
+> **Important:** This is a CLI tool. You must install it globally with `-g`. Do not use `npm install shortcutxl` without the `-g` flag — it won't work as intended.
+
+## Capabilities
+
+Shortcut Desktop Agent full power compared to any Excel plugin:
+
+- **Data lives locally** - Your workbooks, files, and skills stay on your machine and are never sent to our servers.
+- **Multi-workbook operations** — Read and write across multiple open workbooks simultaneously.
+- **Deep feature control** — Full manipulation of pivots, charts, sensitivity tables, iterative recalculations, and more.
+- **VBA access** — Read, write, and run macros. Create VBA modules programmatically.
+- **File system access** — Save to arbitrary paths, open files from disk, export PDFs.
+- **Extensible** — Integrate any API or data source (Daloopa, Box, internal tools, etc.) by adding a skill file or a custom tool extension. Your API key is local.
+- **User-defined functions (UDFs)** — Create custom Excel formulas powered by Python to pull live data from APIs, run calculations, or query databases.
+- **External data connections** — ODBC, OLE DB, QueryTables, Power Query.
+
+## Quick Start
+
+### Prerequisites
+
+- **Windows 10 or 11** with **Microsoft Excel 2016 or later** (64-bit)
+- **Node.js >= 20** — This gives you `npm`, the package manager used to install the agent.
+
+If you don't have Node.js installed, open a terminal (Command Prompt, PowerShell, or Windows Terminal) and run:
+
+```
+winget install OpenJS.NodeJS.LTS
+```
+
+This will prompt you to approve a Windows admin dialog (UAC) — click **Yes**. After it finishes, **close and reopen your terminal** so the `npm` command is available.
+
+> **No winget?** Download the installer directly from [nodejs.org](https://nodejs.org) and run it — accept the defaults.
+
+### Install
+
+```bash
+npm install -g shortcutxl
+shortcut
+```
+
+On first launch the agent guides you through setup step by step:
+
+1. **Git Bash** — Required for the agent's shell. If missing, the agent installs it for you via `winget` (admin approval needed).
+2. **Python 3.12** — The agent checks for Python 3.12 and installs it if needed (with your permission, per-user, no admin required).
+3. **Excel add-in** — Registered with Excel so it loads automatically on startup. The agent opens Excel for you after this step.
+
+After setup, just run `shortcut` — Excel opens automatically with the agent connected.
+
+## Links
+
+- [shortcut.ai](https://shortcut.ai)

package/agent-docs/README.md

@@ -0,0 +1,397 @@
+# Shortcut Agent
+
+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.
+
+---
+
+### System Prompt
+
+Replace the default system prompt with `.shortcut/SYSTEM.md` (project) or `~/.shortcut/agent/SYSTEM.md` (global). Append without replacing via `APPEND_SYSTEM.md`.
+
+---
+
+## 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 [Agent 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) |
+
+### Tool Options
+
+| Option | Description |
+|--------|-------------|
+| `--tools <list>` | Enable specific built-in tools (default: `read,bash,edit,write`) |
+| `--no-tools` | Disable all built-in tools (extension tools still work) |
+
+Available built-in tools: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`, `task`
+
+### 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 |
+| `--theme <path>` | Load theme (repeatable) |
+| `--no-themes` | Disable theme 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 |
+|--------|-------------|
+| `--system-prompt <text>` | Replace default prompt (context files and skills 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 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"
+
+# Read-only mode
+shortcut --tools read,grep,find,ls -p "Review the code"
+
+# 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 |