Sightdeck AI

Documentation

User Guide

How to install Sightdeck AI, how the moving parts fit together, and how to drive a day's worth of work through it. Written for both audiences in one voice — indie builders without a dev background can follow the steps, developers see the file paths to verify what is going on under the hood.

Getting Started

What you need

  • A Mac running macOS (Apple Silicon or Intel). Windows support is in progress; the skill and CLI scripts are pure Python and run anywhere Claude Code does.
  • Claude Code installed and logged in. Sightdeck AI is a layer on top — it does not replace the CLI.
  • A Sightdeck AI license (yearly subscription, €49). A free trial runs without a license; activation unlocks the full feature set on up to two machines.

Install the app

  1. Open the download section on the homepage and pick the build for your Mac (Apple Silicon or Intel).
  2. Open the .dmg and drag Sightdeck AI into Applications.
  3. Launch Sightdeck AI. The first screen is Setup.

Install the skill

The Sightdeck skill is the contract between you, Claude and the app. It keeps the task lifecycle in sync so the app always shows the real state.

  1. In Setup → Install Skill, click Install. The skill lands in ~/.claude/skills/sightdeck-ai/ and Claude Code picks it up automatically.
  2. The skill is self-installing per project: on first use inside a project, it adds a UserPromptSubmit hook to .claude/settings.json so every later Claude prompt runs through Sightdeck without manual setup.
  3. Verify: open a project, ask Claude to do anything. A .agents/sightdeck/sightdeck.xml file appears in the project root.

Activate your license

  1. In Setup → License, paste the license code you received via email.
  2. The app verifies the code once online and stores the activation locally. No further outbound connection is required.
  3. The same license activates one more machine — useful for a laptop / desktop pair.

Add your first project

  1. Click Add Project in the sidebar.
  2. Pick the folder of any Git repository you work in. Sightdeck AI starts watching <repo>/.agents/sightdeck/sightdeck.xml.
  3. Set a prefix (e.g. SD, MO, WB) — this prefixes every task ID displayed in the app (SD-12, MO-7). Sightdeck suggests one based on the folder name; override it if a teammate already established a convention.
  4. Optional: set a language (en or de) and tags for filtering.

The project now appears in the sidebar. You can add as many as you want; all of them stream into the same dashboard.

Concepts

Five concepts run through everything Sightdeck does. Reading this section once saves a lot of "what does that pill mean?" moments later.

Task

A single unit of work. Stored as a <task> element in sightdeck.xml, displayed as a card in the app. Every task has:

  • A title and summary (what to do).
  • An estimate bucket (15min, 30min, 1h, 2h, halber tag, 1 tag, mehrere tage).
  • Story points (Fibonacci: 1, 2, 3, 5, 8, 13, 21, 34) — measure complexity, not pure time.
  • A kind: bug, change, feature, research, or question.
  • A Claude model: haiku, sonnet or opus, suggested from the story points.
  • A status along the lifecycle.

The body of the task — what to actually do, prep notes, sub-steps — lives in a Markdown concept file at .agents/sightdeck/tasks/<TASK-ID>.md. Claude writes and updates it. You can edit it like any other file.

Lifecycle

Every task moves through a fixed sequence of states:

  1. backlog — created, not started.
  2. active — Claude is working on it.
  3. testing — verification is running (tests, build, lint, smoke). The status pill carries the name of the verifier (e.g. PHPUnit, Cypress, make pr, tsc) so you can tell at a glance whether a long Cypress run is in progress or a quick tsc check.
  4. feedback_required — Claude is waiting for your answer. The task jumps into the Needs You column with a red border and a pulse. The question is rendered directly on the card.
  5. done — work is complete and verified.

Going back from testing to active is normal (bug found → fix → re-verify) and visible — you see the iterations, not just the outcome. Reopening a done task sends it to backlog first; the cycle then runs again from the top.

Lane

A Lane is a group of tasks that belong to one run — one multi-task launch from the app. Every running task is in a Lane:

  • A single task started on its own → a Lane with one tile.
  • A parallel Bulk Start of three tasks → three Lanes, one tile each.
  • A serial run (or an Epic start) → one Lane with the tiles connected by arrows.

Lanes are visible in the AI Now view. Once every tile in a Lane is done, the Lane disappears.

Epic and Subtask

A task with subtasks behaves as an Epic. Its chip in the list reads Epic · N, and its Start button no longer launches the parent — it schedules every open subtask serially in one Lane.

  • Add a subtask: hover a task row, click the small + button, type a title, hit Enter. The new task is linked to the parent.
  • Run the Epic: click Start on the parent. The subtasks run one after another in a single Claude session, in the order shown in the expanded Epic.
  • Or run a subtask alone: click Start on the subtask directly. It gets its own Lane and runs in parallel.
  • Close the Epic: Sightdeck does not auto-close the parent. When all subtasks are done (chip shows Epic · N ✓), close it explicitly from the detail panel.

Refinement and Planning Mode

Refinement runs automatically when you drop a rough idea into the quick-add field. Claude reads the input, splits independent topics into separate tasks, and writes a proper title, summary, kind, estimate, story points and Claude model for each one. You confirm or briefly edit, and the backlog has grown.

Planning Mode kicks in for the big ones. A task with story points 8 or higher — or vague scope — shows a pulsing Plan Epic button. Click it: a fresh Claude session opens and asks 2–3 focused questions about scope and acceptance criteria, then proposes a subtask breakdown. The parent stays in backlog throughout — Planning is preparation, not work. On confirm, the subtasks land under the parent and the chip flips to Epic · N. You decide when to launch them.

Story Points and Auto Model Selection

Story points measure complexity / uncertainty, not pure time. A one-hour task can be 5 points if it is fiddly; a three-hour task can be 3 points if it is straightforward.

Sightdeck uses the points to suggest a Claude model:

  • 1–2 points → Haiku (cheap, fast — typos, one-liners).
  • 3 points → Sonnet (balanced).
  • 5+ points → Opus (heavy lifting, refactors, architecture).

Override the mapping per project under Settings → Models → Task model detection, and override the model on a single task in its detail panel. Bulk runs with mixed models warn you before launch and propose the strongest of the selection.

Daily Workflows

Add a task

  1. Click New Task in the sidebar, or drop the idea into the Quick-Add field at the top of the backlog.
  2. Type — a sentence, a paragraph, even a pasted Slack rant. Hit Enter.
  3. Sightdeck creates the task immediately (it appears in backlog) and sends it to Refinement in the background. Independent topics become separate tasks; pieces that only make sense together become one Epic parent plus subtasks.
  4. While Refinement runs, the card shows a Refining… pill. When it settles, the title, summary, estimate, story points and model are filled in. Edit by clicking the card.

Reorder the backlog

Drag tasks up or down in the backlog list. The order drives both the single-task launch and Bulk Start: top of the backlog runs first.

Start a single task

Click the play button on the task. A fresh Claude CLI session opens in the right project directory, with the task prompt pre-loaded. The status flips to active and the task moves into AI Now.

Bulk Start

Select several backlog tasks via their checkboxes. The run bar appears at the bottom of the window with four options:

  • Run in parallel — one Claude session per task, all started at once. Best for independent tasks.
  • Run in order — a single Claude session works through the tasks back-to-back. Use when later tasks build on earlier ones.
  • Run with Autopilot — Sightdeck inspects the selected tasks for file overlap and picks the safe mode itself. Same files → serial; independent files → parallel.
  • Schedule… — opens a small dialog: pick a local date / time, and for multi-task selections a run mode. The app schedules the start via the OS scheduler and fires the run when the time comes.

The run bar also shows a recommendation pill that names the reason ("same files touched" / "independent files") before you click anything.

Sightdeck also detects clusters on its own: backlog tasks that look similar are surfaced as a collapsible band above the backlog with a ▶ Run button. One click launches the cluster as a tailored bulk run — no manual selection needed.

Watch AI Now

The AI Now view shows every running task as a live Lane of pill-cards. Colours map to the lifecycle: orange = working, cyan = testing, green = done, slate = scheduled. The Lane updates the moment Claude writes to the XML — no refresh, no polling.

Answer Needs You

When an agent stops to ask a question, the task moves into the Needs You column with a red border and a pulse. The question is on the card.

  1. Read the question on the card. Click for full context.
  2. Reply in the corresponding Claude session.
  3. The card clears itself — the agent picks up active automatically and continues.

If the question is about whether an existing test should be adapted, the card carries an extra red Test-Anpassung pill in front of the question so you know tests are involved before you click.

Integrations

Jira, GitHub, Linear references

Tasks can carry an external ticket reference: an external_id (AHSR-1234, gh-#42, lin-ABC-7) and an external_url.

  • Mention the ticket ID in the title or in Quick-Add — Sightdeck detects it automatically and adds the reference.
  • Drag a screenshot of a Jira / GitHub / Linear ticket into the chat. Claude reads key, title and acceptance criteria out of the image and creates the task with the reference filled in.
  • Click the reference badge on the card to open the original ticket.
  • Edit external_id and external_url any time in the detail panel.

Git branches and worktrees

A per-project Git setup, configured in Edit project → Git.

  1. Turn on Feature branch per task.
  2. Pick a branch pattern with placeholders {prefix}, {num}, {id}, {external_id}, {auto_id}, {type}, {slug}. Default: claude/{type}/{id}-{slug}. The live preview shows the next branch name as you type.
  3. Optional: Separate worktree per task — Sightdeck creates a sibling working copy at ../<repo>-<task-id>/ so several tasks can run without fighting over the same files.
  4. Optional: Push branch when done — pushes the branch to origin when the task moves to done.
  5. Optional: Squash commits — collapses the auto-commits Sightdeck makes during the task into a single commit on top of the branch base.

The branch is created the moment a task moves backlog → active. Auto-commits land on that branch at sensible checkpoints (after a green test run, before a risky refactor, once before done if there are pending changes). Failures are non-fatal — a missing git binary or a pre-commit reject becomes a history entry on the task; the work keeps running.

Webhook on done

Per project, configure a webhook URL in Edit project → Webhook. As soon as a task moves to done, Sightdeck POSTs a short JSON payload there. Wire it up to Slack, n8n, a deploy trigger, or your own script.

Caveman prompt mode

A compressed prompt style that cuts token usage by ~75% by dropping articles and filler. Toggle per project. Use when token budget matters and the team can read terse output.

Import / Export

Move your Sightdeck setup between machines:

  1. Settings → Data → Export writes a JSON with your projects, project groups and webhook configurations.
  2. On the target machine, Settings → Data → Import merges the JSON into the local setup. Existing entries are updated; new entries are added; nothing is deleted.
  3. Per-task data (tasks, concepts, attachments) travels with the repo itself via Git — not part of the export.

Setup

Multi-project view

Add as many projects as you want via Add Project. The sidebar lists them; the dashboard streams every project's tasks into one sorted view — filterable by status, kind and tag.

Project prefix

A short uppercase token (SD, MO, WB) prefixed to every task ID displayed in the app. Set on project creation, change in Edit project. Tasks themselves carry a numeric ID in the XML; the prefix is purely cosmetic.

Project language

en or de. Drives the language Claude writes task titles, summaries, concept files and history events in. The Sightdeck CLI itself stays in English — only the content Claude writes follows the project language.

Project tags

Short labels (website, skill, infra) you can attach to tasks for filtering. Set them per task in the detail panel or in bulk via Bulk Select.

Local-first data layout

Everything Sightdeck creates lives in your repo, in plain XML and Markdown:

  • .agents/sightdeck/sightdeck.xml — every task in the project.
  • .agents/sightdeck/tasks/<TASK-ID>.md — the concept file for each task.
  • .agents/sightdeck/attachments/<TASK-ID>/ — files you dropped onto a task (screenshots, PDFs, logs).

App-level settings (selected projects, theme) live in your user data folder (userData/sources.json), not in the repo. No telemetry, no forced account, no cloud sync. Uninstall the app and the XML files keep working.

Troubleshooting / FAQ

The skill did not fire — Claude is not updating the XML

  1. Open the project and run any Claude prompt.
  2. Check .claude/settings.json for a UserPromptSubmit hook pointing at bootstrap.py. If missing, reinstall the skill from Setup → Install Skill.
  3. Confirm ~/.claude/skills/sightdeck-ai/ exists. The skill is the ground truth — without it Claude has no way to write tasks.

A task is stuck in testing

A PreToolUse Bash hook auto-detects common test runners (PHPUnit, Vitest, Cypress, Playwright, make pr, …) and flips the status to testing before the tool fires. If the tool itself crashes, the status may not flip back. Either:

  • Let Claude continue in the same session (it will set the right status on the next message), or
  • Open the task in the detail panel and reset the status to active or backlog manually.

A branch was not created on active

  1. Confirm Feature branch per task is on in Edit project → Git.
  2. The branch is only created on backlog → active, not on testing ↔ active. If the task was already active before you turned the setting on, reopen it (done → backlog → active).
  3. Check the project directory is a Git repo. Sightdeck does not init one for you.

License activation fails

  1. Check the license code is the full string from your email — no trailing spaces.
  2. The activation requires one outbound HTTPS call to the license server. If you are behind a strict firewall, allow license.sightdeck.app.
  3. Each license activates up to two machines. If you used both, deactivate one in Setup → License → Manage before trying a third.

A subtask appears in two places at once

By design. When a subtask is in testing or feedback_required, the card bubbles up into the top-level "In Testing" / "Waiting for Review" group so a running verification or pending review is always visible. The nested row under the expanded Epic still shows the same task, dimmed, with a hint Also shown in: In Testing underneath. Pick whichever entry is convenient — they edit the same task.

Bulk Start refuses to launch

  1. All selected tasks must come from the same project. Cross-project bulk runs are not supported.
  2. Any task still in Refinement blocks the start. Wait for the Refining… pill to clear, then try again.
  3. If the Start Epic button on a parent stays disabled, one of its subtasks is still in kind unclassified. Run Refinement on each unclassified subtask, then retry.

Where is my data, exactly?

  • Per-project tasks, concepts and attachments: <repo>/.agents/sightdeck/. Commit them to git for sharing, gitignore them for local-only.
  • App settings: ~/Library/Application Support/Sightdeck/sources.json.
  • License activation: the same user-data folder, encrypted at rest.

Nothing leaves your machine without your action.