Tour

A 10-minute walkthrough from install to your first verified report.

This walkthrough takes you from zero to your first verified report in about 10 minutes.

1. Install Spinosa

Open a terminal and run:

curl -fsSL https://github.com/medialab/spinosa/releases/download/stable/install.sh | bash

This installs the spinosa command and all its dependencies (Bun runtime, document converters, OCR engine). After install, open a new terminal window.

2. Launch the dashboard

spinosa

This opens the Spinosa TUI (terminal UI) dashboard. If this is your first time, you'll see:

A welcome screen with the Spinosa logo and version
A list of workspaces (empty on first run)
A + New workspace button in the bottom-right area Press W or click Workspaces in the footer to open the workspace picker.

3. Create a workspace

In the workspace picker, click + New workspace. This starts the onboarding wizard. The wizard guides you through these steps:

Path — Enter the folder path containing your research documents (PDFs, Word files, images, etc.)
Name — Give your workspace a name
Tools — Verify that the document processing tools are installed (OCR, MarkItDown)
Scan — Spinosa scans your folder and classifies each file by type
Import — Select which file types to import
Setup — Workspace folder is created and registered 7–9. Convert — Files are copied and converted to markdown in phases
Provider — Choose which AI coding tool you use (Claude Code, OpenCode, Gemini, etc.)
Done — Summary of what was imported

Tip: If you already have a workspace folder, you can skip the wizard and just point the workspace picker to it.

4. Start a chat session

When the wizard finishes, you'll return to the home screen with a chat prompt at the bottom. Type a question about your documents, for example:

What did the interviews say about coastal erosion?

Press Enter to send. Spinosa's agents search your documents, assemble evidence, and return a markdown report.

5. Read the report

Every answer comes back with:

A direct answer to your question
Quoted evidence with source file paths
Analysis that separates interpretation from source text
A verification status showing whether the claims passed source checks
Limitations so you can judge scope and confidence You can navigate the report with ↑↓, open cited files, or ask follow-up questions in the same chat.

6. Visualize your session

Press W and select a workspace, then look for Visualizer in the top menu. The visualizer shows:

Files view (press 1) — heatmap of which files were accessed
Flow view (press 2) — graph of tool calls the agents made
Activity view (press 3) — timeline of the conversation Use +/- to zoom, click and drag to pan, and Enter to inspect details.