Hot Sheet

A fast, local ticket tracker that feeds your AI coding tools.

hot sheet (noun) — a document or report listing items of high current interest, typically featuring urgent, new, or updated information.

Hot Sheet is a local-first project management tool wired into your AI coding workflow. Create tickets with a bullet-list interface, drag them into priority order, and your AI tools automatically get a structured worklist they can act on. A real PTY-backed terminal lives in the footer drawer — switch to the dashboard view to see every terminal across every project as a tile grid — so you can keep an eye on dev servers, tests, and the AI's own Claude Code session from the same window.

No cloud. No logins. No JIRA. Just tickets, terminals, and a tight feedback loop.

Desktop app (recommended) — download from GitHub Releases:

Platform	Download
macOS (Apple Silicon)	.dmg (arm64)
macOS (Intel)	.dmg (x64)
Linux	.AppImage / .deb
Windows	.msi / .exe

After installing, open the app and use Open Folder to get started — or click Install CLI to add the hotsheet command to your PATH for terminal launching.

Or install via npm:

npm install -g hotsheet

Then, from any project directory:

hotsheet

That's it. Data stays local.

Platform support. Hot Sheet is designed to run on macOS, Linux, and Windows, but active development and testing happens on macOS only. Linux and Windows builds come out of the same Tauri release pipeline and the platform-specific code paths are written to be cross-platform, but cross-platform regressions may go undetected between releases. Help from users on other platforms is welcome — bug reports, reproduction steps, and PRs fixing platform-specific issues are all actively appreciated. Please open an issue if you hit something on Linux or Windows.

---

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 review, give feedback, and add new tickets

The loop stays tight because the AI always knows what to work on next — and you always know what it's doing.

---

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. Click column headers to select all tickets in a column. 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, mark as read/unread, move to backlog, and archive actions — all with icons. Right-click any ticket for a full context menu with submenus.

Detail panel — side or bottom orientation (toggle in the toolbar), resizable, collapsible. 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. Reader mode (book icon) opens any note — or the details body — in a distraction-free overlay that you can step through with chevrons or arrow keys without re-clicking the icon.

Embedded terminal — a real PTY-backed terminal lives in the footer drawer next to the commands log. Configure multiple named terminals per project (dev server, tests, build, a Claude session, anything else), each with its own theme, font, and per-terminal shell-history pool — up-arrow on the dev-server tab won't surface the commit messages you typed on the deploy tab. 11 curated themes (Default, Dracula, Solarized Dark/Light, Nord, Gruvbox, Monokai, One Dark, Tomorrow Night, GitHub Dark/Light) and 11 monospaced font choices, settable as a project default OR per-terminal via the gear popover. Right-click tabs to close, drag-to-reorder, single + button to spawn a one-off dynamic terminal. A macOS-Terminal.app-style quit-confirm catches Cmd+Q when long-running processes (claude, npm dev, anything heavier than an idle shell) are alive so you don't lose them by accident.

Shell integration that earns its keep — xterm.js renders the buffer and Hot Sheet parses every standard shell-integration escape: OSC 7 drives a cwd-aware toolbar chip you can click to open the working directory in Finder/Explorer; OSC 8 makes hyperlinks emitted by gh, cargo, ls --hyperlink=auto, etc. actually clickable; OSC 9 fires desktop toasts AND native OS notifications (system Notification Center / tray) when the window is backgrounded; OSC 133 marks every prompt with a gutter glyph, supports Cmd+Up/Cmd+Down to jump between commands, and a hover popover with Copy command / Copy output / Rerun / Ask Claude about this buttons. A bell character (\x07) bounces the terminal tab and persists an accent outline until you visit it — and bells fired in another project's terminal surface as a dot on that project's tab so you don't miss them.

Terminal dashboard — click the square-terminal button in the toolbar to enter a dedicated full-window view showing every terminal across every registered project as a grid of 4:3 tiles. Tiles stay live (xterm + scrollback + PTY all preserved); bells bounce the tile and outline it; the column-count slider scales the whole grid from "one giant tile" to "10-per-row dense overview." Single-click a tile to magnify it to ~70% viewport with keyboard input; double-click to enter a dedicated full-pane view that resizes the PTY to fit. Shift+Cmd+Arrow (macOS) / Shift+Ctrl+Arrow (Linux/Windows) walks to the next-magnified-target tile in the indicated direction — perfect for cycling through a row of build/test pipelines. Hide / Show Terminals with named visibility groupings (e.g. "claude only", "server logs", "single app") so you can switch contexts without re-toggling rows. A flow layout mode flattens projects into a single tagged grid; sectioned mode groups by project. Off-screen tiles unmount their xterm to keep memory tame; the PTY stays alive server-side so the bytes are waiting when you scroll back.

Unread indicators — when tickets are created or updated externally (by AI tools, sync plugins, or the API), a blue dot appears next to the title. Your own edits in the UI never trigger unread status. Mark as Read/Unread from the context menu or batch toolbar. Tickets are automatically marked as read when you open them in the detail panel.

Git status tracker — auto-detected sidebar chip shows your current branch, dirty-file count, and ahead/behind upstream commits. Click to expand a popover with the file lists; one-click git fetch updates remote counts without leaving Hot Sheet. Silent no-op for non-git projects.

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. Each project remembers its own sidebar view, settings, sort preferences, and layout. Tabs appear automatically when you register a second project via Open Folder (Cmd+O). Drag tabs to reorder, right-click for close options and "Show in Finder," switch with Cmd+Shift+[/].

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, mark as read/unread, backlog, archive, delete
• Search — full-text search across ticket titles, details, ticket numbers, and tags. When matches sit in the backlog or archive, gray "Include N backlog / N archive" rows surface under the search bar so you can mix them in with one click without leaving the current view
• Ticket cross-references — HS-NNNN-style references inside notes, details, and reader-mode become clickable links that open a stacking modal showing the referenced ticket; click another reference inside that modal to push it onto the stack
• 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 / cut / paste — Cmd+C copies selected tickets (formatted text to clipboard + structured data for paste), Cmd+X cuts, Cmd+V pastes into the current project with title dedup. Works across projects.
• File attachments — attach files via file picker or drag-and-drop onto the detail panel, reveal in file manager. Feedback-dialog drafts also save their attachments — Save Draft persists files alongside the text so you can pick up where you left off.
• 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. A Database Repair panel in Settings can find a working backup automatically and run pg_resetwal if the live cluster ever needs it.
• Auto-cleanup — verified tickets auto-archive after a configurable number of days; trashed tickets auto-delete
• Portable settings — all project settings stored in settings.json for easy copying between projects
• 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. Tickets modified by the AI show a blue unread dot so you know what to review.

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:

• Play button — appears in the sidebar. Single-click sends the worklist to Claude on demand. Pending worklist changes are flushed immediately so the AI always reads up-to-date data.
• Auto mode — double-click the play button to enable automatic mode. Claude is triggered immediately, then continues monitoring for new Up Next items with debounce. 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.
• Feedback loop — Claude can request user input by adding notes prefixed with FEEDBACK NEEDED: or IMMEDIATE FEEDBACK NEEDED:. A rich dialog appears in the UI with inline-response slots between every prompt block, a catch-all field, and file attachment support. Save Draft to come back later (text + attachments survive); Submit re-triggers Claude with your response. Blue dots on project tabs indicate pending feedback.
• Custom commands — create named buttons that send custom prompts to Claude or run shell commands directly. Organize into collapsible groups. Toggle between "Claude Code" and "Shell" targets per command. Shell commands execute server-side with stdout/stderr streamed to the commands log in real time.
• 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. Per-project allow-rules can auto-approve specific tool+pattern pairs (e.g. always allow Bash:npm test) so trusted commands skip the overlay entirely.
• Commands log + embedded terminal — the footer drawer hosts both a resizable commands log (every trigger, completion, permission request, shell output) AND tabs for any number of project-scoped terminals. Hop between an npm run dev terminal, the Claude session, and the audit log without leaving Hot Sheet.
• MCP tools — Claude Code sees Hot Sheet as a connected MCP server with schema-validated tools: hotsheet_create_ticket, hotsheet_update_ticket, hotsheet_query_tickets, hotsheet_batch, hotsheet_signal_done, hotsheet_request_feedback, and 8 more. Tickets, notes, and attachments all round-trip without the AI hand-crafting curl commands.
• 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

---

Plugins

Hot Sheet supports plugins for syncing with external ticketing systems and adding custom functionality. Plugins are loaded from ~/.hotsheet/plugins/ and configured per-project.

GitHub Issues (bundled)

The GitHub Issues plugin ships with Hot Sheet and syncs tickets bidirectionally:

• Pull issues from GitHub, push local tickets to GitHub
• Map categories, priorities, and statuses via configurable labels
• Sync notes as GitHub comments, push attachments via the Contents API
• Toolbar sync button with busy indicator

Configure it in Settings → Plugins with your GitHub PAT and repository details.

Building Plugins

Plugins are ESM JavaScript modules with a manifest.json. They can:

• Sync tickets with any external system (Linear, Jira, Trello, Asana, etc.)
• Add UI elements — toolbar buttons, sidebar actions, context menu items
• Run custom actions — export, notifications, webhooks, automation

See docs/plugin-development-guide.md for the complete plugin API reference, including a full Linear plugin skeleton and standalone TypeScript types. The guide is designed to be read by both humans and AI coding assistants — point Claude Code or another AI tool at it to generate plugins for systems it already knows.

---

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:

Tier	Frequency	Retention
Recent	Every 5 minutes	Last hour (up to 12)
Hourly	Every hour	Last 12 hours (up to 12)
Daily	Every day	Last 7 days (up to 7)

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, use Open Folder to point the app at your project directory. The app remembers your projects and reopens them on subsequent launches. Optionally install the CLI for terminal-based launching:

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

Flag	Description
--port <number>	Port to run on (default: 4174)
--data-dir <path>	Data directory (default: .hotsheet/)
--no-open	Don't open the browser on startup
--strict-port	Fail if the requested port is in use
--browser	Open in browser instead of desktop window
--check-for-updates	Check for new versions
--help	Show help

Settings file

All project settings are stored in .hotsheet/settings.json. You can copy this file between projects to share configuration:

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

Key	Description
appName	Custom window title and tab name (defaults to the project folder name)
backupDir	Backup storage path (defaults to .hotsheet/backups/)
ticketPrefix	Custom ticket number prefix (defaults to HS)
appIcon	Icon variant (default, variant-1 through variant-9)

UI preferences (detail panel position, sort order, categories, custom views, custom commands, etc.) are also stored in this file and transfer automatically when you copy it.

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

Keyboard shortcuts

Shortcut	Action
Enter	Create new ticket
Cmd+I/B/F/R/K/G	Set category (customizable)
Alt+1-5	Set priority (Highest to Lowest)
Cmd+D	Toggle Up Next
Delete / Backspace	Delete selected tickets
Cmd+C	Copy ticket info
Cmd+X	Cut tickets
Cmd+V	Paste tickets
Cmd+A	Select all
Cmd+Z	Undo
Cmd+Shift+Z	Redo
Cmd+P	Print
Cmd+F	Focus search
Cmd+N / N	Focus new ticket input
Cmd+O	Open folder (add project)
Cmd+,	Settings
Cmd+Shift+[ / ]	Switch project tab
Cmd+Alt+W	Close active tab
Escape	Blur field / clear selection / close

---

Architecture

Layer	Technology
Desktop	Tauri v2 (native window, auto-updates)
CLI	TypeScript, Node.js
Server	Hono
Database	PGLite (embedded PostgreSQL)
UI	Custom server-side JSX (no React), vanilla client JS
Charts	Inline SVG (no external chart library)
Build	tsup (server + client bundles), sass (SCSS)
Storage	.hotsheet/ in your project directory

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 (3000+ tests)
npm run test:e2e         # E2E browser tests (375 tests) — fails on unexpected console errors / pageerrors / 4xx-5xx responses by default (HS-8435 / HS-8436)
STRICT_E2E_ERRORS=0 npm run test:e2e   # Local debugging only — opt out of the unexpected-event gate
npm run test:fast        # Unit + fast E2E (skips GitHub plugin 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 3000+ unit tests (vitest) and 375 Playwright E2E browser tests, plus smoke tests for production install verification.

The E2E suite carries an error-capture fixture (HS-8435 / HS-8436, e2e/coverage-fixture.ts) that fails any test with an unexpected console.error / pageerror / 4xx-5xx response event. Specs that legitimately expect an error opt in via the per-test errorCapture.allowErrors([patterns]) fixture helper (add a code comment explaining why); global noise lives in the GLOBAL_ERROR_ALLOWLIST constant. Set STRICT_E2E_ERRORS=0 for local debugging only — CI should always run with the strict default.

---

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