Spinosa is a local research workspace for people who work with document collections — interviews, field notes, PDFs, reports, transcripts. You ask questions in plain language. AI agents search your files, draft answers, and verify every claim against the original text.
No cloud, no uploads. All processing happens on your machine.
Spinosa was built at médialab Sciences Po for researchers who need to extract, compare, and verify information across hundreds of documents. It works for:
- Social scientists analysing interview transcripts, field notes, or survey responses
- Journalists cross-referencing leaked documents, reports, and public records
- Legal researchers reviewing case files, rulings, and evidence bundles
- Anyone with a folder of PDFs who needs answers grounded in their own sources
If you have a research question and a folder of documents, Spinosa gives you a terminal-based workspace where an AI assistant reads, searches, and writes reports — while a dedicated verifier checks every claim back against the originals.
LLMs are good at answering questions. They are bad at knowing where their answers came from. Spinosa solves that by giving the AI a structured workspace on top of your actual files — so every answer traces back to a source you provided.
The design is local-first. No documents leave your machine. The workspace is a folder on disk. The agents communicate through files, not hidden memory, so their work is inspectable and auditable.
# 1. Install (macOS / Linux)
curl -fsSL https://github.com/medialab/spinosa/releases/download/stable/install.sh | bash
# 2. Launch the dashboard
spinosaThe first time you run spinosa, you'll see the workspace picker. Click + New workspace and follow the 11-step wizard: choose your document folder, name the workspace, verify the document converters are installed, review what was found, and select your AI coding tool (Claude Code, OpenCode, Gemini, Ollama, etc.).
When the wizard finishes, a chat prompt appears. Type your first question.
| You have... | Spinosa gives you... |
|---|---|
| 200 PDFs from field research | A searchable workspace that knows every file |
| "What did participants say about X?" | A report with quotes, source paths, and a verification badge |
| Concerns about accuracy | Every claim checked against the original file by a dedicated verifier |
| New files later | Add them without starting over — the workspace updates in place |
The main conversation view. Type a question, get a report back with evidence quotes, analysis, and a verification status. Reports are rendered inline — you can read, scroll, or ask follow-ups in the same thread.
Press W to see all your registered workspaces in a sortable table. Each row shows the workspace name, parent folder, setup status, framework version, and last access time. Use Delete stale to clean up entries pointing to deleted folders.
An 11-step guided flow that takes you from a folder of raw documents to a fully indexed workspace. It scans your files, classifies them by type (text, Office, PDF, image), runs the appropriate converters, and prepares the workspace for chat.
Press I to add new documents to an existing workspace. The wizard runs the same conversion pipeline as the initial setup — scan, classify, convert, and integrate.
Three view modes:
- Files (
1) — heatmap of which documents were accessed during a session - Flow (
2) — graph of tool calls the agents made, in sequence - Activity (
3) — timeline of the conversation
Use + / - to zoom, drag to pan, and Enter to inspect individual tool calls.
Press A to see which agents are available and switch between them. The orchestrator selects the right agents automatically based on your question, but you can also configure custom pipelines.
Press K to connect your preferred AI provider (local via Ollama/oMLX, or cloud via OpenAI, Anthropic, Google, GitHub Copilot). Press M to switch between configured models.
| What you want | How |
|---|---|
| Launch the TUI | spinosa |
| Create a workspace from the terminal | spinosa create ~/research/papers |
| Add more files | spinosa add ~/research/more-papers |
| Update the framework | spinosa upgrade |
| List workspaces | spinosa list |
| Check system health | spinosa doctor |
PDFs, Word docs, spreadsheets, presentations, EPUB, HTML, ZIP, Outlook messages, images (OCR), CSVs, Markdown — all converted to searchable text.
- macOS or Linux
- ~500 MB disk space for the framework and dependencies
- An AI model provider (local or cloud)