{"id":51003923,"url":"https://github.com/sreekarnv/draftlet","last_synced_at":"2026-06-20T18:01:22.875Z","repository":{"id":362943847,"uuid":"1261298520","full_name":"sreekarnv/draftlet","owner":"sreekarnv","description":"Local-first drafting assistant with a browser extension, desktop companion, and Ollama-powered local replies.","archived":false,"fork":false,"pushed_at":"2026-06-13T16:48:06.000Z","size":6924,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-13T18:10:11.817Z","etag":null,"topics":["ai","chrome-extension","electron","fastapi","local-first","ollama","productivity","react","sqlite","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sreekarnv.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-06T13:56:44.000Z","updated_at":"2026-06-06T17:54:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sreekarnv/draftlet","commit_stats":null,"previous_names":["sreekarnv/draftlet"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sreekarnv/draftlet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sreekarnv%2Fdraftlet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sreekarnv%2Fdraftlet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sreekarnv%2Fdraftlet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sreekarnv%2Fdraftlet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sreekarnv","download_url":"https://codeload.github.com/sreekarnv/draftlet/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sreekarnv%2Fdraftlet/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34580039,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-20T02:00:06.407Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","chrome-extension","electron","fastapi","local-first","ollama","productivity","react","sqlite","typescript"],"created_at":"2026-06-20T18:01:20.683Z","updated_at":"2026-06-20T18:01:22.857Z","avatar_url":"https://github.com/sreekarnv.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Draftlet\n\nDraftlet is a local-first browser drafting assistant. It helps you capture context from a webpage, generate reply drafts through a local Ollama model, refine those drafts over multiple turns in a thread, and insert only the text you approve back into the page.\n\nThe webpage never owns the Draftlet workflow. Draftlet-owned surfaces (the browser extension's side panel, the desktop companion, and the local server) own the assistant experience. The page is only an integration point for context capture, editable target detection, and best-effort insertion.\n\n![Draftlet side panel generating a draft from selected text in Gmail](.github/assets/extension-gmail.gif)\n\n## What's included\n\n- **Browser extension** — Chrome MV3 extension with a content script for page integration, a background coordinator for browser-level routing, a side panel as the primary drafting workspace, and a popup for quick actions and runtime status.\n- **Local FastAPI server** — Ollama streaming, prompt building, response parsing, SQLite persistence for sessions, threads, turns, draft variants, preferences, and diagnostics.\n- **Electron desktop companion** — first-run setup, runtime start/stop controls, model selection, tray behavior, and diagnostics.\n- **Shared contracts** — typed messages and schemas used across the extension, desktop, and runtime boundaries.\n\n## What's not included\n\n- **Ollama is not bundled.** Install it separately from [ollama.com/download](https://ollama.com/download) and pull a model. `gemma3:4b` is the recommended default; the desktop companion can switch to any installed model.\n- **No remote server.** The Draftlet server runs on `http://127.0.0.1:47632` and is reachable from the extension and the desktop companion over loopback. There is no hosted Draftlet service.\n- **No signed store build.** The extension is loaded as an unpacked build from this repository. There is no Chrome Web Store build yet.\n- **No favorites, no in-page overlay, no legacy history.** Draftlet only drafts into the side panel, persists workspace sessions and threads locally, and inserts into the page through best-effort page integration. Nothing else.\n\n## Requirements\n\n- Node.js with pnpm (workspaces enabled)\n- Python 3.12+\n- [uv](https://docs.astral.sh/uv/) for Python dependency management\n- [Ollama](https://ollama.com/download) running on `127.0.0.1:11434`\n- An Ollama model; `gemma3:4b` is the recommended default\n- A Chromium-based browser (for example, Chrome) with Developer Mode enabled, for loading the unpacked extension\n\nThe desktop companion runs on the platforms Electron supports. The Linux desktop build uses Electron Forge Debian and ZIP makers.\n\n## Quick start\n\nThe shortest first-run walkthrough lives in [docs/getting-started.md](docs/getting-started.md). Use [docs/setup.md](docs/setup.md) when you need the full command reference.\n\n1. Install Ollama and pull a model:\n\n   ```bash\n   ollama pull gemma3:4b\n   ```\n\n2. Install repo dependencies:\n\n   ```bash\n   pnpm install\n   cd apps/server \u0026\u0026 uv sync --group dev \u0026\u0026 cd ../..\n   ```\n\n3. Apply server database migrations:\n\n   ```bash\n   cd apps/server \u0026\u0026 uv run alembic upgrade head \u0026\u0026 cd ../..\n   ```\n\n4. Start the local stack (server, extension dev, desktop):\n\n   ```bash\n   pnpm dev\n   ```\n\n   Or start one app at a time:\n\n   ```bash\n   pnpm dev:server\n   pnpm dev:extension\n   pnpm dev:desktop\n   ```\n\n5. Build the extension and load it as an unpacked extension:\n\n   ```bash\n   pnpm --dir apps/extension build\n   ```\n\n   Load the directory `apps/extension/.output/chrome-mv3` in your browser's extensions page with Developer Mode enabled.\n\n6. Select text on a page, open the Draftlet side panel, and generate a reply.\n\n## Extension loading\n\nThe extension is a WXT-built Chrome MV3 unpacked build:\n\n1. Run `pnpm --dir apps/extension build` to produce `apps/extension/.output/chrome-mv3`.\n2. Open your browser's extensions page.\n3. Enable **Developer mode**.\n4. Choose **Load unpacked** and point it at the directory above.\n5. After code changes, rebuild and click **Reload** on the Draftlet extension card.\n\nThe extension expects the Draftlet server at `http://127.0.0.1:47632`. If the server stops, the side panel and popup surface a connection error with a retry control.\n\n## Desktop companion\n\n![Draftlet desktop companion showing runtime and model controls](.github/assets/desktop-companion.png)\n\nThe desktop companion is an Electron app for first-run setup and runtime operations:\n\n- Checks whether Ollama is installed and running.\n- Lists installed Ollama models and lets you select the active model.\n- Starts, stops, and restarts the local Draftlet server.\n- Exposes a system tray icon for quick access.\n- Shows a diagnostics page that reads the latest browser recapture diagnostics report from the runtime relay and the runtime's generation-run maintenance endpoint.\n\nThe desktop companion does not replace the side panel. It is the operator-facing shell for setup, runtime lifecycle, and operational diagnostics. The primary drafting workflow lives in the extension's side panel.\n\nFor the Linux Electron `chrome-sandbox` SUID helper issue, see [docs/troubleshooting.md](docs/troubleshooting.md#electron-dev-fails-on-linux-sandbox-setup).\n\n## Local data\n\nDraftlet stores data in two places:\n\n- **SQLite database** at `apps/server/draftlet.db` during development, and under the Electron user-data directory in packaged desktop builds. The schema holds `WorkspaceSession`, `ConversationThread`, `Turn`, `DraftVariant`, `GenerationRun`, `GenerationRunEvent`, preferences, and bounded browser recapture diagnostics reports.\n- **Browser extension storage** holds only lightweight coordination state (for example, the last selected tone).\n\nTo reset development state, stop the server and delete the database file:\n\n```bash\nrm apps/server/draftlet.db\n```\n\nThe next server start recreates the database after `uv run alembic upgrade head`. Migration history is preserved across resets; only the data is removed.\n\nDraftlet only controls its own processes. It cannot prevent the browser, the page, or the operating system from capturing content elsewhere.\n\n## Architecture summary\n\nDraftlet is composed of six surfaces, each with a narrow responsibility:\n\n- **Content script** — page integration. Detects editable surfaces, captures selection, performs best-effort insertion. Does not own business logic, persistence, or runtime connection.\n- **Extension service worker (background)** — command routing, tab/session coordination, capability checks, and bridge orchestration to the runtime. Holds lightweight browser-level state only.\n- **Side panel** — the primary Draftlet workspace. Thread view, streaming drafts, follow-up instructions, draft variants, review, and insertion controls.\n- **Popup** — runtime status, quick actions, refresh, and entry into the side panel. Compact. Recapture diagnostics, when shown, are dev-only and gated behind `DRAFTLET_DEBUG_INSERTION=1`.\n- **Desktop app** — first-run setup, runtime lifecycle, tray behavior, settings, and diagnostics.\n- **Local runtime** — Ollama streaming, prompt building, response parsing, SQLite persistence, and the bounded durable diagnostics relay.\n\nThe full architecture, setup, troubleshooting, boundaries, and contracts are documented under [docs/](docs/):\n\n- [Architecture](docs/architecture/architecture.md)\n- [Boundaries](docs/architecture/boundaries.md)\n- [Events and contracts](docs/architecture/events-and-contracts.md)\n- [Current state and open cleanup notes](docs/architecture/phase-plan.md)\n- [UI principles](docs/ui/ui-principles.md)\n- [Getting started](docs/getting-started.md)\n- [Setup](docs/setup.md)\n- [Troubleshooting](docs/troubleshooting.md)\n- [Public release checklist](docs/release-checklist.md)\n- [Developer docs](docs/dev/) (recapture target recovery background contract, dev-only manual QA)\n\n## Development commands\n\nRun from the repo root unless noted.\n\n```bash\npnpm typecheck\npnpm build\npnpm make:desktop\n```\n\nExtension:\n\n```bash\npnpm --dir apps/extension exec tsc --noEmit\npnpm --dir apps/extension test\npnpm --dir apps/extension build\n```\n\nDesktop:\n\n```bash\npnpm --dir apps/desktop typecheck\npnpm --dir apps/desktop test\npnpm --dir apps/desktop package\npnpm --dir apps/desktop make\n```\n\nServer:\n\n```bash\ncd apps/server\nuv run pytest\nuv run alembic upgrade head\n```\n\n## Troubleshooting\n\n- [Getting started](docs/getting-started.md)\n- [Setup walkthrough](docs/setup.md)\n- [Common failures and recipes](docs/troubleshooting.md) — Ollama, server health, port conflicts, extension loading, Linux Electron `chrome-sandbox`, stale or interrupted generation recovery\n- [Release checklist](docs/release-checklist.md) — the public-readiness pass we run before tagging a release\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsreekarnv%2Fdraftlet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsreekarnv%2Fdraftlet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsreekarnv%2Fdraftlet/lists"}