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

Skip to content
< 7FFF link rel="preload" as="image" href="https://github.githubassets.com/assets/changelog-fd687bff072883b0.png"/>

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

149 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Obelus

Why I built Obelus

The only way to write is to write. - Ralph Waldo Emerson

I did most of my writing as a student. I never considered emails I sent or presentations as writing, but I was communicating with others in the written form. The only time I wrote without any agenda was when I jotted my observations or ideas from the books I was reading.

Around 5 years back, I started jotting down my notes in Obsidian. Obsidian’s wiki-link and graph features encouraged me to develop connections across my vault. I composed mini-essays to aid me in building the Obsidian's knowledge-graph.

I did not write my essays with an intent to publish, but I did post occasionally on LinkedIn. I spent more time editing and rewriting before posting.

After launch of ChatGPT, I started to use it for polishing my posts. AI composed highly polished prose, which was beyond my skill. AI became my ghostwriter.

With every new model release, AI got much better at writing, but not me. So, in early 2026, I decided to learn how to write . I asked AI to review my writing and provide suggestions.

I slowly started improving but I knew in the back of my head that most of the improvements came from AI’s advice not completely from my efforts.

In September 2026, I finished reading William Zinsser's 'On Writing Well'. The book’s final section, "Attitude", forced me to examine my process. While I was thinking how to best to use AI, I came across Thomas Ptacek post on 'How To Write With An LLM'.

Ptacek suggests adopting two rules:

  • Avoid using words suggested by AI
  • Avoid encouragement by AI

Ptacek’s advice makes sense as AI is trained to be helpful even when you are wrong.

Luckily, I had done most of what he recommendeds ‘Skills’. My skills never restricted AI from making recommendations.

This app incorporates Ptacek’s advice along with other rules. I will be updating the project frequently, but the tool will only inform when the writing is poor.

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 6DEC 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