# Motion
> Manage your ocean of markdown.
Motion is a **local-first technical writing IDE**. It edits markdown on your own
filesystem, renders diagrams and queries inline, and can generate both from
natural-language prompts using CLI tools you already have installed.
## Features
### Editing
- **Three view modes** — WYSIWYG, syntax-highlighted Markdown, and Split, switchable at any time.
Edits carry across modes without loss.
- **Workspace management** — open a folder and Motion lists every markdown file
under it as a **collapsible directory tree**. **Search notes** filters by
filename or file contents (⌘K / Ctrl+K). Nested folders keep their shape.
The tree follows the disk: when another program adds, deletes, or renames a
note in the folder, the sidebar shows the change in about one second.
- **Finder Open With** (desktop) — right-click a `.md` in Finder → Open With
Motion. The workspace is the file's parent directory; the note is selected.
Last folder and last file are restored on the next desktop launch.
- **New Note** / **New Folder** — New Note writes `untitled-<timestamp>.md` in
the parent of the selected file (or the workspace root). New Folder writes a
`README.md` so the tree can show it.
- **Save** — labeled **Save** control in the toolbar, plus **⌘S** / **Ctrl+S**.
Status shows Saving… / Saved / Save failed.
- **Share** — publish the current note to a **GitHub Gist** or a **Notion**
page. Tokens stay on this machine (Settings in the Share menu).
- **Copy All** — copies the current note. Paste into a markdown editor to get
markdown; paste into Docs, Word, or Mail to get rich text. Header actions
are icon-only; the accessible name is unchanged.
- **Reload note** — re-reads the open file from disk. If the note is dirty,
Motion asks before discarding unsaved edits.
- **Export PDF / Word** — themed download of the current note. The dialog
previews the page first. Ice Snowstorm (ice page, black text, navy headings,
blue rules) and Clay (Anthropic ivory paper, terracotta accent) are built in.
**Themes** adds more and sets the export default. PDF uses standard fonts;
Word uses Calibri or Georgia. Tables export as a bordered grid with a filled
header row and striped body rows in both PDF and Word. Each theme sets the
table header, header text, row, alternate row, and border colors.
- **YAML front matter.** WYSIWYG hides a `---` block on the first line, and the
Markdown view shows it. Saves keep it unchanged. Export and the rich text
part of Copy All leave it out.
- **Images.** `` shows the image. Relative paths resolve
from the current note, then from the folder. Saves keep the link unchanged.
- **Markdown kept as written.** A save writes `- item` and `1. item` lists,
`## 1. Title` headings, and `snake_case` words as you wrote them, so an edit
to one line changes only that line in the file.
- **Note links.** Click a link to a markdown file on disk, and that note
opens. Relative paths resolve from the current note, then from the folder.
Web links stay web links.
- **Zoom** — ⌘+ / ⌘- / ⌘0 scale the editor and the file tree, not the header.
A brief overlay shows the percentage. Remembered in the settings file.
- **Layout** — the editor fills the window. Drag the sidebar edge or the Split
divider; both widths are remembered.
- **Rename** — New Note opens an inline name field. Right-click → Rename, or F2.
- **Rich markdown** — headings, lists, blockquotes, code blocks with syntax
highlighting, and **GFM tables**. Insert a 3×3 from the toolbar or `/tab`;
edit cells; add/delete rows and columns while the caret is in the table.
Pipe tables round-trip through save/reload.
- **Ask AI** — select text for a floating **Ask AI**, type `/ai` at the start of
a line, or use toolbar **Refine** for the whole document. Replies stream into
a preview (Replace / Insert below / Try again / Discard) before anything is
committed. Targeted edits (`replace_range`, insert after a block, table row /
cell) preview as a list; **Apply N edits** commits the batch. Uses the
Anthropic API when `ANTHROPIC_API_KEY` is set, otherwise `claude` on `PATH`.
### Content blocks
Five block types, insertable from the toolbar or by typing `/` at the start of a
line (the slash menu also lists **Ask AI** first, then **Table**). Blocks survive save/reload as
real blocks (not plain code).
| Block | What it does |
|---|---|
| **Mermaid** | Renders a diagram from Mermaid source, editable in place |
| **Dataset** | Registers a local CSV/JSON/JSONL file as a queryable table |
| **Query** | Runs SQL against registered datasets via DuckDB-WASM, in-browser |
| **Image gen** | Generates an image from a prompt via the `imagen` CLI |
| **Diagram gen** | Generates a Mermaid diagram from a prompt via the `claude` CLI |
Dataset/Query need the data files inside the **open workspace** (demo files ship
under `public/demo/`). SQL is restricted to `SELECT`/`WITH` with validated
identifiers and a clamped row limit — the query box cannot modify your data.
### Workspace synthesis
**Synthesize** summarizes every note in the workspace, clusters them by topic,
and writes a generated `TOC.md` and a short folder `README.md` back into the
folder (or `README.motion.md` if a hand-written README.md is already there).
Its own output is excluded from the input, so re-running does not feed the
index back to itself. Capped at 40 notes per run, and it reports what it
skipped. Needs `claude` on `PATH`.
### Safety
- Filesystem access is jailed to the folder you opened. Paths are canonicalized,
so `..` traversal and symlinks pointing outside the workspace are both refused.
- Rendered markdown and generated SVG are sanitized before insertion.
- Dev server binds to **localhost only**.
## Getting started
### Prerequisites
- [Bun](https://bun.com) 1.3+
- [Rust](https://www.rust-lang.org/tools/install) — only for the desktop build
- Optional, for Ask AI / generative blocks: `ANTHROPIC_API_KEY`, and/or the `claude` and `imagen` CLIs on `PATH`
```bash
bun install
```
### Running
Motion runs two ways, and the difference matters:
```bash
bun tauri dev # desktop app — real filesystem access
bun run dev # browser at http://localhost:3000
```
**Desktop (`bun tauri dev`)** is the real product: a native folder picker, and
reading and writing files anywhere inside the folder you open.
**Browser (`bun run dev`)** reads and writes real files too, against a workspace
directory set by `MOTION_WORKSPACE` (default `public/demo/`) instead of a folder
picker:
```bash
MOTION_WORKSPACE=~/notes bun run dev
```
Both modes go through the same rules, enforced by one shared contract that both
test suites run — so behaviour you see in the browser is behaviour the desktop
app is held to. That is what makes browser automation a meaningful gate rather
than a rehearsal. The server binds to `127.0.0.1`.
There is no hot reload. The dev server rebuilds the bundle when files change, but
the page does not refresh itself — reload manually.
Desktop packaging, Finder Open With, unsigned local builds, and the overlay
title bar are documented in [docs/macos.md](docs/macos.md).
## Testing
```bash
bun run verify # typecheck → client-bundle guard → unit tests → end-to-end
```
That one command is the gate. Individually:
| Command | Covers |
|---|---|
| `bun run typecheck` | `tsc --noEmit`, strict |
| `bun run guard:client` | rejects any `Bun.` API reachable from the browser bundle |
| `bun test src` | unit tests |
| `bunx playwright test` | end-to-end against the real dev server |
| `cd src-tauri && cargo test --lib` | the workspace filesystem jail |
End-to-end specs fail automatically on console errors, uncaught exceptions,
failed requests, and any response with status 400 or above — so a broken UI
cannot pass quietly. See `CLAUDE.md` for the full definition of done.
## Known limitations
Recorded here rather than discovered later:
- **Welcome demo datasets** use `sample-data.csv` / `sample-events.jsonl` when
those files exist in the open workspace. Opening an unrelated folder shows
"Demo data is not in this workspace" instead of a DuckDB/HTTP error; pick a
local CSV/JSONL or open Motion's demo folder.
- **No hot reload.** The dev server rebuilds the bundle on change but the page
does not refresh itself — reload manually.
- **Ask AI** uses `ANTHROPIC_API_KEY` when set, otherwise `claude` on `PATH`.
Generative blocks and **Synthesize** still need `claude` / `imagen`.
- **Share** needs a GitHub PAT (gist scope) and/or a Notion internal
integration token plus a parent page the integration can write to.
- **PDF export** uses Helvetica, Times, or Courier. Word uses Calibri, Georgia,
or Consolas. The on-screen preview uses system fonts, so it can look slightly
closer to the theme than the PDF does.
- **Images** load only from inside the open folder. The desktop app does not
load web images, because its content security policy allows only local,
`data:`, and `blob:` images. PDF and Word export show the alt text, not the
image.
- **Task list checkboxes** (`- [ ] item`) are lost when Motion saves the note.
The Markdown view also shows the note without them. Edit those notes in
another editor until task lists ship.
- **PDF tables** size each column by its longest cell text, counted in
characters, so a column of wide letters can wrap early. A single table row
taller than a page runs off the page. The header row repeats on each page.
See [CHANGELOG.md](CHANGELOG.md) for release history and
[docs/roadmap.md](docs/roadmap.md) for what is planned.
## Tech stack
- **Runtime:** Bun
- **Frontend:** React 19, TypeScript, Tiptap 3
- **Desktop shell:** Tauri 2 (Rust)
- **Data:** DuckDB-WASM
- **Testing:** Playwright, `bun:test`, `cargo test`
## License
See [LICENSE](LICENSE).