WritingTools

The Problem

Users need a system‑wide writing assistant that works across Windows, Linux, and macOS, offering proofreading, rewriting, and summarisation without leaving the active application. Existing solutions are either platform‑locked, require a paid subscription, or lack support for local or free cloud LLMs.

What This Does

Writing Tools is an Apple‑Intelligence‑inspired app that sits in the background and watches the system clipboard. When the user presses Ctrl + Space, a popup appears with actions such as Proofread, Rewrite, Friendly, Professional, Concise, or custom instructions. The selected text is sent to an LLM (Gemini, Ollama, OpenAI, etc.) and replaced in place. A separate summarisation mode lets users select web‑page text or a YouTube transcript and receive a summary, key‑points list, or table.

The code base is split between two platforms:

• Windows & Linux – Windows_and_Linux/main.py is the entry point; it launches the GUI built with Tkinter‑style windows (Windows_and_Linux/ui/AboutWindow.py, Windows_and_Linux/ui/OnboardingWindow.py, etc.) and delegates LLM calls to Windows_and_Linux/aiprovider.py. The provider layer supports Gemini, Ollama, OpenAI, OpenRouter, Anthropic, Mistral, and local models. Dependencies are declared in Windows_and_Linux/requirements.txt (pip).
• macOS – a native Swift port under macOS/WritingTools. The Swift UI (macOS/WritingTools/App/AppState.swift, macOS/WritingTools/App/KeychainManager.swift) mirrors the Windows functionality, with provider implementations (macOS/WritingTools/Models/Providers/GeminiProvider.swift, macOS/WritingTools/Models/Providers/LocalModelProvider.swift, etc.) and a Swift‑based onboarding/settings flow.

Both branches share the same logical flow: hotkey → UI picker → provider request → LLM response → text replacement.

How It Is Wired

The internal call graph (102 code files analysed) is flat: every module has Ca = 0, Ce = 0, instability = 0. Execution starts at Windows_and_Linux/main.py, which creates the WritingToolApp instance, loads the UI windows, and registers the global hotkey. The UI windows call aiprovider functions (e.g., generate_text, summarise) that internally select the configured provider (Gemini API, Ollama local model, etc.) and handle the HTTP/request‑response cycle. On macOS, macOS/WritingTools/writing_toolsApp.swift performs the same orchestration using Swift‑UI views and Swift‑based networking.

Key files with wide blast radius:

No edge leaves the process except the outbound HTTP request(s) to the chosen LLM endpoint; all other work stays in‑process.

How To Use It

1. Clone the repository (verbatim): ``bash git clone https://github.com/moses-y/WritingTools ``
2. Install dependencies (Windows & Linux): ``bash cd WritingTools/Windows_and_Linux pip install -r requirements.txt ``
3. Configure an LLM – the repo supports free Gemini API keys or local Ollama models. API keys are stored in Windows_and_Linux/options.json (or set via the UI onboarding flow). No environment‑variable‑only flow is documented, so edit options.json directly or use the Settings → AI Provider Settings pane.
4. Run the app: ``bash python main.py ` On macOS, open macOS/WritingTools/WritingTools.xcodeproj and run the scheme, or build with xcodebuild`.
5. Invoke the assistant anywhere with Ctrl + Space (Windows/Linux) or the assigned macOS shortcut (configured in the onboarding step). Choose an action, and the selected text is instantly replaced. Use Ctrl + Z to revert.

No CI/CD pipeline is present, so after each change you should locally run the build and test commands (see the “Code Health & Issues” section).

Real‑World Use

A journalist researching a story selects a paragraph from a PDF, presses Ctrl + Space, chooses Proofread, and the text is re‑written for clarity and tone without leaving the PDF viewer. Later, they select an entire webpage, pick Summary, and receive a concise bulleted overview in a pop‑up—saving minutes of manual copy‑pasting into a separate LLM chat.

Code Health & Issues

Measured static‑analysis findings (51 total):

• 16 HIGH – deep nesting (indentation depth up to 12) in macOS/WritingTools/Models/CommandModel.swift, macOS/WritingTools/Utilities/Modifiers/LoadingModifier.swift, macOS/WritingTools/Views/About/AboutView.swift; duplicated 6‑line blocks (105 occurrences) across Windows_and_Linux/ui/AboutWindow.py, Windows_and_Linux/ui/OnboardingWindow.py, Windows_and_Linux/ui/SettingsWindow.py, Windows_and_Linux/ui/ResponseWindow.py; file‑opened‑without‑context‑manager in Windows_and_Linux/aiprovider.py and Windows_and_Linux/ui/AboutWindow.py; broad except clauses in Windows_and_Linux/ui/CustomPopupWindow.py.
• 35 MEDIUM – oversized Swift files (macOS/WritingTools/App/AppState.swift, macOS/WritingTools/Models/CommandModel.swift, macOS/WritingTools/Models/Providers/LocalModelProvider.swift – 720 lines each); high branching density (74 branch points over 253 lines) in macOS/WritingTools/App/KeychainManager.swift, macOS/WritingTools/Models/PromptStructure.swift, macOS/WritingTools/Models/Providers/AIProvider.swift.

Code‑Health Audit (4 items, each with a prescribed fix):

• HIGH – Add a test suite; repository has 101 source files and zero test files. Any regression will ship undetected. Fix: add one test per public entry point, then a CI step that runs them.
• HIGH – Add a workflow that builds and tests this repository; no CI configuration exists. Fix: add a GitHub Actions workflow that runs pip install -r requirements.txt and the test suite on push and pull_request.
• MEDIUM – Enable Dependabot or Renovate; only a single manifest is present, no update bot configured. Fix: commit .github/dependabot.yml covering pip and Swift package ecosystems plus GitHub Actions.
• MEDIUM – Move large binaries to Git LFS or out of the repository; README's Linked Content/Demo - Summaries.mp4 is 4.9 MB. Fix: track *.mp4, *.mov, and other media extensions with Git LFS, or fetch them in a setup step.

The Bottom Line

Writing Tools delivers a genuinely cross‑platform, free AI writing assistant with a simple hotkey workflow and support for both cloud and local LLMs. The code base is functional but suffers from deep nesting, duplicated UI logic, and missing test/ CI infrastructure. Teams that need an immediately usable, self‑hosted writing copilot will find value here, provided they are willing to add basic automated testing, a CI gate, and Git LFS for the demo video.