Figure-on-ground roadmap: a verified product model (vartamana ground) under an issue/PR-derived backlog (shabda), assembled into the transformations the project is actually under. Directions are hypotheses until the maintainer confirms them. mergeable=null / UNSTABLE treated as unknown — never "clean."
Karakeep is a worker-pipeline product: a save enqueues async jobs (crawl → AI-enrich → index) that turn a bare URL into archived, tagged, searchable content. Each line is cited to a real primitive.
| Subsystem | Cited primitive |
|---|---|
| 📦 Ingestion / Crawler | apps/workers/workers/crawlerWorker.ts; CRAWLER_* env |
| 📦 AI / Inference | apps/workers/workers/inference/, embeddingsWorker.ts; OPENAI_*/OLLAMA_*/INFERENCE_*/EMBEDDING_*/OCR_* env |
| 📦 Search | searchWorker.ts; packages/shared/search; README (Meilisearch) |
| 📦 Reader / Web UI | apps/web/app/*; Next.js app router, tRPC |
| 📦 Content Management | packages/trpc/routers/{lists,tags,highlights,rules,feeds}.ts; ruleEngineWorker.ts, feedWorker.ts, importWorker.ts |
| 📦 Integrations / Clients | apps/{cli,mcp,browser-extension,mobile}; packages/{sdk,open-api}; webhookWorker.ts |
| 📦 Platform / Storage & Auth | packages/db/schema.ts; NextAuth; apiKeys router; backupWorker.ts; DATA_DIR/ASSET_STORE_S3_* env |
| Capability | Subsystem | Cited primitive |
|---|---|---|
| ⚙️ Headless-browser crawling | Crawler | crawlerWorker.ts; CRAWLER_HEADLESS_BROWSER/STORE_SCREENSHOT/STORE_PDF |
| ⚙️ Full-page archival (monolith) | Crawler | CRAWLER_FULL_PAGE_ARCHIVE/MONOLITH_* env; README |
| ⚙️ Video archiving (yt-dlp) | Crawler | videoWorker.ts; CRAWLER_VIDEO_DOWNLOAD env |
| ⚙️ Client-side crawl (SingleFile) | Crawler | release 0.32.0 (#2197); apps/browser-extension |
| ⚙️ AI auto-tagging | AI/Inference | inference/tagging.ts; INFERENCE_ENABLE_AUTO_TAGGING |
| ⚙️ AI summarization | AI/Inference | inference/summarize.ts; INFERENCE_ENABLE_AUTO_SUMMARIZATION |
| ⚙️ Embeddings generation | AI/Inference | embeddingsWorker.ts; EMBEDDING_TEXT_MODEL/DIMENSIONS |
| ⚙️ OCR text extraction | AI/Inference | OCR_LANGS/OCR_USE_LLM env; tesseract.js |
| ⚙️ Full-text search (Meilisearch) | Search | searchWorker.ts; packages/shared/search |
| ⚙️ Rule-engine automation | Content Mgmt | ruleEngineWorker.ts; routers/rules.ts; 0.32.0 (#2547) |
| ⚙️ RSS feed auto-hoarding | Content Mgmt | feedWorker.ts; rssFeedsTable |
| ⚙️ Bookmark importers | Content Mgmt | importWorker.ts; 0.32.0 (#2495 OneTab, #2690 Readwise) |
| ⚙️ Reader view | Reader/Web UI | apps/web/app/reader/[bookmarkId]; 0.32.0 (#2527/#2691/#2696) |
| ⚙️ REST API + SDK + OpenAPI | Integrations | packages/open-api/karakeep-openapi-spec.json; packages/sdk |
| ⚙️ CLI + MCP + agentic skill | Integrations | release 0.32.0 (CLI revamp, agentic skill, MCP #2717) |
| ⚙️ Browser extensions + mobile apps | Integrations | apps/browser-extension, apps/mobile; 0.32.0 Safari (#10), mobile revamp (#2685) |
| ⚙️ Webhooks | Integrations | webhookWorker.ts; WEBHOOK_* env |
| ⚙️ Granular-scope API keys | Platform | release 0.32.0; routers/apiKeys.ts |
| ⚙️ Auth + SSO + self-hosting | Platform | NextAuth; OAUTH_*, ASSET_STORE_S3_* env; README |
The product's spine is a 5-step relay — a save fans out into async worker jobs and ends at the reader. Each step consumes(ahara) / produces(utpatti) a typed phenomenon:
The core spine is structurally clean (0 relay-gaps, 0 no-actor kriyas, 0 lifecycle gaps). The structural risk is at the edges of this spine — see Reading of the field.
Ready now: D2, D3, D4. Sequenced after a prerequisite: D1 (after D4), D5 (after D4), D6 (after D1+D2+D4). Dependency evidence marked evidenced (milestone) or heuristic (architectural inference — a hypothesis).
vimarsha_of the subsystems.upadhi/context, Reddit kriya specifies.actor → #829). Contributor-led & needs-review.specifies → #853, fixes context to Integrations subsystem.actor → #829). The headline offline feature is community-requested & unowned (no PR) — flagged deferred-but-real.upadhi.actor → #828). Maintainer-led & committed (#2660 → 0.33.0).upadhi → #856, phenomenon specifies → #856.actor → #829). Community-requested, contributor-led, deferred (driving PR conflicting & drive-by).actor → #828). Maintainer-led & committed.| # | title (verbatim) | author | assoc | maps to |
|---|---|---|---|---|
| 2882 | Add title and favourites button to browser extension | shannonr | NONE | D2 / clients |
| 2817 | Screenshot previewer does not show scroll bar | Summon528 | CONTRIBUTOR | D3 (risk) |
| 2798 | [bug][ux] Autosaving tags can autoclose the edit window when in the removed tag's feed | NotaInutilis | NONE | D6 (risk) |
| 2752 | RSS downstream should return full content | wesamjabali | NONE | RSS (dark branch S1) |
| 2694 | feat: Introduce bookmark "trash" and undo deletion button | esimkowitz | COLLABORATOR | D6 |
| 2669 | bug: removing accounts … can lock the database … (background reaping support) | MohamedBassem | COLLABORATOR | D4 |
| 2667 | feat: allow previewing rule engine rules | MohamedBassem | COLLABORATOR | D6 |
| 2660 | feat: Agentic interaction improvements for search and content extraction | MohamedBassem | COLLABORATOR | D1 |
| 2594 | Links from collaborators are not visible in public lists | karabays | NONE | D6 (risk) |
| 2591 | [FR] Basic article TTS | zblesk | NONE | reader (D2/web) |
| 2502 | Saving a page that was previously saved fails | Garrett-R | NONE | D6 (risk) |
| 2172 | Uncertain origin of alpine chrome image | MemQu | NONE | D6 (risk) |
| 1592 | Share single bookmark to anyone | Draky50110 | NONE | D6 / content |
| 863 | Chat about your bookmarks | sherry-ummen-zalando | NONE | D1 |
| 441 | [Feature request] Selfhosted semantic search | JojiiOfficial | NONE | D1 |
Closed since harvest (now done): #2779 "Mobile app - Layout optimizations" (jostrasser, NONE); #2777 "Mobile app lacks sort controls available on web" (Ben-Jian, NONE). Gating subset: #2660, #2667, #2694, #2669 (maintainer/collaborator-authored, committed). The remaining 11 open issues stay in the milestone.
| # | title (verbatim) | author | assoc | maps to |
|---|---|---|---|---|
| 2781 | Add swipe actions on mobile apps | jibe-b | NONE | D2 |
| 1977 | BUG: Full page archives no longer render correctly after the CSP blocklist | dvshenry | NONE | D3 (risk) |
| 1953 | Bug: … inference status in the backend remains unprocessed | mapleshadow | NONE | D4 (inference) |
| 1939 | Detect products on all sites | flexagoon | NONE | capture plugins (deferred) |
| 1913 | Add button to edit notes | daviddavis | NONE | D2 / web |
| 1800 | Allow to create pretty URLs for public lists and their RSS | landure | NONE | content / sharing |
| 1782 | Support for external databases (like Postgres) | Mrtenz | NONE | D5 |
| 1773 | Allow for rules to be run manually in Rule Engine | kausar007 | NONE | D6 / content |
| 1748 | Bug: High memory usage on karakeep worker during large imports (and crawlings in general) | Garrett-R | NONE | D4 (risk) |
| 1667 | Bug: Add timeouts for the image download to avoid failing the entire crawling … | Fmstrat | NONE | D3 / D4 |
| 1611 | [FR] Preflight checks on inference / browser service health before … background jobs | pdc1 | NONE | D4 |
| 1581 | List sorting inconsistent in "dropdown" | enkelmedia | NONE | D6 / web (risk) |
Closed since harvest, no longer open Backlog: #1666, #1404, #1863, #1905, #1865, #1969, #1669.
The part a flat ticket list cannot produce — the graph's read of who drives the work, what structural gaps it computed, and how each direction grounds on a real capability.
| Karta | Layer | Drives | Wiring |
|---|---|---|---|
| 👤 Maintainer (MohamedBassem) | dev-driver | D1, D4, D6 (committed) | actor → agentic-search, AI-assistant, rule-preview, trash/undo kriyas; owned via 0.33.0 issues. D4's carrier PR #2625 is a drive-by — ownership via issues. |
| 👤 Contributor community | dev-driver | D2 fixes, D3, D5 (needs-review) | actor → scraper/stealth/Postgres/mobile-fix PR kriyas |
| 👤 Worker fleet | runtime | Crawl / AI-enrich / Index core flows | runtime actor only — distinct from backlog drivers |
| 👤 End user (data hoarder) | runtime | Save + Search&read | runtime actor only |
Offline-mobile (D2) and Postgres (D5) are the two top-demand themes with no maintainer commitment — unowned/deferred. A solo-maintainer roadmap is a map of finite attention; making that explicit is the point.
vollzug capabilities have no upadhi from any flow: Video archiving, OCR, RSS auto-hoarding, Bookmark importers, REST API+SDK, Webhooks. The modeled core spine only applies crawl/AI/search — so bugs in those branches (RSS full-content #2752, image-download timeout #1667, list-sorting #1581) have no lifecycle to reason about. The directions cluster on the crawl→AI→search spine and under-serve the secondary ingestion/output branches. Either model a 2nd estafeta (RSS → import → archive → export) or declare those out-of-spine.⚙️ CLI + MCP + agentic skill is a bare 0.32 release fact referenced as upadhi but produced by no flow. If the conversational layer (D1) is to be first-class, this capability needs a producing estafeta — otherwise "agentic Karakeep" stays bolted to the side.vimarsha_of to the Platform/AI subsystems, not a single kriya — cross-cutting with no flow owner. This is why D4 is the critical-path foundation, and why it should be standing capacity work, not a discrete ticket.All other structural detectors clean: 0 leaked estafetas, 0 relay gaps, 0 no-actor kriyas, 0 lifecycle gaps, 0 deadlocks, 0 mode conflicts. (Excluded as modeling artifacts: shipped-state facts #841 client-side crawl & #855 granular API keys legitimately have no producing flow.)
| Direction | Ground capability extended | Graph link |
|---|---|---|
| D1 AI conversational | AI summarization (#843), Embeddings (#844), Meilisearch (#846) | driving kriyas → upadhi |
| D2 Mobile offline | Browser extensions + mobile apps (#853) | offline phenomenon specifies; fixes context |
| D3 Crawling resilient | Headless-browser crawling (#838), Full-page archival (#839) | driving kriyas upadhi/context; Reddit kriya specifies |
| D4 Hardens for scale | Platform/Storage (#825) + AI/Inference (#820) (cross-capability) | risks vimarsha_of subsystems |
| D5 Storage pluggable | Auth + SSO + self-hosting (#856) | Postgres kriya upadhi; phenomenon specifies |
| D6 0.33.0 release | Rule-engine automation (#847) + Content Mgmt | carrier kriyas upadhi/context |
Query basis: all 588 open issues (PRs excluded), issues?state=open paginated via REST; reaction_count = reactions.total_count, comments = comments; author_association per-number. Raw, full-set figures — rankings computed over the complete open-issue set, not the capped subset.
| Rank | # | title | author (assoc) | reactions | disposition |
|---|---|---|---|---|---|
| 1 | 1077 | Offline cache on Mobile app. | venci1ty (NONE) | 51 | D2 — included (unowned, flagged) |
| 2 | 414 | Bypassing cookie and GDPR banner | TurbulenceDeterministe (NONE) | 40 | D3 — included |
| 3 | 1782 | Support for external databases (like Postgres) | Mrtenz (NONE) | 32 | D5 — included (deferred) |
| 4 | 2189 | Enhanced Prompt Customization for Advanced Tagging Workflows | DaveG7 (NONE) | 28 | D1 — included (folded, no PR) |
| 5 | 274 | Cache Hoards while away from server. | hockeygoalie35 (NONE) | 20 | D2 — included |
| 6 | 2401 | "Offline" mode for mobile app … | alexlucasdev (NONE) | 18 | D2 — included |
| 7 | 705 | "Remind me of this" feature | arcb01 (NONE) | 16 | out-of-scope — reminders, no modeled capability (deferred) |
| 8 | 739 | Reddit full page archiving. | nicktheone (NONE) | 15 | D3 — included |
| 9 | 295 | [Feature request] Allow Epub generation from multiple bookmarks | winston0410 (NONE) | 15 | out-of-scope — export, dark branch S1 (deferred) |
| 10 | 863 | Chat about your bookmarks | sherry-ummen-zalando (NONE) | 15 | D1 — included (0.33.0) |
| 11 | 1652 | [FR] Option to enable archive.org as a middle-man | MelanieTanaka (NONE) | 15 | D3-adjacent — archival fallback (deferred, untriaged) |
| 12 | 75 | Feature: Import / Export for backup purposes | georgzoeller (NONE) | 14 | out-of-scope — import/export, dark branch S1 (deferred) |
| 13 | 329 | [FR] Support uploading SingleFile .html files from local filesystem | huyz (NONE) | 12 | D3-adjacent — ingestion (deferred) |
| 14 | 237 | Mobile app: don't open after hoarding | DominikBritz (NONE) | 12 | D2 — included (mobile UX) |
| 15 | 836 | PDF Highlighting Feature | DavidMoffatt-web (NONE) | 11 | out-of-scope — reader feature (deferred) |
| Rank | # | title | author (assoc) | comments | disposition |
|---|---|---|---|---|---|
| 1 | 414 | Bypassing cookie and GDPR banner | TurbulenceDeterministe (NONE) | 63 | D3 — included |
| 2 | 2344 | Memory leak in 0.30 … RAM growing | nkkfs (NONE) | 54 | D4 — included (top driver) |
| 3 | 1166 | provide a VNC client to log in user websites on the puppeteer instance | maelp (CONTRIBUTOR) | 39 | out-of-scope — status/icebox (deferred upstream) |
| 4 | 739 | Reddit full page archiving. | nicktheone (NONE) | 31 | D3 — included |
| 5 | 674 | Failed to connect to the browser instance, will retry in 5 secs | snowdream (NONE) | 24 | D3 — included (risk) |
| 6 | 517 | Degraded performance when rendering large images in the bookmarkgrid | Antebios (NONE) | 22 | D4-adjacent — perf (deferred, S3 theme) |
| 7 | 75 | Import / Export for backup purposes | georgzoeller (NONE) | 20 | out-of-scope — dark branch S1 (deferred) |
| 8 | 185 | How to verify hoarder app is working with the local ollama | lihw (NONE) | 20 | D1 — included (Ollama samshaya) |
| 9 | 424 | inference job failed | hujh818 (NONE) | 19 | D4 — included (risk) |
| 10 | 902 | Loading main page makes server CPU max out | freakshock88 (NONE) | 16 | D4 — included (driver) |
| 11 | 511 | [FR] Add support for authentication proxy headers | cyruz-git (NONE) | 15 | D5-adjacent — auth (deferred, icebox) |
| 12 | 1748 | High memory usage on karakeep worker during large imports | Garrett-R (NONE) | 15 | D4 — included (Backlog) |
| 13 | 2401 | "Offline" mode for mobile app … | alexlucasdev (NONE) | 14 | D2 — included |
| 14 | 815 | Failed to determine the content-type for the url | GreenMonito (NONE) | 14 | D3 — included (content-type samshaya) |
| 15 | 978 | Link Banners Not Loading | lmalmoreno (NONE) | 14 | out-of-scope — question, unreproduced (deferred) |
Survival check: the top-3 reacted (#1077, #414, #1782) and top-3 commented (#414, #2344, #1166) all appear above with an explicit disposition. The only top-ranked items not pulled into a direction are out-of-scope by capability (#705 reminders, #295/#75 export, #836 PDF-highlight, #1166 VNC/icebox, #978 unreproduced) — each marked deferred/out-of-scope, none silently dropped. The export/import cluster (#75, #295) corroborates structural risk S1.
repo-roadmap skill · realm github-skill-test · focus holon 📦 Karakeep (#818) · 6 bianhua (#1002–#1007).
Live item state re-verified 2026-06-27 via gh; mergeable=null / UNSTABLE treated as unknown, never "clean."
Directions are hypotheses (shabda) until the maintainer confirms them.