Write a whole book in your terminal, in plain Markdown. okashi is a
distraction-free writing app for long-form manuscripts — split your work into
chapters it keeps in order, brainstorm in an outline, read the whole thing
through, and export an agent-ready .docx or an elegant PDF. No database, no
proprietary bundle, no lock-in: it's just .md files in ordinary folders.
For writers who live in the terminal (vim, Markdown, plain text) and want a real manuscript workflow — ordered chapters, a corkboard, word-count goals, snapshots — without leaving the keyboard or handing their prose to someone else's cloud.
Plain .md files · manuscript-aware sidebar · live word counts · outline &
corkboard · RTF / PDF / DOCX export · full-screen focus — all from the command line.
Download the archive for your OS/architecture from the
Releases page, extract it, and put
okashi on your PATH:
# pick the file matching your OS/arch on the Releases page (darwin/linux, arm64/amd64)
tar -xzf okashi_*_darwin_arm64.tar.gz
sudo mv okashi /usr/local/bin/
okashi --versionOn macOS, if Gatekeeper blocks the unsigned binary, clear the quarantine flag once:
xattr -d com.apple.quarantine /usr/local/bin/okashi # or: right-click → Opengit clone https://github.com/snackztime/okashi
cd okashi
go build -o okashi . # build the binary
go run . # or run without installingComing soon.
okashi # open the writing app
okashi --version # print the version
okashi --help # show helpokashi opens in your writing folder (see Configuration for
where that is). The sidebar shows your documents and projects on the left; the
editor is centered on the right. Collapse the sidebar with ctrl+b for a
full-screen writing surface.
Saving: okashi autosaves as you write and shows a save indicator in the
status bar. Press ctrl+s to save explicitly at any time.
Snapshots: every file keeps a ring of timestamped backups in a .okashi-bak/
folder beside it. Select a file in the sidebar and press b to browse them —
preview any snapshot, take one on demand with n, or restore one with ⏎
(your current version is backed up first, so a restore is never destructive).
Press d to diff the selected snapshot against the current file, or D
twice to diff two snapshots — a scrollable, color-coded view (removed red, added
green, changed words highlighted) so you can see exactly what a draft changed.
| Key | Action |
|---|---|
ctrl+b |
Toggle sidebar |
ctrl+y |
Inspector tabs |
ctrl+l |
Outline (full-screen brainstorming — beats & notes) |
ctrl+k |
Corkboard (full-screen manuscript navigator); c from the sidebar |
ctrl+o |
Home (launch screen) |
esc |
Switch focus / back |
ctrl+c |
Quit |
| Key | Action |
|---|---|
ctrl+n |
New file (+ new, right-click / F2 rename) |
r |
Rename file |
M |
Move file or folder |
del |
Delete file |
d |
Duplicate file |
| Key | Action |
|---|---|
ctrl+s |
Save |
ctrl+t |
Typewriter scrolling (caret stays centered) |
ctrl+d |
Focus dim (dim everything outside the current sentence) |
ctrl+g |
Set goals |
ctrl+r |
Spelling suggestions |
| Key | Action |
|---|---|
ctrl+e |
Export (RTF · PDF · DOCX) |
ctrl+p |
Markdown preview |
t |
Toggle Tufte view (inside preview) |
| Key | Action |
|---|---|
ctrl+f |
Search (Tab to scope · ctrl+a all sources) |
The atom is one .md file. Larger structures are plain folders:
- Manuscript — a folder containing a
manifest.json. The manifest is the sole source of order and display titles. Files listed initemsare chapters; unlisted.mdfiles are Resources (visible but not part of the ordered view or export).ctrl+eexports the whole manuscript. - Category — a plain folder of unnumbered documents (no manifest). Good for loose notes, research, or reference material.
- Resources —
.mdfiles inside a manuscript folder that are not listed initems, or unnumbered files at the root or in a category. - Legacy manuscripts — a folder with no manifest but at least one
numerically-prefixed file (e.g.
01-opening.md) is recognized for display only: order by numeric prefix, titles de-slugged from filenames. This is a read-only transitional view; no structural writes are offered.
The left pane is a clean chapter list. In a manuscript, press ctrl+k (or c
from the sidebar) to open the corkboard — a full-screen spread of your
chapters, each a card with its word count and a synopsis (or its first line,
dimmed, until you write one). A header line shows the chapter count, total word
count, and — if you've set a project goal — your progress toward it; the card
you're currently editing is marked. On the corkboard:
⏎open a chapter ·eedit its synopsis ·J/Kreorder (staged;escthenyto apply, orescto discard)aadd / promote ·xremove (demote to a resource) ·rretitlectrl+eexport the whole manuscript ·escback
The read-through pager is m from the sidebar. The outline (ctrl+l) is a
separate free-form planning doc — jot beats and structure there before they
become chapters.
ctrl+n in a manuscript asks chapter or resource — a chapter is appended to
the manifest; a resource is an unlisted supporting doc, filed loosely or into a
folder (Characters/Aldous). Synopses live in a small .okashi-synopsis.json
beside your files; order lives in manifest.json.
Press ctrl+l to open the full-screen outline — a place to think before you
have chapters. It's a plain outline.md of two levels: each top-level bullet is a
beat, its indented bullets are notes. You type freely (list-continuation
included); alt+↑/alt+↓ move a whole beat (with its notes) up or down.
When a beat is ready to become a chapter, alt+↵ promotes it: okashi creates
the chapter in the current manuscript, seeds its synopsis from the beat's notes,
and checks the beat off (- [x] …). It's a one-way bridge — the outline is
your brainstorm, not a live index, so reordering chapters later in the corkboard
never rewrites the outline. The outline is also visible read-only in the inspector
while you write.
No lock-in. Your work is just Markdown files in ordinary folders, with a
small human-readable manifest.json for order and titles — no database, no
proprietary bundle. Everything is grep-able, diff-able, and git-friendly, and
reads perfectly well in any other editor. okashi writes files atomically
(temp-file + rename) so a crash or a synced-folder conflict can't corrupt them.
Stop using okashi tomorrow and your manuscript is exactly where you left it.
Press ctrl+e to export. Choose a style:
| Key | Style | Description |
|---|---|---|
m |
Manuscript | Double-spaced manuscript format for agents/editors (submit the .docx) |
t |
Tufte | Elegant serif, for a readable or printable copy |
Both styles produce a .rtf, a .pdf, and a .docx, written to <project>/export/.
(.docx is what most agents and editors ask for.)
When invoked from the outline, the full manuscript is exported (all chapters
concatenated). When invoked from the editor, only the current document is
exported.
A whole-manuscript Manuscript-style export opens with a standard title page:
your name and contact block (OKASHI_AUTHOR / OKASHI_CONTACT) top-left, an
approximate word count top-right, and the title centered below. Set
OKASHI_AUTHOR to also stamp your name into the running header. Single-chapter
exports skip the title page.
Press n (with a file selected in the sidebar) to open revision notes for that
chapter — jot "cut the flashback", "check this date", "too slow here". Add with a, edit
with e, delete with d. Notes live in a small .okashi-notes/ sidecar beside your files
and never touch the manuscript text, so they stay out of your prose and out of exports.
Set writing goals with ctrl+g: a daily word target, a project word target, daily
writing minutes, and an optional deadline. With a project target + deadline, the Goals
inspector tab shows a live burndown — "≈850/day to hit 80,000 by Mar 1" — that adjusts
as you write.
okashi keeps a per-project word-count history. The Goals tab shows a recent sparkline
and your current streak; press g (in the sidebar) to open the full writing-history
heatmap — a contributions-style grid of how much you wrote each day.
ctrl+p opens a rendered Markdown preview of the current document (powered by
glamour). The preview is read-only;
↑/↓ scroll, ctrl+p returns to editing.
Inside the preview, press t to toggle Tufte view — a book-style layout
that floats footnotes into margin sidenotes when the terminal is wide enough
to hold the text plus a right margin. The body stays at your writing measure; the
preview pane widens to accommodate the notes. On a narrower terminal, footnotes
fall back to numbered endnotes.
The preview theme follows your terminal background (dark or light). Override
with OKASHI_THEME=dark or OKASHI_THEME=light.
Press i on a project in the launch hub to open Properties — an editable screen for the
things you'd otherwise set via env vars:
- Title — the manuscript display title (written to
manifest.json; manuscripts only). - Author and Contact — your name and a multi-line contact block for the export title page,
saved to a personal
config.jsonin your OS config dir (macOS~/Library/Application Support/okashi/, Linux~/.config/okashi/) — set once, applies to every project. - Width and Smart quotes — per-project editor preferences, saved to
<project>/.okashi.json.
⇥ moves between fields, ⏎ edits, space toggles, ctrl+s saves, esc backs out. Both stores
are plain JSON you can read or edit by hand.
Each variable below is a default that the matching Properties field overrides when set. An env-only setup keeps working unchanged.
| Variable | Default | Description |
|---|---|---|
OKASHI_DIR |
(see below) | Override the writing folder — set this to point okashi anywhere |
OKASHI_WIDTH |
72 |
Editor column width, 20–200 (per-project override in Properties) |
OKASHI_SMARTQUOTES |
on |
Smart curly quotes as you type; set off, false, or 0 to disable |
OKASHI_THEME |
(auto) | Force dark or light for the Markdown preview |
OKASHI_ICONS |
(auto) | Glyph set: nerd (Nerd Font glyphs), plain (Unicode only), or unset for auto-detect |
OKASHI_AUTHOR |
(none) | Author name for the Manuscript running header + title page (editable in Properties) |
OKASHI_CONTACT |
(none) | Free-text contact block for the Manuscript title page (editable in Properties) |
okashi opens in a writing folder resolved in this order:
$OKASHI_DIR— set this to point okashi anywhere you like.- iCloud Drive —
~/Library/Mobile Documents/com~apple~CloudDocs/okashi, when iCloud Drive is enabled. ~/Documents/okashi— cross-platform fallback (iCloud off, or Linux).
The folder is created on first run and seeded with a sample manuscript under Demo/ (a
short piece, The Lighthouse) so you have something to explore — delete it whenever you
like. Until you create your own work, the launch screen shows a quick primer on okashi's
model (manuscript · category · notes).
okashi enables mouse reporting so the scroll wheel and click-to-focus work. This suppresses the terminal's native drag-to-select. Two ways to select text:
- Quick modifier drag — hold ⌥ Option (iTerm2 / Ghostty / Terminal.app) or Shift (most other terminals) and drag.
- Selection mode — press
ctrl+xto release okashi's mouse capture so a plain drag selects; a-- SELECT --marker shows in the status bar. Pressctrl+xagain to restore clicking.
Then ⌘C (or your terminal's copy key) to copy.
okashi runs anywhere. The outline and corkboard — reordering, promoting, navigating — all have keys that work on any terminal, including macOS Terminal.app, where the Option key types accented characters instead of acting as Meta:
- Moving things — reorder with
shift+↑/↓(a chapter in the corkboard, a beat in the outline;J/Kalso works in the corkboard). Promote a beat withctrl+p. Thealt+↑/↓/alt+↵aliases are a convenience on Meta-capable terminals (iTerm2, Ghostty, kitty, WezTerm, Alacritty). To use them in Terminal.app: Settings → Profiles → Keys → Left Option key → Esc+. - Nerd Font glyphs degrade to plain Unicode automatically on Terminal.app and
the Linux console (override with
OKASHI_ICONS). - Truecolor renders best in a 24-bit terminal; through tmux, enable
RGB/Tc.
MIT — see LICENSE.
Copyright (c) 2026 Michael Pentz.