How Writ works

The same facts in more detail live in the repo's docs folder.

Install

Builds for macOS, Windows and Linux are on the download page with their checksums, or from a package manager:

brew trust ibrahemid/writ
brew install --cask ibrahemid/writ/writ
winget install -e --id ibrahemid.Writ
yay -S writ-bin
curl -fsSL https://github.com/ibrahemid/writ/raw/main/install.sh | sh

First launch

Writ asks two things before the first file. The format for new files: Plain text (.txt) or Markdown (.md). Then the apps, each with a switch, all off. Continue saves both and opens an untitled file in the chosen format. Both answers can be changed later in Settings, Files and Settings, Apps.

The hotkey

⌘⇧Space (Ctrl⇧Space on Windows and Linux) brings the window up over whatever is in front; the same keys put it away. Writ keeps running while the window is away, and it comes back on the tab you were on. Change the key in Settings, Shortcuts.

Files and the folder

Drag a file onto the window, double-click it in Finder once Writ is the default app, use Open File, or run writ path. Writ saves the file where it is, a second after you stop typing; ⌘S saves at once. Code, configs and logs open with highlighting for the language, binary files open read-only as hex, and very large files open with highlighting off.

Writ also has a folder of its own, ~/Writ unless you choose another in Settings, Files, Folder. New File (⌘N) creates a file there named writ- plus the date and time, in the format set in Settings, Files, Default format. Name it Groceries.md or Groceries.txt and the name decides the format. Today's File, in the File menu, opens a file named for the date. Delete moves a file to the Trash, and closing a tab keeps the file.

The folder is watched, so a change made in another program shows up at once. A file with unsaved edits asks before anything is replaced, and a save never overwrites a newer file: the unsaved text is written beside it as a dated copy instead. Drag another folder onto the window, or run writ . in it, and the sidebar shows its tree.

Markdown

A Markdown file opens in Inline mode: headings, emphasis, lists, checkboxes, links, images and code blocks are formatted where they are written, and the line you are editing shows its markup. Source shows the plain text. The status bar switches between the two, and so does ⌘⇧V; Settings, Preview sets which one a Markdown file opens in. Tables stay as written, with their columns styled.

Lists continue on Enter, a checkbox toggles on click, and ⌘B, ⌘I, ⌘K wrap the selection. In a Markdown file, [[File]] opens that file, [[Folder/File]] picks one of two with the same name, and [[File#Heading]] opens it at the heading. Typing [[ offers the files in the folder. Renaming a file offers to update the links that point at it.

HTML preview

An HTML or Mermaid file can show its source, the rendered page beside it, or the page alone. The status bar switches between Source, Split and Preview; the two panes scroll together, and ⌘⇧H puts the page below the source instead of beside it. The preview has no network access: a page cannot load anything from the web, and a link in it names its destination and asks before opening.

Search

⌘⇧F opens one palette over commands, settings, file names and the text of every file in the folder, plain text and Markdown alike. With a second folder open it adds that folder's file names and contents. Results are grouped by where they came from; Enter opens the match on its line.

• > limits the query to commands
• # limits it to file contents
• :42 jumps to line 42 of the current file

⌘F finds within the current file, and ⌘⇧O opens a file by name.

Versions

Writ keeps a version of a file in the folder each time it is saved. A run of saves inside ten seconds is one version. Versions are kept for thirty days, at most two hundred per file and 250 MB in all, in Writ's own data folder and never in the folder itself. A file over 2 MB is not versioned. Revert To, in the File menu, puts one back, and the restore is kept as a version too.

Default app

On macOS, Settings, Files, Open these file types with Writ has a box per group: Plain text & logs, Markdown, Config & data, Source code. macOS keeps the choice per file type. The guide on making Writ the app for .md and .txt covers Windows and Linux.

Command line

The writ command opens files in the running app. Install it from Settings, Advanced, Terminal command (macOS asks for an administrator password once to link it into /usr/local/bin).

writ todo.txt            # open a file
writ .                   # open the folder
pbpaste | writ           # stdin becomes a new file
make test 2>&1 | writ --title tests

Piped text is saved as a file in Writ's folder, so it stays after the terminal closes.

Watched folder

Point Settings, Advanced, Folder to watch for new files at a folder. Any file that appears there after that moment opens by itself and the window comes forward. Files that were already in the folder are left alone, and more than three arrivals in two seconds collapse into one notice. Turn off "Bring Writ to the front when a new file arrives" to keep arrivals quiet.

Spelling

Off until you turn it on in Settings, Editor. It runs on your machine. Double-click a flagged word to accept a correction, fix every occurrence, or add the word to your dictionary. Code, links and tokens like API are not flagged.

Apps

Settings, Apps has one switch per app. An app that is off has no menu item, command, shortcut or panel, and switching it on or off takes effect without a restart. Turning one off keeps its data for the next time.

• Connections. ⌘⇧\ opens a panel beside the file: the files that link to it, each with the sentence the link sits in, its outline and the properties from its frontmatter.
• Graph. Open Graph draws every Markdown file in the folder and the links between them, with a search box and a color per folder. With Connections on, the panel also shows the files near the open one.
• Tags. A sidebar list of the #tags written in the text or the frontmatter. Choosing one filters the file tree.
• Chat. ⌘⇧A opens a pane beside the file with that file attached; type @ to attach another. Only attached files are sent. When the model proposes an edit, the pane shows it as a diff, and Apply writes it through the same guarded path as every save, so a file that changed since is not overwritten. Conversations are saved in Writ's data folder, and the pane lists, renames and deletes them.
• Rewrite. Select text, right-click, Rewrite: proofread, rephrase, polish, or your own instruction. The result shows as a diff you apply or discard. Only the selection is sent.
• Connected programs. An MCP server for a client such as Claude Code or Cursor. The first call from a program waits until you approve it, and reading and writing are approved separately. Recent activity lists every call without the file's text. The guide walks through the setup.

Chat and Rewrite share one connection, shown under Apps while either is on: a provider, a key and a model. Ollama and LM Studio run on your machine and need no key. Anthropic, OpenAI, Google Gemini, OpenRouter, Groq, DeepSeek, Mistral, xAI, Together and Fireworks take your own key, kept in the system keychain on macOS and Windows; OpenRouter can also connect from a button that opens your browser. Any other OpenAI-compatible endpoint works by URL. Before anything reaches a host off your machine, Writ asks once, naming the host.

A folder written in Obsidian

Set Settings, Files, Folder to the folder Obsidian uses and the files open where they are. Links, properties and tags read as written, nothing is copied or converted, and Obsidian keeps working from the same folder. The guide lists what carries over, and Writ and Obsidian on one folder covers using both.

Appearance

Light, dark, or following the system, with six accents to choose from in Settings, Appearance. Interface text size is a setting of its own, and Zoom scales the editor and the rendered pane together.

Shortcuts

Every one of these can be changed in Settings, Shortcuts. macOS keys shown; Windows and Linux use Ctrl for ⌘.

Config

Everything in Settings is also in ~/.writ/config.toml, including which programs you approved. Logs are in ~/.writ/logs/. Writ checks for an update shortly after launch, at most once a day, and Settings, Updates turns the check off.