Margin: A Markdown App Which Collaborates With You

A second mind in the margin and collaborator for writers.

Comment

Inspiration

Margin draws on J.C.R. Licklider’s idea of human-computer symbiosis and Apple’s Knowledge Navigator: computing that expands a person’s capacity to think. Licklider kept track of how his time was used when working He found that "about 85 percent of my 'thinking' time was spent getting into a position to think, to make a decision, to learn something I need to know": mechanical activities like searching and making calculations to prepare himself for thinking.

I kept running into the same interruption in AI writing tools: most AI tools take the form of an assistant the user directs, which then actually does the writing. While helpful, I want a writing app which lets me write, but removes the friction for me in thinking through what I am trying to say, and makes my writing better. I wanted the intelligence to meet the writer inside the document. Margin gives the model a focused role there: research, read closely, and offer editorial judgment tied to the text.

It is built for a writer who cares about prose, evidence, and control over every change, and to explore a different interaction model for AI.

What it does

Margin is a writing tool that lets the writer stay in the flow writing, so they can focus on the idea, not mechanical and prepatory work. Directed by the user, Margin performs research and creaties tables, charts and illustrations, as they write. The writer can describe what research they want performed and how they want it presented using a #[] syntax, and keep writing—Margin will research and fill it in in the background. Margin also ambiently helps the writer notice relationships, test an argument, and find evidence, to strengthen their writing.

As an editor, it identifies consequential shifts, tensions, and open threads. Each observation is anchored to the passage that prompted it. The document review presents Margin’s interpretation as an argument spine: three to seven claims from premise to conclusion, each linked to an exact passage and assessed as grounded, developing, contested, or open. The writer can correct a claim and see which later claims depend on it. Margin then uses that correction to prepare a revision plan. Local findings can be discussed, refined, dismissed, resolved, or applied with a visible diff. Authored prose changes only after an explicit action.

As a researcher, it responds to #[] directives placed in the prose. A directive can request a sourced table, chart, diagram, editorial image, or interactive widget. Margin begins preparing the result after the writer pauses. Insert replaces the directive with Markdown and portable assets, including concise source captions and static fallbacks.

How we built it

The client uses React and CodeMirror. Custom editor decorations position findings, rendered tables, computed previews, completed-change diffs, and interactive widgets inside the writing surface. Browser-local companion state preserves documents and editorial state; the source itself remains Markdown.

An Express server handles every OpenAI request. It uses the Responses API, GPT-5.6 models, web search, and schema-constrained outputs validated with Zod. It also enforces timeouts, retries, request limits, and security headers. The API key stays on the server. A labeled deterministic path keeps the demonstration available during provider outages.

Charts, diagrams, and widgets are serialized as portable assets with editable JSON specifications and static SVG or Markdown fallbacks. The production app is packaged in a multi-stage Docker image and deployed as one same-origin service on Render.

How GPT-5.6 is used

GPT-5.6 performs the work that requires interpretation. It researches the web with a preference for primary sources, returns validated specifications for computed media, identifies local findings, extracts the argument spine, maintains issue discussions, and plans document-wide revisions from the editable brief and the writer’s corrections.

Generated images use a GPT-5.6 editorial brief and accessibility metadata before the OpenAI image model creates the final asset.

How Codex was used

Codex was the primary engineering collaborator. In the main build task, it operated the application, traced CodeMirror and persistence behavior, reproduced UX failures from screenshots, implemented the OpenAI and editor integrations, revised interactions after user testing, created the portable media pipeline, added safeguards and tests, deployed the service, and verified the public judge path.

The entrant set the product direction and made the consequential design decisions. The document opens first. Notes stay anchored to their source passages. Research inserts at the point of use. Model interpretations can be challenged. Prose changes require approval and include a diff. Rich formats export with Markdown and normal asset files.

Challenges we ran into

The central challenge was deciding how an AI should participate in writing. The writer had to remain in control of the draft even when the model was doing substantial work. Every model action therefore needed a visible basis: a finding anchored to a passage, an argument claim the writer could correct, a proposed edit with a preview and diff, or a research result with sources. Margin also needed to accept disagreement. A writer can challenge the model’s diagnosis, revise its interpretation, or dismiss its advice without turning the entire application into a chat interface.

Editorial judgment operates at several scales. A sentence may contain a local tension, while the document as a whole may have a weak premise or an unsupported conclusion. Margin had to distinguish those levels, connect each observation to the relevant text, and show how a correction to one claim affects the argument that follows. Producing suggestions was straightforward; making the model’s reading inspectable and revisable required a more careful interaction model.

Writing and AI also run at different speeds. The editor must respond immediately, while research and document analysis may take considerably longer. Margin begins stable #[] instructions after a pause, reports what it is doing, keeps the document usable, and returns completed work at the point where it was requested. This lets the writer continue while Margin handles research or a delegated edit in the background. The document itself is a moving target. CodeMirror virtualizes its view, and every edit can change the position of findings, previews, tables, diffs, and argument anchors. Keeping those elements attached to the correct prose required careful state mapping and custom editor decorations. Rich results introduced a related constraint: tables, charts, diagrams, images, and widgets needed responsive controls inside Margin and durable representations outside it. Each format therefore exports as Markdown or an ordinary asset, with editable data and static fallbacks where appropriate.

Accomplishments that we're proud of

The main accomplishment is a coherent writing environment in which research, editorial judgment, and revision remain attached to the document.

  • Built the full document workflow—create, open, rename, write, review, save, and export—around a quiet, effective Markdown editor.
  • Developed an editorial system that works at two scales: local findings beside specific passages and a whole-document review of purpose, audience, argument, structure, and voice.
  • Made the model’s interpretation inspectable. The argument spine links every claim to an exact passage, accepts corrections from the writer, and identifies the later claims that need reconsideration.
  • Turned #[] into a native writing interaction. Margin begins research after the writer pauses, shows its progress, and inserts the finished material where it was requested with source provenance intact.
  • Extended that interaction beyond tables to charts, diagrams, editorial images, and interactive widgets. Each format works inside Margin and exports with editable data or a static fallback.
  • Created an accountable revision workflow. Findings can be discussed, refined, dismissed, or resolved; proposed edits require approval; completed changes retain their before-and-after diff.
  • Added file and URL context while keeping discovered sources distinct from material supplied by the writer.
  • Shipped a public production build with a server-only OpenAI boundary, schema-validated model responses, rate and timeout controls, automated API and editor checks, and a labeled deterministic demonstration path.

What we learned

I set out to explore what's possible for human-computer interaction with AI, with the goal of building a tool that helps us think rather than just perform tasks for us. What I found is that we can build tools which leave the human as the primary actor to make sure they are actively engaged in thinking and creating, but also aid them by collaboratively performing work at their direction through different interaction schemes like '#[]' syntax and ambient review. Anecdotally, I found that I was more engaged in creative thought when I interacted with AI through explicit intent (and could keep going after doing so without pause).

What I have also found is that these different modes of human-AI interaction—assistant, autonomous, acting at the user's expressive direction—are not mutually exclusive, nor do we need to choose. Each has a purpose. We need to continue exploring human-AI interaction to find new modes and what each mode is good for.

In meta fashion, I developed Margin almost entirely through Codex using GPT-5.6 Sol. I provided Codex with my idea, brainstormed it and developed it, turned it into a PRD, had Codex develop it, tested it myself and provided specific and pointed feedback, and brainstormed challenges and opportunities for it with Codex. Margin was developed with an assistant in that sense, where we closely collaborated to create it.

We need more human-AI interaction experimentation, not less.

What's next for Margin App

The next step is to extend Margin’s understanding from a single document to a body of work. Document collections would form a revisable map of the writer’s ideas, evidence, open questions, commitments, and recurring tensions. Margin could recover an earlier line of thought, notice when two drafts approach the same idea differently, or surface a source whose significance only becomes clear weeks later. The writer would be able to inspect and correct that map, just as they can correct a document’s argument spine today. Margin could then become a more continuous partner in thought. A writer might leave an intention directly in the work—find the origin of this claim, test this assumption, compare these accounts, sketch the relationship, calculate the consequence—and continue writing while Margin prepares the material. Its work would return to the relevant place with its reasoning and provenance intact. Over time, the system could help the writer follow unresolved questions across projects, explore competing interpretations, and recognize how their own thinking is changing. The nearer-term product work supports that direction: shared context across collections, citation refresh and staleness monitoring, publication-aware editorial review, richer keyboard-first editing for tables and other computed media, portable publishing packages, and collaboration that preserves anchors, discussions, decisions, and diffs. Together, these move Margin toward a workspace that remembers the development of an idea and helps its author carry it further.

Built With

Share this project:

Updates