Using Shuttle

Shuttle organizes thought in two dimensions. Horizontally, a Loom (織架) is a document made of Threads (思緒) — chapters you walk through with ↑ and ↓ in the thread list. Vertically, every bullet is a Node (織點), and depth links (深度連結) connect nodes across threads so you can dive deeper and surface back. Your whole collection of looms is a Workspace (織坊) — that's also the unit of device sync.

The app has two modes. In viewing mode (the default), arrow keys navigate and nodes are read-only. Press Enter or i on a node to enter writing mode — a text editor — and Escape to save and drop back to viewing.

⌘K opens the command palette from anywhere — even while you're editing a node. It's the fastest route to almost everything: switching looms, creating threads, managing depth links, zen mode, sync, and sharing.

Typing does double duty: it filters commands, and at two or more characters it also fuzzy-searches all your node content. Enter jumps to a search result — and holding ⌥ while pressing Enter creates a depth link from the currently focused node to that result instead of navigating.

Viewing mode has two panes: the thread list (sidebar) and the content. ← and → move between them; ↑/↓ move through threads or nodes. Switch looms with ⌘B (the Loom Manager) or jump directly with ⌘1–⌘9. ⌘. toggles zen mode; ⇧⌘I opens Loomy, the built-in AI helper.

On a phone, swipe right to open the thread drawer and left to close it. While a node is focused, a bottom toolbar covers the essentials: previous/next node, todo, indent/outdent, more options, depth link, and edit/done.

⇧T creates a thread; ⇧⌥T creates a whole new loom. Inside a node, Enter splits it at the cursor, Backspace at the start merges it into the one above, and Tab/⇧Tab indent and outdent. Reorder nodes with ⌥↑/⌥↓ — that's the only way; dragging a node selects rather than moves.

⌘Enter cycles a node through todo states (none → unchecked → checked). In viewing mode the clipboard works on whole subtrees: ⌘C/⌘X/⌘V, and ⌘⇧C copies the entire thread. Pasting multi-line or markdown text splits it into nodes automatically; ⌘⇧⌥V pastes verbatim. Paste an image and it's stored as an asset. Markdown formatting works as you'd hope: ⌘B/⌘I for bold/italic while writing, ⌘1–⌘3 for headings, and typing a third backtick expands a fenced code block.

Outgrown a bullet? Palette → Convert Node to Thread promotes a node and its subtree into a thread of its own.

Create: focus a node and press ⌘L to open the Depth Link Manager, then search for the target and press Enter. Or use the palette trick above (⌥Enter on a search result). Or ⌘-click a thread or node reference in a Loomy reply.

Dive: on a node with exactly one link, ⌘→ takes you there (clicking the node's link indicator does the same). With more links, you pick from the manager. Surface: ⌘← pops you back to where you dove from.

Three distinct flows — pick by what you want (full detail on the Features page):

Sync My Devices (palette or app menu) keeps your whole workspace live on your own devices. Enable sync on the first device, then open the pairing link or scan the QR code on the next one. Note: joining replaces the joining device's local data (a backup is kept — "Restore previous workspace" undoes it).

Share This Loom Live (loom icon menu → "Share live…", or the palette) shares one loom with another person, live in both directions. Opening the dialog starts sharing immediately; send the invite link or QR. As owner you can stop new joins or remove a member at any time, enforced server-side.

Share a snapshot (⌘⇧S) hands someone a frozen, read-only copy of a thread, a loom, or everything — a short link that expires in 1, 7 (default), or 30 days.

Loomy runs on your API key (Anthropic by default, or Gemini), calling the provider straight from your browser — there's no Shuttle backend reading your thoughts. Set the key and model in Loomy Settings (the gear icon).

There are two ways to use it. The chat panel (⇧⌘I) is for building: it can create looms and threads, bulk-import structured content with hierarchy and depth links, search your nodes, analyze YouTube videos, and search the web. Thread and node references in its replies are clickable — and ⌘-clicking one creates a depth link from your focused node. Inline AI is for transforming: press ⌘K, type a request while a node is focused (or nodes are selected), and choose "Ask Loomy about this" — it reads the full node content and can rewrite it in place or add new sibling nodes.

Worth knowing the boundaries: chat Loomy cannot edit or delete existing nodes — rewriting is inline AI's job. Selecting nodes doesn't send their text to the chat (only a count); again, inline AI is the path that reads selections. And chat history doesn't survive a reload — use "Export to Thread" (in the clear-conversation dialog) to keep a conversation.

Nodes hold markdown: bold, italic, strikethrough, headings, links, blockquotes, lists, tables, and fenced code blocks with syntax highlighting — plus ```mermaid diagrams and ```plot function graphs. A single newline is a hard line break. Callouts use > [!note], [!tip], [!warning] and friends — or any emoji: > [!🧶] Yarn notes.

Checkboxes have one subtlety: [ ] task alone on a line is an interactive checkbox (click or ⌘Enter toggles it), while - [ ] inside a list renders but isn't clickable. Not supported: footnotes and reference-style links (they silently disappear), LaTeX, and raw HTML other than <img>.

Video threads: make a thread's title a YouTube URL (bare, or [My Title](url)) and the player embeds in the thread header. [m:ss] timestamps in that thread's nodes become click-to-seek buttons, and ⌘⇧T while editing inserts the current playback position. Map View: nodes containing a Google Maps URL with coordinates become place pins on a map panel (⌘⇧M). One catch: maps.app.goo.gl short links carry no coordinates and won't pin — open them and copy the full URL instead. X posts: embed with the image syntax, ![](post-url).

Paste images directly while editing — they're compressed, stored locally as assets, and synced via blob storage. The ThoughtWeave strip at the bottom of the sidebar shows every depth link in the loom as a two-column stitch; click either half to jump there.

The import format is plain markdown: a # Title line starts a new loom, --- separates threads, - bullets with 2-space indents build the hierarchy, #anchor-name at a node's end declares a link target, and [>>](anchor-name) creates a depth link. Without a # Title, content imports into your current thread.

Ways in: ⌘K → "Import Markdown" (paste, upload a file, or fetch a URL), App menu → Import (auto-detects share links, backups, and markdown — always merges, never replaces), and App menu → File → Load for .shuttle backups (asks Replace or Merge). Two merge behaviors worth knowing: a loom you already have is skipped (your copy wins), and merging never resurrects content you've deleted.

Ways out: App menu → Export gives a .shuttle backup (one loom or everything) or the current loom as markdown — and markdown export round-trips: depth links are written as anchors and recreated on re-import. For handing someone a copy, snapshot links (⌘⇧S) are usually simpler.

App menu → File → Connect Folder turns a folder into a home for multiple workspaces — one .shuttle file each, auto-saved 30 seconds after changes and when you leave. Switch between them with ⌘⇧O.

One real warning: switching workspaces (or creating a new one) saves the current one, then replaces your entire live database with the target — immediately, with no confirmation, and the change propagates to synced devices and live-shared looms like any other edit. Treat the switcher with the respect you'd give a "replace everything" button, because that's what it is.

Claude Code can read and write your Shuttle directly: claude mcp add wwwshuttle -- npx @wwwshuttle-app/mcp. On the production app you also need the bridge extension (App menu → Claude Code → Download Extension), the "Enable MCP" toggle, and a page refresh. Eleven tools cover listing looms, reading a thread's full contents, creating looms and threads, adding and updating nodes, search, context, and structured markdown import — everything additive, nothing destructive. The server also exposes a shuttle://usage resource: the canonical usage map, worth reading before generating Shuttle content. A Shuttle tab must be open; all data stays in your browser. Full details in the MCP tool reference.

Global

Viewing mode

Writing mode

Shortcuts are shown in macOS notation and are suppressed while a Chinese/Japanese IME is composing.