# Inkling

A markdown workspace that keeps every note as a plain file on your own disk, lets a crew edit one document live, and refuses to touch git unless a person presses push.

Domain: Our own · Inkling
Label: Running (our own)
For your content team. Inside: plain files on your disk · live co-editing · push only by a person

## Dated figures

- Version 0.2.3, Windows and Linux builds (recorded 2026-07-14)
- 144 commits across 86 tracked files (recorded 2026-07-11 to 2026-07-14)
- 8 test files, all of them about git or workspace safety (recorded 2026-07-14)
- No download count recorded (recorded 2026-09-14)

Inkling is OCTYN's own product, written in every day, with its server deployed and run by OCTYN.

## The situation

A notes app that owns the notes is the trap. The file sits inside a database that cannot be opened directly, the sync is a subscription, and the day the subscription stops, the writing is hostage. The other half of the trap is the opposite one: keep everything as plain files in a git repo and ownership comes with no live collaboration at all, because a shared file and a real-time session are not the same problem and git answers only one of them.

Inkling was started on 2026-07-11 to take both halves. Every note is a plain markdown file in a real folder on the writer's own disk, searchable the ordinary way and backed up by whatever already backs up that folder, and a crew can still sit in one document together.

## Why it was hard

Git is the hard part, and the danger is not merge conflicts. It is the automatic write.

The first version treated the local working tree as the live source of truth and pushed on an eight second debounce. The design note that killed that, written 2026-07-12, states the problem plainly: a bad autosave or a background operation can land in git with no human deciding to, and that is the one wrong move a document should never be exposed to. It also names the behaviour that fear produces in users, which is cloning the same branch several times so there is always a spare, and then having the same document in four places.

The second hard part is that real-time editing and branches disagree about what a document is. A live session is keyed to the document. A branch is keyed to the repository. A pair of writers can be in the same paragraph while sitting on different branches, and the system has to hold both facts at once without either writer discovering it the hard way.

## What was built

A desktop app with a plain, unframed editing surface underneath it and a live preview written for it, after moving away from an earlier approach that caused drag duplication, over-granular undo, and could not show raw syntax on the active line. The read view renders headings, anchors, diagrams and links between notes.

Live editing runs over a persistent connection keyed to the document, not the branch. A late joiner gets the current state on arrival. Every keystroke is also mirrored to that participant's own disk copy, so the connecting server is a relay and never the only place the writing lives.

Branches are the spine. Each repository-and-branch pair gets its own checkout on disk, so switching branch means switching directory. Nothing runs a checkout over anyone's uncommitted work, and several branches can be open at once. Push is a deliberate, confirmed act: it takes the session's current text and commits it to the branch that person chose. Nothing commits or pushes on its own anywhere in the design.

Around the editor: a multi-root file explorer, a command palette instead of a toolbar, twelve desaturated themes, tiling panes, a freeform canvas of note cards, and a map of notes and the links between them. An outside assistant can also read and edit the same vault a person is looking at, through a connection built for that purpose.

The assistant is provider agnostic and its key never ships in the client. Requests go through a proxy on OCTYN's own server, so the key can be rotated and the feature switched off remotely without anybody reinstalling anything.

## What it does under load

Plainly: not measured, and that is the state as of 2026-09-14. There is no download telemetry in the repo and no usage instrumentation, so there is no download count to publish and no concurrent-session figure. Publishing one would mean inventing it.

What can be stated with a date: version 0.2.3 on 2026-07-14, with Windows and Linux builds and an auto-update feed served from OCTYN's own server. 144 commits between 2026-07-11 and 2026-07-14, across 86 tracked files. The server is a container on the OCTYN VPS with its own volume, and it redeploys when a push to `main` touches the server directory.

The one load-shaped design decision already made: the live session is persisted, so the figure that matters later is participants per document, not documents per server, and nothing in the current build pretends to know what that ceiling is.

## What happens when it breaks

Of the eight test files in the repo on 2026-07-14, every one is about git or workspace safety, not editing: safe checkout, clone guarding, checkout paths, no-op pushes, root de-duplication, workspace state, and two about shared spaces. That distribution is the whole risk model written down. An editor bug loses a keystroke. A git bug loses a document.

The failure paths that follow from the model:

Lose the network and the editor keeps working, because the file is already on disk and autosave writes there. What stops is the live session, not the writing.

Lose the server and the same thing holds, and push still works, because push goes straight to the code host.

Edit a file from outside, with an assistant, a terminal or a pull, and the file watcher refreshes the tree and reloads clean open notes. It ignores writes the app made itself, so the app does not chase its own tail.

The push path is tested, not merely assumed safe: a push that would change nothing is one of the cases with a test against it, because a confirm dialog that promises to save the work and then does nothing is worse than an error.

The unresolved one, worth saying plainly: the desktop build carries no code signature yet, so Windows warns on first run. That is a cost paid by every person who downloads it and it is not fixed by anything in the code.

## Who maintains it, and what that costs in attention

The person who wrote it, which is the same arrangement as everything else here.

Steady state is quiet, because the parts that could page somebody are the parts that were deliberately made optional. Notes are local, so a server outage is a degraded feature and not an outage of the product. Git is manual, so nothing runs unattended against a repository.

What costs real attention is desktop packaging, and it is seasonal rather than continuous. The main process is bundled with all dependencies inlined specifically because module resolution failed inside the built app while working cleanly in development, a class of bug that only appears after shipping. Linux builds cannot be produced on Windows at all, so a release is a two-machine job.

## What changes when requirements change in six months

Configuration, no release: which model the assistant uses, whether the built-in assistant runs at all, and the update feed. All three are server side by design, which is the reason the proxy exists.

A small code change: another theme, another export format, another view over the same index. The renderer is plain modules, so a view is a file.

A larger code change: anything that alters what a document is. Comments, suggestions, or per-block permissions all sit on top of the live document and touch the branch model at the same time, and those two were deliberately kept apart.

A rebuild: a mobile or browser-only client. The whole premise is a real folder on a real disk, and a phone does not have one in the sense this design means. The shared editor that already runs in a browser is a viewer on a session, not the app.

## What we would do differently

Write the branch model first. The autosave-to-git version existed, was used, and had to be argued out of the product a day later, and the argument was won by a design note rather than by a fix.

Instrument downloads on day one. The claim made about this product is that people can have it, and there is currently no figure attached to that claim.

And settle on one editing approach before building on it. Two approaches sat in the dependency list at once for longer than was comfortable, one of them unused, which looks like optionality and is really an unmade decision.

## Related

- [The Consult](https://octyn.co/consult)

Canonical: https://octyn.co/casestudies/inkling