GRASPPY Capture User Guide

GRASPPY Capture is a small Mac app that finds the AI coding conversations already stored on your computer and turns them into clean, readable Markdown files — in one folder you own.

Claude Code, Codex, and Cursor each keep a full record of every session on your machine. Those records sit in hidden folders, in formats built for programs rather than people: line-delimited JSON logs and databases. The work is all there — the decisions, the fixes, the reasoning — but reading it back is nearly impossible.

Capture solves exactly that:

• It finds your conversations automatically. No exports, no copy-paste. It scans the known provider folders and lists everything it found.
• It converts each one to plain Markdown. Every conversation becomes an ordinary .md file with a readable name, clear message markers, and a metadata header.
• It keeps the archive current. Run a sync whenever you like — conversations that haven't changed are skipped, so re-syncs take seconds.

The result is a permanent, portable archive of your AI work. Open it in any editor, search it from the terminal, drop it into Obsidian, or commit it to git — they're just files.

Three promises define Capture, and all three are verifiable rather than taken on trust.

Free. There is no price, no trial, no tier, and no upsell inside the app. You don't create an account, and the app never asks for an email.

Local. Capture makes no network requests while cataloging or syncing. Your conversations never leave your computer — not to us, not to anyone. The single exception is the Check for Updates menu item, which runs only when you click it and sends nothing but a version query to GitHub. Nothing runs in the background: if the window isn't open, Capture is doing nothing at all.

Open source. The complete source code is public under the GPL-3.0 license at github.com/grasppy-labs/grasppy-capture. You can read exactly what the app does — or build your own copy from source.

Capture is made by Grasppy Labs, the makers of Grasppy. It works entirely on its own; a Grasppy account is never required.

What you need

What you do not need

• No account or sign-up of any kind
• No internet connection for cataloging or syncing
• No Grasppy subscription — Capture is fully standalone

Platforms in progress

A Windows version is in progress — the app's core is portable, and packaging is underway. Intel Macs are not supported in the current release.

Get the app

1. Go to grasppy.com/capture and click Download for macOS — or download directly from the GitHub Releases page.
2. Open the downloaded .dmg file.
3. Drag GRASPPY Capture into your Applications folder.

The download is about 116 MB. Every release on GitHub shows a SHA-256 checksum next to the file, so you can verify the download if you want to.

Building from source instead

Because Capture is open source, you can skip the download entirely and build it yourself:

git clone https://github.com/grasppy-labs/grasppy-capture.git
cd grasppy-capture
npm install
npm start

Both routes give you the same app.

The first time you open Capture, macOS will block a normal double-click. This is expected: the build is not notarized with Apple (notarization requires a paid Apple Developer subscription, and Capture is a free app). It is a one-time step to tell macOS you trust it.

The one-time step

1. Open your Applications folder.
2. Right-click (or Control-click) GRASPPY Capture.
3. Choose Open.
4. In the dialog that appears, click Open again.

From then on, the app opens normally with a double-click or from Spotlight.

If you don't see the Open option

On newer macOS versions the dialog may only offer Done on the first try. Right-click → Open a second time, or go to System Settings → Privacy & Security, scroll to the security section, and click Open Anyway next to the GRASPPY Capture message.

On first launch, Capture asks one question: where should your archive live?

Pick any folder you like — Desktop, Documents, a synced drive folder. Capture creates a folder named GRASPPY Capture Archive inside it, and that is the only place it will ever write. Your original conversation files are opened read-only and never modified, moved, or deleted.

Choosing well

• Pick somewhere you'll find again. The archive is meant to be opened, searched, and browsed — not buried.
• A cloud-synced folder works fine. If your chosen folder is inside iCloud Drive, Dropbox, or similar, your archive gets backed up automatically. The syncing is done by that service, not by Capture.
• You can always get there in one click. The Open Archive Folder button at the bottom of the Archive view opens it in Finder.

Once the folder is chosen, Capture scans your providers and shows everything it found. Nothing is written yet — that only happens when you press Sync Now.

The Archive view is Capture's home screen. From top to bottom:

Archive shows where your archive lives on disk, with the time of your last sync on the right.

Sources shows one card per provider — Claude Code, Codex, and Cursor — with its status and how many conversations were found. Ready means the provider's folder was read successfully. If a provider isn't installed on your Mac, its card simply reports that nothing was found; that's normal.

The conversation table lists every conversation Capture discovered, with:

When you open the app, the table appears instantly from Capture's own records — then a fresh scan of your providers runs in the background and updates it. The scan is read-only; the button says Checking… while it runs, and nothing is written to disk.

Three tools above the table help you find any conversation quickly.

Status filters. The Pending / Synced / All buttons switch the table between conversations waiting to be archived, conversations already archived, and everything. Each button shows its count.

Search. The search box matches as you type, against both the short ID and the conversation name. Paste an ID from an archive filename to jump straight to its row.

Platform filter. The dropdown beside the search box narrows the table to a single provider — All platforms, Claude Code, Codex, or Cursor.

Sorting. Every column header is clickable. Click once to sort ascending (▲), click again for descending (▼). Sort by Size to find your biggest conversations, by Activity to see the most recent, or by Provider to group them.

All three combine: you can filter to Pending, narrow to Codex, and search a name fragment at the same time. The footer under the table always tells you how many of the current filter's conversations you're seeing.

Not everything belongs in the archive. The Exclude checkbox on any row keeps that conversation out of every future sync.

Three things to know:

• Exclusions are remembered. Once checked, a conversation stays excluded across app restarts until you uncheck it.
• Excluding never deletes. If a conversation was already archived, its Markdown file stays exactly where it is. Exclusion only stops future syncs from touching it.
• Excluded rows stay visible. They appear crossed out in the table, so you always see the complete picture of what exists versus what you've opted out of.

There is no bulk-exclude in the current release — exclusions are per conversation, one checkbox at a time.

Nothing in Capture syncs automatically. Files are written only when you press Sync Now. Here is exactly what a sync does:

1. Takes stock. The pending, non-excluded conversations are collected. Everything already synced and unchanged is skipped — this is why re-syncs finish in seconds.
2. Converts each conversation. The original file is read, parsed, and rendered as Markdown.
3. Validates before writing. Every rendered document is checked against Capture's format rules — message counts, markers, structure. A conversation that can't be rendered correctly is reported, never silently mangled.
4. Writes atomically. Each file is written completely or not at all. An interrupted sync never leaves a half-written file, and a failed conversation never overwrites a previous good copy.
5. Reports. The banner shows the result — how many files are new, updated, unchanged, or still pending.

If a conversation changes later — you keep working in Claude Code, say — it automatically returns to Pending, and your next sync picks up the new version. First-time syncs of a large history can take several minutes; after that, syncs are quick.

The most important thing to understand: no status ever means your data is lost. Needs re-archive in particular reads more alarming than it is — your conversation is intact; only Capture's copy of it is being scheduled for a rewrite.

If you sync while a conversation is still open in its app — a Claude Code session running in your terminal right now, for instance — that conversation will stay Pending. This is deliberate.

A conversation that is actively being written changes on disk while Capture reads it. Archiving a file mid-change would produce a truncated, half-written copy — worse than no copy at all. So Capture checks whether the file changed during processing, and if it did, it sets the conversation aside and preserves whatever was previously archived.

Nothing is lost and nothing needs fixing. The conversation simply waits. The next time you run Sync Now while that conversation is idle — the session ended, or you're just not typing into it — it archives normally.

A practical habit: sync at the end of a work session rather than in the middle of one, and everything goes through on the first pass.

The Dashboard's calendar shows your conversations laid out by day, with two views switched by the toggle in the card header:

• Synced — conversations by the day they were archived.
• Last updated — conversations by the day you last worked on them. This is the interesting one: it lays out months of your actual work history, with the busiest days shaded darkest.

Reading the calendar

• Shading shows intensity — the more conversations on a day, the deeper the color.
• Hover any day for a tooltip listing that day's conversations by ID and name.
• Click a day to print its conversation list under the grid.
• The ‹ › arrows move between months, with each month's total shown in the bar.

At the top of the Dashboard, four cards summarize the archive: files in the last sync, data written, total Markdown files, and total archive size.

Archive by provider shows how your archive divides across Claude Code, Codex, and Cursor — file counts and storage per provider, with proportional bars. It answers "where does my AI work actually happen?" at a glance.

Recent syncs is the log of your completed manual runs, newest first. Each row shows when the sync finished, its results — how many files were new, updated, and unchanged — plus how many files were checked and how much data was written.

A reassuring pattern to recognize: a sync that reports mostly unchanged and writes 0 B is the system working perfectly — it checked everything, confirmed your archive is current, and wrote nothing because nothing needed writing.

Every archived conversation is one Markdown file with a stable, predictable name:

claude-code--Backtesting-executor-parity--64c91278-….md
   provider          readable label            session ID

The name never changes between syncs, so links and references to archive files keep working. The short ID in the middle matches the ID column in the app, which is how you connect a file on disk back to its row in the catalog.

Inside, every file begins with a self-describing header:

# Markdown Export - Claude Code

**Provider:** claude-code
**Messages:** 330
**Session ID:** 64c91278-…
**Short ID:** 64c91278
**Source Updated:** 2026-07-16T00:57:35Z
**Conversation Turns:** 165

Below the header, the conversation itself flows as alternating message blocks — 👤 USER MESSAGE and 🤖 AI RESPONSE — each numbered, in order. Code blocks, tool activity, and images are preserved in readable form.

The entire point of plain Markdown is that nothing special is needed to use it. Some things people do with their archive:

• Open it anywhere. Any text editor, any notes app, any Markdown viewer, on any machine — today or in twenty years.
• Search it from the terminal. grep -r "connection pool" "GRASPPY Capture Archive/" finds every conversation that ever discussed connection pools.
• Drop it into Obsidian or Logseq. Point your vault at the archive folder and your AI history becomes linked, searchable notes.
• Commit it to git. The archive versions beautifully — every sync becomes a meaningful diff of your AI work.
• Feed it back to an AI. Paste an old conversation into a new session to restore context. This is also exactly what Grasppy automates, if you ever want the archive to become searchable, analyzed knowledge rather than raw files.

One rule keeps all of this safe: treat the archive as Capture's output. Edit copies, not originals — a hand-edited archive file will be flagged on the next scan as needing re-archive, and rewritten from the source.

"Local only" in Capture is not a policy promise — it is how the app is built.

• The interface cannot reach the internet. Capture's window runs with networking structurally disabled, enforced by the engine the app runs on. There is no analytics call, no telemetry, no "phone home" — the capability itself is absent.
• Cataloging and syncing are entirely offline. Finding conversations reads your local provider folders; archiving writes to your local archive folder. You can run Capture with Wi-Fi off and everything works identically.
• Your originals are read-only. Capture never modifies, moves, or deletes anything in your Claude Code, Codex, or Cursor folders.
• The code is public. None of the above needs to be taken on faith — the full source is at github.com/grasppy-labs/grasppy-capture, and the GPL-3.0 license guarantees it stays open.

The one place Capture touches the network is the Check for Updates… item in the ⋯ menu — and only when you click it.

What happens: the app asks GitHub's public releases API one question — what is the latest published version? — and compares the answer to the version you're running. The request carries no personal data, no conversation data, and nothing about your archive. There is no background polling: if you never click it, Capture never makes the request.

The menu itself says it plainly: Runs only when you ask. Nothing about your conversations is sent.

1. Click the ⋯ menu in the top-right corner of the app.
2. Choose Check for Updates…
3. If you're current, a dialog confirms it. If a newer version exists, the dialog offers Download… — clicking it opens the release page in your browser.
4. Download the new .dmg, open it, and drag GRASPPY Capture to Applications, replacing the old copy.
5. Launch as usual.

Updates never install themselves — the download and the drag are always your explicit actions. Your archive and settings are untouched by an update: the new version picks up exactly where the old one left off, and your first scan afterward confirms everything is still in sync.

New releases are also announced on the GitHub Releases page, where you can read what changed before updating.

Almost always: the conversation is still active. A session that's open in its app keeps changing on disk, and Capture refuses to archive a file that changes while being read — a half-written archive would be worse than a late one. See Why Active Conversations Wait for the full explanation.

What to do: nothing, usually. Finish or pause the session, run Sync Now again, and it goes through.

If it stays Pending even when idle: check the status column for a more specific state — Permission needed means macOS is blocking folder access; Incomplete means the source file ends mid-record. Both have their own entries in this chapter's status table. If a conversation repeatedly fails across multiple syncs while idle, that's worth reporting — open an issue on GitHub with the conversation's short ID from the ID column.

This status is the app repairing itself — not data loss.

Needs re-archive means Capture re-checked an archived Markdown file and found it invalid or outdated: perhaps it was written by an older version of the app with a rendering flaw, or the file was hand-edited, or it went missing from the archive folder. Your original conversation is untouched and fully intact — only Capture's copy needs redoing.

What to do: run Sync Now. The file is rewritten fresh from the source, and the status returns to Synced.

This is Capture's integrity check working as designed: every scan re-validates the archived files themselves, so a damaged archive is detected and queued for repair automatically instead of sitting silently broken.

"GRASPPY Capture can't be opened because it is from an unidentified developer" — this is the expected first-launch experience, not a problem with your download. The build isn't notarized with Apple, so macOS asks you to confirm trust once.

The fix: right-click the app → Open → Open. One time only; afterwards it launches normally. The First Launch On macOS section walks through it step by step, including the System Settings route for newer macOS versions.

Why isn't it notarized? Notarization requires a paid Apple Developer subscription. Capture is a free, open-source app — the trade-off is this single extra click. If you'd rather not trust a downloaded binary at all, the repository lets you build the identical app from source yourself.

The one-click answer: the Open Archive Folder button at the bottom of the Archive view opens your archive in Finder.

The path: inside the folder you chose at setup, Capture created GRASPPY Capture Archive. The full location is shown at the top of the Archive view, under the ARCHIVE heading.

Finding one specific conversation: note its 8-character ID in the app's table — the archive filename contains the same ID. Searching the archive folder in Finder for that ID lands on exactly that file.

If the archive folder was moved or deleted: Capture detects that its files are missing and marks affected conversations Needs re-archive. Run Sync Now and the archive is rebuilt from your original conversations — which is also your reassurance that the archive is always recoverable, because the sources remain the truth.

Windows: in progress. Capture's core — the discovery, conversion, and validation engine — is written portably and has no Mac-specific dependencies; what remains is Windows packaging and testing. Watch the GitHub repository for progress, or open an issue to add your voice — interest genuinely helps order the queue.

Intel Macs: not supported in the current release, which ships for Apple Silicon (M1 and newer) only.

Linux: not currently planned, but the same portability note applies — and as an open-source project under GPL-3.0, a community port is both possible and welcome.

Other AI tools: Capture currently reads Claude Code, Codex, and Cursor. For AI conversations in your browser — ChatGPT, Claude.ai, Gemini, and others — the Grasppy browser extension covers what a local-files app cannot see.