npm install -g hotsheet

hotsheet

Why Hot Sheet?

AI coding tools are powerful, but they need direction. You know what needs to be built, fixed, or investigated — but communicating that to your AI tool means typing the same context over and over, or maintaining a text file that drifts out of sync.

Hot Sheet gives you a proper ticket interface — categories, priorities, statuses — with one key difference: it automatically exports a worklist.md file that AI tools like Claude Code can read directly. Your tickets become the AI's task list.

The workflow:

1. You create and prioritize tickets in Hot Sheet
2. Hot Sheet syncs an Up Next worklist to .hotsheet/worklist.md
3. Your AI tool reads the worklist and works through it
4. You mark tickets complete and add new ones

The loop stays tight because the AI always knows what to work on next.

Features

Bullet-list input — type a title, hit Enter, ticket created. Set category and priority inline with keyboard shortcuts.

Customizable categories — defaults to a software development set (Issue, Bug, Feature, Req Change, Task, Investigation), with built-in presets for Design, Product Management, Marketing, and Personal workflows. Each category has a color, badge label, and keyboard shortcut — all configurable in Settings.

Column view — switch to a kanban-style board grouped by status. Drag tickets between columns to change status, or drag onto sidebar items to set category, priority, or view.

Batch operations — select multiple tickets to bulk-update category, priority, status, or Up Next. The overflow menu (⋯) provides duplicate, tags, move to backlog, and archive actions. Right-click any ticket for a full context menu with submenus.

Detail panel — side or bottom orientation (toggle in the toolbar), resizable. Shows category, priority, status, and Up Next in a compact grid, plus title, details, tags, attachments, and editable notes. Click a note to edit inline; right-click to delete.

Stats dashboard — click the sidebar widget to open a full analytics page with throughput charts, created-vs-completed trends, cumulative flow diagram, category breakdown, and cycle time scatter plot. Hover any chart for detailed tooltips.

Multi-project tabs — open multiple projects in a single window. Tabs appear automatically when you register a second project via the Open Folder dialog (Cmd+O). Drag tabs to reorder, right-click for close options and "Show in Finder," and switch with Cmd+Shift+[/]. Each project has independent settings, sort preferences, and views.

Also includes:

• Tags — free-form tags on tickets, with autocomplete and a batch tag dialog for multi-select
• Custom views — create filtered views with an interactive query builder (field + operator + value conditions, AND/OR logic). Associate a tag with a view to enable drag-and-drop tagging and auto-tag on create.
• Custom ticket prefix — change the default HS- prefix to any project-specific prefix in Settings
• Five priority levels — Highest to Lowest, with Lucide chevron icons, sortable and filterable
• Up Next flag — star tickets to add them to the AI worklist
• Drag and drop — drag tickets onto sidebar views to change category, priority, or status; drop files onto the detail panel to attach; reorder project tabs and custom views
• Right-click context menus — full context menu on tickets with category/priority/status submenus, tags, duplicate, backlog, archive, delete — all with Lucide icons
• Search — full-text search across ticket titles, details, and ticket numbers
• Print — print the dashboard, all tickets, selected tickets, or individual tickets in checklist, summary, or full-detail format
• Keyboard-driven — Enter to create, Cmd+I/B/F/R/K/G for categories, Alt+1-5 for priority, Cmd+D for Up Next, Delete to trash, Cmd+P to print, Cmd+Z/Shift+Z for undo/redo
• Undo/redo — Cmd+Z and Cmd+Shift+Z for all operations including notes, batch changes, and deletions
• Animated transitions — smooth FLIP animations when tickets reorder after property changes
• Copy for commits — Cmd+C copies selected ticket info (number + title + details + notes) for use in commit messages
• File attachments — attach files via file picker or drag-and-drop onto the detail panel, reveal in file manager
• Markdown sync — worklist.md and open-tickets.md auto-generated on every change
• Automatic backups — tiered snapshots (every 5 min, hourly, daily) with preview-before-restore recovery
• Auto-cleanup — configurable auto-deletion of old trash and verified items
• App icon variants — 9 icon variants to choose from in Settings, applied instantly to the dock icon
• Fully local — embedded PostgreSQL (PGLite), no network calls, no accounts, no telemetry

AI Integration

The exported worklist is plain markdown. Any AI tool that can read files can use it.

Star tickets as "Up Next" and they appear in the worklist, sorted by priority. As the AI works, it updates ticket status and appends notes — visible right in the detail panel.

Claude Code

Point Claude Code at your worklist:

Read .hotsheet/worklist.md and work through the tickets in order.

Or add it to your CLAUDE.md:

Read .hotsheet/worklist.md for current work items.

Hot Sheet automatically generates skill files for Claude Code (as well as Cursor, GitHub Copilot, and Windsurf) so your AI tool can create tickets directly. Run /hotsheet in Claude Code to process the worklist.

Claude Channel Integration (Experimental)

Hot Sheet can push events directly to a running Claude Code session via MCP channels. Enable it in Settings → Experimental:

• Play button — appears in the sidebar. Single-click sends the worklist to Claude on demand.
• Auto mode — double-click the play button to enable automatic mode. When you star a ticket for Up Next, Claude is notified after a 5-second debounce and picks up the work automatically. Exponential backoff prevents runaway retries.
• Auto-prioritize — when no tickets are flagged as Up Next, Claude automatically evaluates open tickets and picks the most important ones to work on.
• Custom commands — create named buttons that send custom prompts to Claude or run shell commands directly. Toggle between "Claude Code" and "Shell" targets per command. Shell commands execute server-side with stdout/stderr captured to the commands log.
• Permission relay — when Claude needs tool approval (Bash, Edit, etc.), a full-screen overlay shows the tool name and command preview with Allow/Deny/Dismiss buttons — no need to switch to the terminal.
• Commands log — a resizable bottom panel that records all communication: triggers, completions, permission requests, and shell command output. Filter by type, search, and copy entries. Shell commands show a stop button for running processes.
• Status indicator — shows "Claude working" / "Shell running" / idle in the footer.

Requires Claude Code v2.1.80+ with channel support. See docs/12-claude-channel.md for setup details.

Other AI Tools

The worklist works with any AI tool that reads files — Cursor, Copilot, Aider, etc. Each ticket includes its number, type, priority, status, title, and details.

What gets exported

worklist.md contains all tickets flagged as "Up Next," sorted by priority:

# Hot Sheet - Up Next

These are the current priority work items. Complete them in order of priority, where reasonable.

---

TICKET HS-12:
- Type: bug
- Priority: highest
- Status: not started
- Title: Fix login redirect loop
- Details: After session timeout, the redirect goes to /login?next=/login...

---

TICKET HS-15:
- Type: feature
- Priority: high
- Status: started
- Title: Add CSV export for reports

Backups & Data Safety

Hot Sheet automatically protects your data with tiered backups and instance locking.

Automatic backups

Backups run on three schedules, each keeping a rolling window of snapshots:

You can also trigger a manual backup at any time from the settings panel with the Backup Now button.

Recovering from a backup

Open the settings panel (gear icon) to see all available recovery points grouped by tier. Click any backup to enter preview mode — the app switches to a read-only view of the backup's data. You can navigate views, filter by category/priority, switch to column layout, and inspect individual tickets to verify it's the right recovery point.

If it looks correct, click Restore This Backup to replace the current database. A safety snapshot of your current data is automatically created before the restore, so you can always go back.

Configurable backup location

By default, backups are stored in .hotsheet/backups/. To store them elsewhere — for example, a folder synced by iCloud, Google Drive, or Dropbox — set the backupDir in .hotsheet/settings.json:

{
  "backupDir": "/Users/you/Library/Mobile Documents/com~apple~CloudDocs/hotsheet-backups"
}

This can also be changed from the settings panel UI.

Instance locking

Only one Hot Sheet instance can use a data directory at a time. If you accidentally start a second instance pointing at the same .hotsheet/ folder, it will exit with a clear error instead of risking database corruption. The lock is automatically cleaned up when the app stops.

Install

Desktop app (recommended)

Download the latest release for your platform from GitHub Releases.

On first launch, the app will prompt you to install the hotsheet CLI command. This creates a symlink so you can launch the desktop app from any project directory. You can also install it manually:

macOS:

sudo sh -c 'mkdir -p /usr/local/bin && ln -sf "/Applications/Hot Sheet.app/Contents/Resources/resources/hotsheet" /usr/local/bin/hotsheet'

Linux:

ln -sf /path/to/hotsheet/resources/hotsheet-linux ~/.local/bin/hotsheet

The desktop app includes automatic updates — new versions are downloaded and applied in the background.

npm

Alternatively, install via npm (runs in your browser instead of a native window):

npm install -g hotsheet

Requires Node.js 20+.

Usage

# Start from your project directory
hotsheet

# Custom port (npm version only)
hotsheet --port 8080

# Custom data directory
hotsheet --data-dir ~/projects/my-app/.hotsheet

# Force browser mode (desktop app)
hotsheet --browser

Options

Settings file

Create .hotsheet/settings.json to configure per-project options:

{
  "appName": "HS - My Project",
  "backupDir": "/path/to/backup/location"
}

All settings can also be changed from the settings panel UI.

Keyboard shortcuts

Architecture

Data stays local. No network calls, no accounts, no telemetry.

Development

git clone <repo-url>
cd hotsheet
npm install

npm run dev              # Build client assets, then run via tsx
npm run build            # Build to dist/cli.js
npm test                 # Unit tests with coverage (446 tests)
npm run test:e2e         # E2E browser tests (55 tests)
npm run test:all         # Merged coverage report (unit + E2E)
npm run lint             # ESLint
npm run clean            # Remove dist and caches
npm link                 # Symlink for global 'hotsheet' command

The project has comprehensive test coverage with 446 unit tests (vitest) and 55 Playwright E2E browser tests, plus 12 smoke tests for production install verification.

See Also

• Glassbox — AI-powered code review tool. Runs locally, reviews your changes, and posts inline annotations. Pairs well with Hot Sheet for a complete local dev workflow.

License

MIT