8000 GitHub - kiran-brahma/writing-tool at v0.1.0 · GitHub
[go: up one dir, main page]

Skip to content

About

A simple writing tool to help improve your writing without getting AI to do the writing

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

141 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Obelus

Why I built Obelus

I hated writing. I learned to write at school and college, where the goal was to pass exams. At work, I wrote mostly emails and presentations. The one exception was a small notebook, where I wrote down what I learned or observed from the books I read over the years.

My first real writing project was my company's blog. Everyone told me that to improve the company's SEO, I had to create content. Google expects content in a specific structure, so that its crawlers can scan a website quickly. I adopted that structure, because my goal was not to write great blog posts. It was to show up in Google search results.

Along the way, I started writing mini-essays for myself in Obsidian. In them, I tried to combine ideas from different books and articles into something I could apply myself. I never planned to publish them. They were personal notes.

During the COVID lockdown, I had too much free time, so I started writing short LinkedIn posts whenever I felt like it. People ignored 99% of them. But I noticed that I was critical of my own writing while I wrote a post. Every post went through several rewrites until I felt it was good. I started to apply the same rigor to my mini-essays.

When ChatGPT launched, I used it for feedback on my writing. Bit by bit, I let it decide what was good and what was bad. AI became my ghostwriter. I gave it raw thoughts and ideas, and it put them together in a neat package. I used AI to rewrite most of my older company blog posts. Slowly but steadily, Google improved my website's ranking for some keywords.

That result gave me the confidence to start my own blog. As the models improved, I felt my writing improved with them. I did not realise that I had never learned to write well. Then the internet filled up with AI content, and every other post sounded the same as mine. I hated it. At the end of 2024, I decided to learn to write better.

I built stronger workflows and processes around my AI writing. Every other week, I updated my project rules and skills to improve the output. After a few months, the writing was much better, but it never lost the signs of AI writing. I had generated so much AI content that I could tell whether a person or an AI had written an article or a LinkedIn post.

During the same period, I grew confident in my own writing, so I started to write the first drafts myself. I asked AI to judge them. It suggested improvements and even rewrote the sections it judged to be poor. Again, I felt my writing had improved a lot. After a few weeks, I was confident enough to rewrite the AI's final essay completely in my own words.

In September 2026, I finally read William Zinsser's On Writing Well. Most of the book described ideas, processes, and tips that I had already adopted. But its final section, "Attitude", made me question my process again. While I was thinking about how to fit AI into my writing, I came across two things. One was the word obelus, the editor's mark for this passage is suspect. The other was Thomas Ptacek's post How To Write With An LLM.

Ptacek's two rules for writing with AI matched the ideas already in my head. His post even included a prompt for building a tool for yourself. I set out to build on his idea and to add my own ideas and workflows, in a simple app.

This app is a prototype. It helps me improve my writing on my own, with AI in a supporting role. I built it the way I wanted it, and I will keep changing it as I try new ideas. I don't know if anyone except me will use it. If you find it useful, give it a try.

About the APP (AI generated text)

Please Note: Everything below has been generated by AI

Obelus is a browser-only writing tool that uses language models as a copyeditor and a judge, never as a ghostwriter. It marks; it never holds the pen.

You write in a rich-text editor. Rule-based passes run on every save and cost nothing. Model passes run on demand and return findings anchored to the exact text they concern. You rewrite in your own words. When a paragraph changes, the judge compares the old and new versions and says which is clearer. It runs twice with the labels swapped, so a verdict that flips shows up as unstable instead of being reported as a preference.

Two constraints shape the product:

  • No model output can enter your document. The findings schema has no field for a rewritten sentence, and the app has no apply, accept, or insert control for model text. Your keyboard is the only path by which words enter a document.
  • No praise. The prompts forbid it, a client-side linter catches it anyway, and the app shows it struck through rather than hiding it, so you can see when a prompt has drifted.

Everything runs in the browser. Documents, revisions, findings, passes, connections, and persisted API keys live in IndexedDB; a session-only key is held in memory and gone on reload. The only outbound requests go to the model provider you configure. There is no account, no sync, and no telemetry.

What it does

  • Rich-text editing with headings, emphasis, lists, and block quotes.
  • Rule passes for hedges and intensifiers, nominalizations, throat-clearing openers, wordy constructions, and repeated words and openers, plus sentence-rhythm metrics. They run on save, offline, and with no API key. Their word lists and patterns are editable.
  • Model passes: a starter pack of paragraph-scope and document-scope passes, each returning findings anchored to a quote. Findings are listed by pass in document order. j and k move through them, a marks addressed, and x declines.
  • The judge: compare any two revisions, see the word-level diff and both extracted passages, then get a verdict from two calls with the labels swapped. The judge defaults to a different Connection and model from the critic.
  • The reader pass: a per-section account of what the section says, what a distracted reader would miss, and the gap between the two, shown in its own tab.
  • A library of documents with tags, search, and status; automatic and milestone revisions; a word-level diff; Markdown import and export; whole-library backup and restore; and a single-document bundle.
  • An offline shell that opens with your existing documents.
  • A pass workbench for writing your own prompts, with a model assistant that works on prompts and never on your prose.

Requirements

  • Node.js 22.12.0 or newer.
  • pnpm 10 or newer (package.json pins the version in packageManager).
  • A browser with IndexedDB and service worker support.
  • For model passes, an API key for OpenAI, Anthropic, Google Gemini, or OpenRouter, or a local Ollama install. Rule passes need none of this.

Run it locally

pnpm install
pnpm run dev

Open http://localhost:5173.

The app works immediately as a plain writing tool with the rule passes, and it creates a Scratchpad so there is somewhere to type. Model passes need a Connection:

  1. Open the Connections panel in the sidebar.
  2. Pick a provider, then enter an API key and a model id. The model field is free text, so a model released today works without an update.
  3. Assign one Connection to the Critic slot and a different one to the Judge slot.
  4. Use "Test connection" to confirm the URL and key before running a pass.

For local Ollama, choose the Ollama prefill (base URL http://localhost:11434/v1, no key) and start Ollama with the app's origin allowed:

OLLAMA_ORIGINS=http://localhost:5173 ollama serve

Ollama refuses any origin it has not been told to allow, and answers the browser's preflight with 403 Forbidden. The app reports this as "Failed to fetch". To use local Ollama from a deployed copy, add the deployed origins to the list, separated by commas:

OLLAMA_ORIGINS=https://obelus.kiranbrahma.com,https://writing-tool.kiranbrahma.workers.dev,http://localhost:5173 ollama serve

On macOS with the Ollama app, set the variable for GUI apps, then quit Ollama from the menu bar and open it again:

launchctl setenv OLLAMA_ORIGINS "https://obelus.kiranbrahma.com,https://writing-tool.kiranbrahma.workers.dev,http://localhost:5173"

launchctl setenv lasts until the next restart. Add the line to ~/.zshrc to keep it. To check it took effect, send the preflight yourself and look for 204 and an Access-Control-Allow-Origin header naming your origin:

curl -i -X OPTIONS http://localhost:11434/v1/chat/completions \
  -H "Origin: https://obelus.kiranbrahma.com" \
  -H "Access-Control-Request-Method: POST"

Chrome may ask for permission to reach devices on your local network the first time. Allow it.

Ollama Cloud models work through the local daemon. Run ollama signin once, then enter a cloud model id such as glm-5.3:cloud in the Ollama Connection; ollama list shows the ones you have. The daemon forwards the request with your account, so no key enters the browser. Calling https://ollama.com directly from the browser does not work: it does not answer CORS preflight, and a proxy would break the privacy claim (docs/adr/0002-browser-only-provider-access.md).

Keys are stored in IndexedDB by default. Set a Connection to session-only to keep its key in memory, in which case you re-enter it after a reload.

Using it

  1. Write or import a document. Rule passes mark problems as you save.
  2. Work the queue in the sidebar. Address a finding when you have fixed it, or decline it. Declining needs no reason.
  3. Run a model pass when you want a closer read. Findings arrive anchored to quotes, grouped by pass.
  4. Rewrite the paragraphs in your own words, then flag a milestone so the version is findable later.
  5. Select a span or a section, pick two revisions, and ask the judge whether the rewrite is clearer.

The Privacy page in the app lists where your data lives and gives the steps to verify it in DevTools.

Install it as an app

Obelus is a Progressive Web App. Installed, it opens in its own window, and it opens offline with your existing documents after the first online visit.

  • Chrome or Edge (desktop): click the install icon at the right of the address bar, or open the menu and choose Cast, save, and share → Install page as app.
  • Safari (macOS Sonoma or newer): File → Add to Dock.
  • iPhone or iPad (Safari): Share → Add to Home Screen.
  • Android (Chrome): menu → Add to home screen, then Install.

Your documents stay in the browser profile's IndexedDB for that site. On iOS and in Safari, the installed app has its own storage, separate from the browser tab, so export a backup from the tab and restore it in the app to carry work across. Each origin also has its own storage, so obelus.kiranbrahma.com and writing-tool.kiranbrahma.workers.dev hold separate libraries. Pick one and install from it.

Checks

pnpm run typecheck  # tsc -b
pnpm test           # full suite, including the constitution harness
pnpm run gates      # the import, silent-catch, affordance, Worker and lockfile gates
pnpm run harness    # the constitution harness alone

Run the constitution harness before changing any pass prompt. It checks that model output parses, that praise is flagged, that no response carries rewritten prose, and that findings stay inside their target.

To check the production build and the security headers, use the Worker locally:

pnpm run build
npx wrangler dev

pnpm run preview serves the static build without the Worker, so it will not show the Content-Security-Policy header.

Deploy to Cloudflare Workers

This is the intended host. wrangler.jsonc serves dist/ as static assets and routes every request through worker/index.ts, which sets the Content-Security-Policy and the other security headers. The Worker has no API route and serves nothing but the app. Keep it that way: a route that called a model provider would put a key on a server and break the central privacy claim.

npx wrangler login
pnpm run deploy

pnpm run deploy runs the gates, typechecks, builds with Vite, and deploys with Wrangler. To preview the Worker and its headers locally, run pnpm run build && npx wrangler dev.

Take a backup before the first deploy to a browser that already holds work. The launch applies the accumulated database migrations at once.

Deploy to Vercel (optional, unsupported)

Cloudflare is the supported host and the one described above. If you would rather deploy to Vercel, docs/reference/vercel-deploy.md has the steps and docs/reference/vercel.json is the config to copy to the repository root. On Vercel the Worker does not run, so that config supplies the security headers statically; pnpm run gates fails the build if its Content-Security-Policy drifts from worker/securityHeaders.ts.

Documentation

  • DESIGN.md explains the reasoning behind the product, including why the constitution is structural.
  • docs/specs/obelus-v1.md is the v1 requirement, published as issue #1.
  • CONTEXT.md is the glossary. Code, tests, and commits use its terms.
  • docs/adr/ records the load-bearing decisions.
  • docs/migrations.md states the database migration policy.
  • CHANGELOG.md lists what changed in each release, and docs/releasing.md describes how to cut one.
  • notes/provider-api-facts.md records the provider wire facts, with the date they were checked.
  • docs/reference/ holds optional material, such as the Vercel deploy config.
  • AGENTS.md describes the build discipline for agents working in the repository.

License

GPL-3.0-or-later. See LICENSE.

About

A simple writing tool to help improve your writing without getting AI to do the writing

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0