8000 GitHub - kiran-brahma/writing-tool at v1.3-53 · 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

120 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Obelus

Why

I hated writing. My writing style was developed during my school and college days, where the goal was to pass my exams. When I started working, most of what I wrote were either emails or presentations. However, I did keep a small notebook where I wrote down my learnings or observations from books I kept reading over the years.

My first real writing project was my company's blog. Everyone kept repeating that if I had to improve my company's SEO peformance, I will need to create content. Now Google expects the content to be structured in a specific manner, aiding their crawlers to scan your website quickly. I adopted the structure as my goal was not write great blog posts but to gain visibility in google search results.

Somewhere along the line, I started writing mini-essays for myself in obsidian. I was trying to combine ideas across different books or articles into something I can apply for myself. I never thought on publishing them anywhere. They were just personal notes for mysel AF10 f. During the covid lockdown, I had too much free time on my hand. So, I started making small LinkedIn posts whenever I felt like it. 99% of what I posted were ignored but I observed that when I was making a post, I was being critical of what I was writing. Every post I made went through multiple rewrites, till I felt it was good. I started applying the same rigor to my mini-essays I was writing for myself.

When ChatGPT was launched, I started using it for feedback on what I was writing. Slowly, I let the AI decide what was good or bad. AI became my ghostwriter. I was just sharing some raw thoughts and ideas and AI put them together in a neat package. I rewrote most of my older company blog posts using AI. Slowly but steadily, google improved my website ranking for certain keywords.

The same confidence encouraged me to even start my own blog. As AI models kept improving, I felt the writing was also improving. I never realised that I actually never learnt how to write well. As internet was getting flooded with AI content, I could see every other post sounded the same as mine. I hated it, so finally at end of 2024, I decided to actually learn how to write better.

Slowly, I started building more robust workflows and process around my AI writing. Every other week, I updated my project rules or skills on how to improve the outputs. After a few months, the writing quality did improve substantially but it never lost the signs of AI-writing. I was generating so much AI generated content that I could understand if a person or an AI wrote an article or a linkedin post.

In the same time, I was feeling confident on my own writing abilities, so I actually started writing the first drafts on my own. I asked AI to judge me and it suggested improvements and even re-wrote certain sections which it judged to be poor. Once again, I felt that the quality of my writing has improved a lot. After a few weeks, I felt confident enough to completely rewrite the final essay that AI generated in my own words.

Last week, I finally ended up reading William Zinsser's book 'On Writing Well'. While most of the book presented the same ideas, process and tips I had adopted, the final section (Atttitude) of the book made me question my process once again. As I was thinking how can I actually adopt AI into my writing workflow, I came across the word Obelus (the editor's mark for this passage is suspect) and a post by Thomas Ptacek on 'How To Write With An LLM'.

Thomas Ptacek's two rules on how to use AI for writing resonated with the ideas twirling in my head. He even included a prompt on how to build a tool for yourself in the post. I took it upon myself to see if I can build something on his idea while incorporating many of my ideas and workflows into a simple app.

The current APP is a prototype to help me improve my writing on my own, with AI relegated to a supporting role. I built this app the way I wanted it to be. I will be making changes by iterating on new ideas on a regular basis. I don't know if anyone will use it apart from me, but then if you find it useful, feel free to 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 API keys live in IndexedDB. 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

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.

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.
  • 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