Pick up your project where you left it

Workroom turns scattered notes, PDFs and links into an organised Obsidian vault of plain Markdown files, and teaches your AI agent to keep it that way.

  • One-time purchase
  • Plain Markdown you own
  • Runs on your computer
Workroom Dropmenu bar shelf
  • PDFinsurance-guide.pdf
  • MDrepair-cafe-visit.md
  • MDdeep-research.md
  • WEBownership-models.html
  • TXTrota-ideas.md
  • MDmembership-idea.md

On your computer, no agent

Filed as source notes

6 new notes in Research

Agent Workspace / Research
Notetypelocatorstatus
How tool libraries lend equipmentsourcesections 2–4draft
Who covers insurance?question—open
Insurance guide for community groupssourcepp. 6–11draft
Visit to a repair cafésourceyour notesdraft
Deep research: lending modelssourceagent reportdraft
Community ownership modelssourcepart 1draft
Volunteer rota ideassourcefrom a chatdraft
Membership ideasourcepasted textdraft
Rota ideasTool librariesRepair caféDeep researchOwnership modelsInsurance guideWho covers insurance?Lending models compared

Draft by your agent · cites 3 sources

Lending models compared

  • Most tool libraries lend for a week and charge a yearly membership Deep research
  • A co-operative can hold one insurance policy for everything it lends Ownership models
  • Lent tools need cover beyond public liability Insurance guide
Example from a fictional project: each file becomes a Markdown note with its type, source and status. Integrate is offered after you keep them, never automatic; drafts cite source lines and wait for your review.

Every time you come back, you start over

Articles in Downloads. Ideas in a notes app. Half a plan in a chat. You hunt for the pieces, then explain the whole project to your agent again.

Workroom gives that material one structure: a map of the project, the sources behind each idea, and the questions still open. You and your agent both start from it.

Agent Workspace / MoCs / Research.md
  • MoCs
  • Research
type
map
title
Research
status
draft

Research

Home · Workflow · Research · Digests

Deliverable: a plan for a neighbourhood tool library: how lending works, who runs it, what it costs

Research framework: Field map

Three ways in

  • Five minutes: the deliverables below.
  • To argue with it: open questions, then sources.
  • To maintain it: the research log.

Deliverables

  • Maps by theme
  • Glossary
  • Who to read
  • Playbooks

Folders

  • Sources
  • Entities
  • Questions
  • Log
  • Terms
  • Playbooks
An example vault from a fictional project: click any note or link to move around it. MoCs are the map notes that hold a project together. Every note is plain Markdown: the links work in Obsidian or any other editor, and your agent reads the same file. Click through a finished demo vault →

One conversation, one vault

Install Workroom, open the agent you already use, and describe the project. It interviews you, proposes a structure, and writes nothing until you confirm.

What you get is a knowledge base in plain Markdown: every note filed with its source, maps that link it all together, easy for you and your agent to search and browse, and ready to turn into a website you can share.

  1. Install

    Unzip the kit and connect your agent. The setup interview runs in your browser, in the terminal or in your agent.

  2. Describe

    Answer a few questions about the project and the result you want. Drop existing files on the Workroom Drop app, or point your agent at them.

  3. Review

    Workroom shows every file it will create before anything is written, and applies the changes only when you confirm.

  4. Keep going

    Ask it to refresh the maps and check for broken links and duplicates. You choose what it may change.

Once Workroom is installed, start with a sentence like this

Use the guided-agent-workspace skill. I’m working on a project and have notes, articles and ideas scattered around. Help me organise them into a vault we can keep working in.

Ask, and your agent knows the way

Once the vault exists, every session starts from the map instead of from scratch, whether your agent runs in a desktop app, a terminal or a messenger.

Four example sessions with a fictional project, one per agent. Pick one to replay it.

  • HermesExamplemessenger

    You: What’s still open on the tool library project?

    Hermes: Two open questions: what a membership would need to cover, and who covers insurance.

    The insurance guide you saved is the closest source for the second one.

  • PiExampleterminal

    You: Bring in the three articles in my Downloads folder

    Pi: Two are new and wait in the inbox as source notes. One is already in the vault, so I skipped it.

    Accept the two? (y/n)

  • Claude CodeExampledesktop app

    You: Build a site from the tool library notes with the wiki layout

    Claude Code: Built a 7-page site in a new folder. Left out 3 private items: my instructions, a template and a draft you marked unpublished.

    Open the folder to review it before you put it online.

  • CodexExampleterminal

    You: Refresh the project map and check for broken links

    Codex: Refreshed the map and source links. Health check: 2 broken links, 1 note nothing links to, no duplicates.

    Fix the two links? (y/n)

Illustrative conversations with a fictional project, not recordings. An agent reaches your vault only through the files you give it access to. Tested so far: Claude Code and Codex in the terminal. The Claude Code desktop app and Hermes (shown here in a messenger) use the same instruction files and aren’t tested yet. Pi has its own rules and a read-only fresh-session check, but a full vault run isn’t tested yet.

Six formats to get you started

Choose by the result you want. Each format brings its own templates, navigation and working rules, and a finished demo you can click through.

  • Line drawing of a project map: a black square anchoring clusters of note dots, index cards and red open questions.

    Field map

    Build a connected view of an area: its vocabulary, sources, people and open questions. Source definitions stay apart from your own reading.

    You work with source notes, terms, people, questions, playbooks, a research log.

    Inside the demo vault 50 notes, 33 of them in these folders

    • Sources8
    • Terms8
    • Entities8
    • Questions6
    • Playbooks2
    • Log1

    One open question Can the council require shielded fixtures on private forecourts?

    Open the Millbrook field map
  • Line drawing of a central document card linked to columns of evidence cards, one conflicting pair linked in red.

    Dossier

    Investigate a company, organisation or other bounded subject. Connect claims to evidence and keep conflicting accounts visible.

    You work with sources, entities, claims, evidence, questions, a research log.

    Inside the demo vault 46 notes, 30 of them in these folders

    • Claims11
    • Sources8
    • Entities5
    • Questions5
    • Log1

    One open question Does MAXTRA PRO remove PFAS at the claimed rate?

    Open the BRITA claim dossier
  • Line drawing of a ledger in four parallel rows, one red exception shifting a decision.

    Evidence ledger

    Track what you expected against what actually happened. Keep the evidence, the proposals and your final decisions as separate records.

    You work with expectations, evidence, proposals, attributed decisions.

    Inside the demo vault 55 notes, 36 of them in these folders

    • Expectations8
    • Evidence8
    • Sources5
    • Proposals4
    • Entities4
    • Decisions3
    • Questions3
    • Log1

    One open question Is the year-end gap real or a timing effect?

    Open the library hours ledger
  • Line drawing of a reference column compared with a matrix of documents, gaps marked by red dashed circles.

    Corpus comparison

    Compare documents of one kind against a reference set you choose. Record what you collected, what you couldn’t access, and the gaps.

    You work with document records, a reference set, coverage and overlap results.

    Inside the demo vault 47 notes, 30 of them in these folders

    • Entities14
    • Documents12
    • Questions3
    • Log1

    One open question Are the missing syllabi hiding unique readings?

    Open the AI literacy corpus
  • Line drawing of four chapter cards fed by source notes, one red open question inside a chapter.

    Book manuscript

    Develop a book from research and ideas with a trail back to the sources. Organise chapters, claims and exercises.

    You work with sources, ideas, chapter records, claims, exercises.

    Inside the demo vault 49 notes, 30 of them in these folders

    • Ideas8
    • Chapters6
    • Sources5
    • Entities3
    • Exercises3
    • Questions3
    • Translations1
    • Log1

    One open question Does the five-minute fix generalize beyond the workshops?

    Open The Repair Habit outline
  • Line drawing of a timeline of artifact cards splitting into two accounts at a disputed date marked in red.

    Personal biography

    Bring together episodes, artifacts and different accounts of a life. Keep uncertain dates and separate reports from interpretation.

    You work with sources, artifacts, people, episodes, interpretations.

    Inside the demo vault 44 notes, 26 of them in these folders

    • Episodes7
    • Artifacts5
    • Sources4
    • Entities3
    • Interpretations3
    • Questions3
    • Log1

    One open question When did the night sessions happen?

    Open Mira Vale’s biography

Other pathways. The setup interview also offers a general project workspace, small daily actions, and learning through questions and practice.

Nothing joins the vault until you say so

Drop something on Workroom Drop and it goes straight in: dropping it is your yes, and Undo takes it back for a few seconds. What your agent brings in, a file, a folder or a web page, waits in an inbox for you. Either way, each piece becomes a source note that records where it came from.

Line drawing: a stack of incoming documents passes through a narrow gate and is filed into an ordered column linked to a black square; one document, outlined in red, is held back before the gate.
  • Every source keeps its origin

    Each note remembers the file or link it came from and when you brought it in. Bring the same article in twice and the copy is skipped.

  • You decide what comes in

    What you drop goes straight in, with a moment to undo. What your agent brings waits in the inbox. A newer version of a source is proposed beside the old one, never written over it.

  • Your notes stay yours

    Workroom writes only the notes it manages, in its own folder, and shows a preview first. Everything is plain Markdown.

Keep what you find without leaving what you’re doing

Workroom Drop is a small Mac app that lives in your menu bar. Its shelf floats over any app, so saving something to your project takes one drag, and you never stop to open a folder or start your agent.

Each thing you drop becomes a Markdown note that records where it came from. You get a few seconds to undo it. Anything that needs a decision waits for you, and a red circle appears in the menu bar.

Downloads

A page in your browser

Tool library

Drop files, links or text

⌘V to paste

    The Workroom Drop shelf for a project called Tool library, with a dashed drop area and three items below it.

    Drag anything onto the shelf, or try a file, link or text of your own: this page reads only the name of a file, and nothing is uploaded.Tap an item to drop it on the shelf. A working copy of the shelf with a fictional project; the notes follow what Workroom writes.

    What it’s for

    • Keep a page as you read

      Drag a link out of your browser. The note keeps the page’s text, its address and the date, so it’s still there if the page changes.

    • Save an answer from a chat

      Copy a useful reply from any AI chat and press ⌘V on the shelf. It stops being a thread you’ll never find again.

    • File a PDF report

      Drop it and the text is extracted on your computer, with an exact copy of the original kept beside the note.

    • Capture a whiteboard

      Drop a photo or screenshot. The image is kept as it is, and your Mac reads any words in it into the note.

    • Watch a folder

      Point Drop at a folder, such as the one your scanner saves to. New files come in while Workroom is open, and the files themselves stay unchanged.

    • Run several projects

      Switch workrooms from the menu bar, so the thesis material doesn’t end up in the tool library.

    Read the vault in its own window

    Open the viewer from the menu bar or the top of the Drop window, and the workroom opens as pages: every note in a sidebar, each one shown with its links and properties, and a search across them.

    Click something you’ve just dropped and the viewer opens on its note. It reads the Markdown files on your Mac and refreshes when the vault changes, so you don’t need Obsidian or a browser tab to check what came in.

    The Workroom viewer window: a sidebar listing the folders and notes of a workroom, and a note called My research project open beside it with its rules and an outline of the page.
    The viewer in Workroom Drop, open on a test workroom called Field trip.

    Keep one workroom on two Macs

    Workroom Drop can keep a workroom in step between two Macs, such as a laptop and a Mac mini. It includes Syncthing, a free tool that copies the folder directly between your computers. On the same network, a saved note reached the other Mac in about 3 seconds when we tested it.

    To pair them, choose Add a Mac on the one that has the workroom and Join a workroom on the other, then check that both show the same four-digit number. Both Macs can read the vault at any time. One changes it at a time, and the other takes over only when you ask.

    Tested on one MacBook Pro and one Mac mini. If both change the same note while they aren’t connected, both versions are kept. An edit made just before a takeover is saved together with the other Mac’s changes, and taking over before its last changes arrive can repeat its last scheduled run once. Obsidian Sync and iCloud Drive aren’t supported or tested yet. How to set it up, and the limits

    A panel from Workroom Drop titled Field trip on your computers. It lists two Macs: this Mac, and a second one marked Online now, same network. A line below says these Macs sync only over Tailscale or the same network.
    From the About window of a development build, for a test workroom synced between two Macs. The Macs’ names are covered.

    What it works with

    Text
    Markdown, plain text and other UTF-8 text files, or pasted text
    PDF
    Up to 100 MB, converted on your computer with pdftotextOptional Marker OCR for scans and complex layouts.
    Images
    PNG, JPEG, GIF, WebP, HEIC, TIFF, BMP
    Web pages
    Any http or https link, read straight from the site or through Firecrawl if you connect itIf neither works, the note keeps the link and title.
    Other files
    Word, Excel and similar files are kept as they are, with no text extracted
    Agents
    Claude Code and Codex in the terminal: testedThe Claude Code desktop app, ChatGPT Work and Hermes use the same instruction files and aren’t tested yet. Pi gets its own rules and a read-only fresh-session check; a full vault run isn’t tested yet.
    Editors
    Obsidian, with optional Dataview views, or any Markdown editor
    Two Macs
    One workroom kept in step between two Macs with Syncthing, which Workroom Drop includesObsidian Sync and iCloud Drive aren’t supported or tested yet.
    Web research
    Firecrawl, Tavily and Browserbase, connected to your agent
    Deep research
    OpenAI, Gemini and ParallelNot yet verified against the live services.
    Other agents
    Read-only access to the vault through MCP
    Publishing
    Static HTML or an Astro project, synced with the Vercel, Netlify, Cloudflare or GitHub command-line toolsSyncing isn’t yet verified against these hosts.
    You need
    Python 3.9+ and Node.js 18+ on Mac, Windows or Linux, tested on macOS so farWorkroom Drop needs macOS 11 or later on Apple silicon. Git is optional.

    Turn part of the vault into a website

    Choose the notes and build a website on your computer, with five layouts, search and a graph of linked notes. Drafts and private files are always left out. Nothing is uploaded: you look it over, then decide where it goes.

    Line drawing: on the left a small network of notes around a black square with three items set apart in dashed outlines; on the right the same network redrawn as web pages, without the dashed items.

    Add a module when you need it

    Optional and off by default. Anything that reaches the web or a model runs only when you ask.

    One price, yours to keep

    Install it in your agent and start with what you’re working on today.

    €49once No subscription · 180 days of updates
    • The Workroom kit: the tool, your agent’s instructions and a setup guide, in one folder
    • The setup interview, in your browser, in the terminal or in your agent
    • Workroom Drop, a small Mac app you drop files and folders on
    • A vault structure your agent maintains: project maps, note templates and optional Obsidian views
    • Intake for files, folders and PDFs, plus refresh, health check and digest
    • Website export with five layouts, search and a graph of linked notes
    • Every release published in your 180 days
    Buy Workroom · €49

    The download link arrives by email and on the page after purchase; no account needed. Releases you download are yours to keep. Licence · Terms of sale · Company licences on request.

    Works with
    Claude Code, Codex, ChatGPT Work, Hermes, Pi or any other modern agent
    You need
    Any agent, on Mac, Windows or Linux: the core runs wherever Python and Node do, tested on macOS so far.
    A Mac for the Workroom Drop desktop app (macOS 11 or later, Apple silicon). Windows is coming.
    Licence
    One person, up to three computers, family sharing included

    Before you buy

    Made by one person, in Berlin

    I’m Gleb Kalinin. I build and teach practical ways to work with AI agents, and help people with or without a technical background turn ideas into useful tools, processes and services. In my cohorts we start with a real goal, build around it, and use human judgment to decide what works.

    Workroom began as the setup I wanted for my own projects. When you write in with a problem, the person who answers is the person who fixes it.

    How does my agent process my material?

    Workroom runs on your computer and never uploads your files. Your agent is different: most agents run on a hosted model, so the text it reads from your vault is sent to that model’s provider, for example Anthropic or OpenAI. Text it never reads is never sent, and with a local model nothing leaves your computer.

    What do I need to run Workroom?

    A computer with Python 3.9 or later and Node.js 18 or later, plus an AI agent that can read and write files on it: Claude Code, Codex, ChatGPT Work, Hermes, Pi or any other modern agent. Not sure whether your computer has Python and Node? Ask your agent to check; the buyer guide shows what to do if one is missing. The core runs on Mac, Windows and Linux; so far it is tested on macOS. Git is optional, for local version history, and Obsidian is optional. The optional Workroom Drop desktop app needs a Mac: macOS 11 Big Sur or later on Apple silicon. A Windows version is coming.

    Do I need Obsidian?

    No. Your vault is ordinary Markdown, so any Markdown editor will do. If you use Obsidian, the optional Dataview views work there, and every view also has a plain-link alternative.

    Does Workroom import my existing notes?

    It doesn’t copy your vault. When you start, you choose a new vault or a selected part of an existing one, and Workroom adds a managed area beside your notes. After that you bring in material piece by piece: a file, a folder, a web page or something your agent found. Each becomes a source note waiting for your acceptance.

    Will it change notes I’ve written?

    Workroom itself doesn’t. It only writes the notes it manages, in an Agent Workspace folder, and shows a preview first. If you edit one of its notes, it refuses to overwrite it and tells you which one. A health check only reports what it finds.

    Your agent is separate: it can edit any file you give it access to when you ask it to. Give it access only to the folders that belong to the project.

    How does an update reach a vault I’ve already built?

    Each vault keeps its own copy of Workroom, so you upgrade it with one command from the new release, or ask your agent to. It shows what will change, keeps a backup inside the vault and records the change in the vault’s history.

    Who can use Workroom, and on how many computers?

    Private individuals and small businesses can use Workroom, including for paid work. A small business here means under €1 million in annual revenue and under €1 million raised from investors in the last 24 months. One licence covers one person on up to three computers, and private buyers can share it with their family. Larger organisations and public bodies need a company licence: write to gleb@salient.community. The licence and the terms of sale are the binding wording.

    What happens when the 180 days of updates end?

    You keep everything you downloaded, and it keeps working; releases published afterwards aren’t included. Workroom is maintained by one developer, not a company. The plan is to keep shipping updates, but there’s no promise of releases past your window. Workroom may be released as open source at some point; that’s a possibility, not a commitment. Your vaults are plain Markdown and stay readable either way. The terms of sale are the binding wording.

    Elimination research

    Pick a product, tool, service or vendor by criteria you set, and see why each option was ruled out.

    Line drawing: six candidate cards pass through three narrow gates; at each gate some drop out with a small cross, until one card remains, marked in red.
    1. Your criteriaYour agent interviews you for what matters and your hard limits
    2. CandidatesCollected with dated sources
    3. RoundsA check ranks them by weighted score; every elimination keeps its reason
    4. Your choiceOnly you mark a candidate as chosen
    You work with
    One note per criterion, candidate and head-to-head round; eliminations with their reasons; a decision note on the vault’s index.
    Pictures
    Product pictures are off unless you ask.

    Open the turntable shortlist →

    Deep research

    Turn your project’s goal into a research brief and run it with a service you choose. The report comes back as an attributed source, not as finished knowledge.

    Line drawing: a goal becomes a brief, then a prompt held under a viewing frame for review, then travels out to a distant service and returns as a report filed among source cards.
    1. A briefWritten from your project’s goal
    2. The exact promptYou review it before anything runs
    3. A runWith the service you choose, started by you
    4. A source noteThe report, attributed, beside your other sources
    You work with
    A brief, a reviewed prompt, a record of each run, and the returned report as a source note.
    What leaves your computer
    Preparing the prompt happens on your computer. Nothing is sent until you start a run yourself.

    Research tools

    If your agent already has last30days, the Firecrawl CLI or a deep-research skill, it runs the tool and hands the saved output to Workroom.

    Line drawing: a magnifier, a funnel and a terminal window each send a line to a saved document card; one card is marked in red, waiting for review.
    1. Your agent asksIt says which tool it will run and what it will contact
    2. The tool runsThrough your agent, not through Workroom
    3. Source notesWith the query, the date and the original links
    4. Your reviewThey wait in the inbox until you accept them
    What leaves your computer
    Whatever the tool contacts, which your agent names before it runs. Workroom itself does not fetch anything here.

    Ask the vault

    Give a vault its own read-only agent. It searches and reads your notes, then answers with links to the notes it used.

    Line drawing: a question in a speech bubble fans out to a grid of notes; three are outlined in black and lead to an answer card with three footnote marks.
    1. A questionFrom the private viewer, or from another agent you give a token
    2. Search and readOnly your notes, and only reading
    3. An answer with linksTo every note it used
    You work with
    Answers that cite your notes, and tokens you issue to other agents.
    What it needs
    Node.js 22.19 or later and a pi sign-in, on top of what the rest of the kit needs.
    What leaves your computer
    With a hosted model, notes your privacy settings keep local are never sent, and the answer says so.

    Add your own

    Any command-line research tool or script can become a module: a search tool you already pay for, a scraper, a script of your own.

    Line drawing: a row of identical module blocks with one open slot marked in red; a new block carrying a fingerprint symbol slides toward it beside a short checklist.
    1. A manifestWhat the tool takes, whether it reaches the network, what it costs
    2. Register and approveOnce, by you
    3. PinnedTo the exact program and its fingerprint
    4. Asked before it runsThe first network call in a session shows the tool, where it connects and the cost
    Changed program, switched off
    Edit the manifest or replace the program and the tool stays off until you approve it again.
    Limits
    Spending limits are set per tool. A misspelled or missing setting denies rather than defaults.
    Examples included
    The kit ships manifests for the Firecrawl CLI and last30days.
    Where results go
    Output arrives as source notes with the query, date and links, like any other source.

    Read access for other agents

    Let another agent search, read and query your notes, without changing them, through the Model Context Protocol (MCP).

    Line drawing: a locked cabinet of notes; two agents on the right reach in through a narrow window with dashed lines that only read.
    1. You connect a clientNothing starts until you configure one
    2. It searches and readsSearch, note reading and frontmatter queries
    3. It never changes anythingNo writing, moving, publishing or fetching
    Scope
    Limited to what you would publish, unless you choose private scope.

    What leaves your computer

    Your vault is a folder of plain Markdown files on your computer, and Workroom itself runs locally: it never uploads your files.

    Line drawing: a laptop holding a folder of notes; two dashed lines lead to outside services, each with a switch; a separate line carries text to a remote model server.
    Stays on your computer
    Your vault, setup and everyday workflows. Workroom never uploads your files.
    Leaves only when you start it
    Fetching a web page sends its address to a web service you connect, such as Firecrawl, Tavily or Browserbase. A link dropped on Workroom Drop is read straight from its own site unless you’ve connected Firecrawl. The picture picker sends your search, the passage and the candidate pictures to Jev, a vision model run by typesafe.ai, and fetches candidates from Wikimedia Commons, Unsplash or Google.
    Goes to your agent’s provider
    Most agents run on a model hosted by a provider such as Anthropic or OpenAI. Whatever your agent reads, with your question, is sent there to be answered. Text it never reads is never sent. With a model on your own computer, nothing leaves it.

    Treat anything you point your agent at as if you had typed it into the provider’s own app. Workroom doesn’t see or control what the provider does with that text; your own agreement with the provider covers it.

    The same material, before and after

    Sixteen notes, articles and ideas kept in four places become one vault: a project map, linked sources and open questions.

    Before Scattered material

    DownloadsNotes appChat historyBookmarks

    After One vault, one map

    Project map
    • Project map
    • Idea or working note
    • Source
    • Open question

    Illustrative diagram with a fictional project, not a screenshot. You choose the pieces: your agent brings each one in as a source note that records where it came from, and you accept it before it joins the vault. Linking sources to ideas is work you and your agent do together.

    Add a managed area beside your notes

    Create a new vault, or add a managed area to the one you already use.

    Workroom doesn’t copy or reorganise your existing notes. The notes it manages live in an Agent Workspace folder; yours stay yours to edit, in plain Markdown, in Obsidian or any other editor.

    Before One folder selected

    Selected folder

    After A map links them

    Selected folderRest of the vault
    • Project map
    • Note
    • Open question
    • Rest of the vault

    Illustrative diagram, not a screenshot. You choose which part of an existing vault to work with and review the proposed changes before they’re applied.

    What Workroom creates

    Ordinary Markdown files with typed frontmatter, plus the instructions your agent needs.

    Line drawing: a folder tree drawn with orthogonal lines beside one note opened up to show a header block above its body, linked to two other notes.
    • Agent Workspace
      • MoCs
        • Home.md
        • Research.md
        • Workflow.md
        • Digests.md
      • Research
        • Sources
        • Questions
        • Terms
        • Log
      • Research project.md
      • Upkeep.md
    • AGENTS.md or CLAUDE.md, HERMES.md: instructions for your agent
    • .git local history
    A research vault, simplified. Your own notes sit beside this, untouched.
    Vault types
    A general project vault, daily actions, a learning pathway, or a research format (dossier, ledger, field map, corpus, biography or manuscript), chosen in a 5- or 15-minute interview.
    Structure
    Maps of content, typed frontmatter and optional Dataview views, each with a plain-link alternative.
    Agent instructions
    An instruction file for the agent you use, so it knows the vault’s structure and rules.
    Upkeep
    Refresh rebuilds maps and source links. A health check reports broken links, orphans, frontmatter problems, duplicates and stale notes without editing anything. A digest lists what changed and what’s still open.
    History
    New vaults get their own local Git repository. Nothing is pushed anywhere.

    Which agents work, and how

    Any agent that can read and write files on your computer, in a desktop app or in a terminal. Chat apps that can’t open files on your computer, such as ChatGPT in a browser tab, aren’t supported.

    Line drawing: five different agent windows in an arc, all connected to one ordered vault cabinet, with an instruction sheet pinned beside it marked in red.
    Installs into the agent you use
    Workroom writes an instruction file so your agent knows the vault’s structure and rules.
    Tested so far
    Claude Code and Codex in the terminal, each with an automated fresh-session check. Hermes has its instruction files; its messenger use isn’t tested. The Claude Code desktop app isn’t tested yet. Pi has its own rules and a read-only fresh-session check; a full vault run isn’t tested yet.
    Only the folders you allow
    Each agent reaches your vault only through the folders you give it access to.
    What your agent sends to its provider
    Most agents run on a hosted model. Whatever text the agent reads is sent to that model’s provider, for example Anthropic or OpenAI. Text it never reads is never sent; with a local model, nothing leaves your computer.

    PDFs, web pages and the Drop app

    Bring material in from files, folders, PDFs and web pages. Each piece becomes a source note that waits for your answer.

    Line drawing: a PDF page, a web page and loose files fall onto a dashed drop window; a clean column of source cards comes out, one marked in red, waiting for your answer.
    1. Drop or pointOn the Workroom Drop shelf, or ask your agent
    2. Converted on your computerAn exact copy of the original is kept
    3. A source noteIn your vault, or in its inbox when your agent brought it
    4. Undo, accept or discardUndo a drop for a few seconds; accept or discard what your agent brought
    PDFs convert on your computer
    Text is extracted page by page with pdftotext, or with the optional Marker OCR for scans and complex layouts. Compare the text with the PDF before you accept it. PDFs up to 100 MB; the file is never sent to an online service.
    Web pages, when you ask
    Drop a link on Workroom Drop and it keeps the page’s text, read on your computer straight from the site, or through Firecrawl if you’ve connected it. Agents fetch pages through a web service you connect, such as Firecrawl, Tavily or Browserbase.
    Workroom Drop, a small Mac app
    It lives in the menu bar: a floating shelf takes files, folders, links, text and images, and the menu switches between workrooms. Drop also picks up the setup interview from your browser and creates or connects the vault. It doesn’t start an agent, and the only thing it sends anywhere is a dropped link’s address, to Firecrawl, if you’ve connected it.

    How outside text is handled

    Imported notes are marked as external, and your agent is instructed to treat them as material, not as instructions.

    Line drawing: an incoming document carrying a hidden hooked mark, in red, passes two gates and is tagged; most documents file into a column, one flagged document is set aside in a dashed enclosure.
    1. Marked externalEvery imported note says it came from outside
    2. Read as materialYour agent is told not to follow instructions inside it
    3. QuarantineWhen a screening check is set up, flagged items wait outside the vault
    4. Release or discardYour decision

    This lowers the risk from instructions hidden in a web page or document; no tool can rule it out.

    How publishing works

    Before Your vault

    AGENTS.mdTemplatespublish: false

    After Your website

    index.html
    • Project map
    • Note
    • Not published
    • Web page

    Illustrative diagram, not a screenshot. Links that point to unpublished notes are listed in the build report.

    What’s included
    By default, only the notes Workroom manages. Add selected folders or notes, or the whole vault.
    Always left out
    Hidden folders, templates, agent instruction files and notes marked publish: false. A report lists every exclusion and every link to something unpublished.
    Layouts
    Wiki, docs, landing, course and a Tufte-style reading layout, each with light and dark themes. An Astro project can be exported instead of plain HTML.
    Readable anywhere
    Open the pages from disk or put them on any static host. Search and a graph of linked notes are included; no fonts or scripts are fetched from the internet.
    Pictures
    Search Wikimedia Commons, Unsplash or Google and let Jev, a vision model run by typesafe.ai, choose the picture that fits the passage. It sends your search, the passage and the candidates, and runs only when you start it. Each picture’s author and licence is printed underneath.
    Deployment
    Workroom builds a folder on your computer. It never uploads or deploys anything.

    Full specification

    Everything Workroom does, in one place.

    Exploded line drawing: the vault as stacked layers for files, structure, instructions and history, with callout lines; the history layer is marked in red.

    Your files

    Files
    Ordinary Markdown with typed frontmatter. Workroom keeps the notes it manages in an Agent Workspace folder. Obsidian is optional, and Dataview views have plain-link alternatives.
    Vault types
    A general project vault, daily actions, a learning pathway, or a research preset (dossier, ledger, field map, corpus, biography or manuscript), chosen in a short interview (a 5- or 15-minute route).
    Version history
    New vaults get their own local Git repository. Nothing is pushed anywhere automatically.
    Leaving
    Your notes are plain Markdown. A clean export makes a ZIP of your content without Workroom’s runtime, agent instructions, logs or hidden settings.

    Your control

    Changes you review
    Creating or adapting a vault is shown as a preview first and applied only when you confirm. Conflicting edits to managed files are refused.
    Agents
    Workroom writes an instruction file for the agent you use, so it knows the vault’s structure and rules.
    Upkeep
    A refresh rebuilds the maps and source links Workroom manages and lists notes nothing links to. A health check reports broken links, notes nothing links to, frontmatter problems, duplicates and stale notes without editing anything; turn it on in your upkeep settings. A digest note lists what changed and what is still open. Each runs when you ask, or your agent offers it when a session starts. Nothing runs in the background unless you set it up: a recurring digest, weekly for example, is configured separately.
    Updates
    Each vault carries its own copy of Workroom, so a new release doesn’t change it by itself. One command upgrades a vault: it shows what will change, keeps a backup inside the vault, and stops without changing anything if you’ve edited notes Workroom manages.

    Where it runs

    Where work runs
    Setup and everyday workflows run locally, without a model service. Your agent works with the material you give it access to, through its own provider. Two optional features contact outside services, and only when you use them: fetching web pages through a web service you connect, and the picture picker.
    Requirements
    Mac, Windows or Linux with Python 3.9 or later and Node.js 18 or later for setup and vault workflows; tested on macOS so far. The site builder needs Python only. Ask the vault needs Node.js 22.19 or later and a pi sign-in. Workroom Drop needs macOS 11 Big Sur or later on Apple silicon. A Windows version is coming soon.

    Publishing

    Site export
    Static HTML with relative links, built without network access; the same vault gives the same output. Optional Astro project output.