{"id":51163774,"url":"https://github.com/tonkonozhenko-mi/ai_private_workspace","last_synced_at":"2026-06-26T17:00:29.975Z","repository":{"id":365286201,"uuid":"1264158312","full_name":"tonkonozhenko-mi/ai_private_workspace","owner":"tonkonozhenko-mi","description":"Local-first desktop app (macOS \u0026 Windows) to chat with your own projects — offline RAG over your files, grounded answers with sources. No cloud, no accounts.","archived":false,"fork":false,"pushed_at":"2026-06-23T23:07:28.000Z","size":167957,"stargazers_count":0,"open_issues_count":11,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-23T23:19:21.692Z","etag":null,"topics":["ai","desktop-app","fastapi","llama-cpp","llm","local-first","macos","offline","ollama","privacy","rag","react","tauri","windows"],"latest_commit_sha":null,"homepage":"https://github.com/tonkonozhenko-mi/ai_private_workspace/releases/latest","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tonkonozhenko-mi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["tonkonozhenko-mi"]}},"created_at":"2026-06-09T16:03:35.000Z","updated_at":"2026-06-23T23:05:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tonkonozhenko-mi/ai_private_workspace","commit_stats":null,"previous_names":["tonkonozhenko-mi/ai_private_workspace"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/tonkonozhenko-mi/ai_private_workspace","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tonkonozhenko-mi%2Fai_private_workspace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tonkonozhenko-mi%2Fai_private_workspace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tonkonozhenko-mi%2Fai_private_workspace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tonkonozhenko-mi%2Fai_private_workspace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tonkonozhenko-mi","download_url":"https://codeload.github.com/tonkonozhenko-mi/ai_private_workspace/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tonkonozhenko-mi%2Fai_private_workspace/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34825611,"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-26T02:00:06.560Z","response_time":106,"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","desktop-app","fastapi","llama-cpp","llm","local-first","macos","offline","ollama","privacy","rag","react","tauri","windows"],"created_at":"2026-06-26T17:00:21.639Z","updated_at":"2026-06-26T17:00:29.964Z","avatar_url":"https://github.com/tonkonozhenko-mi.png","language":"Python","funding_links":["https://github.com/sponsors/tonkonozhenko-mi"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/brand/logos/pigeon-mark.png\" alt=\"AI Private Workspace\" width=\"200\"\u003e\n\u003c/p\u003e\n\n# AI Private Workspace\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/tonkonozhenko-mi/ai_private_workspace/releases/latest\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/tonkonozhenko-mi/ai_private_workspace?label=latest\u0026sort=semver\u0026style=flat-square\u0026color=2ea44f\" alt=\"Latest release\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/tonkonozhenko-mi/ai_private_workspace/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/downloads/tonkonozhenko-mi/ai_private_workspace/total?style=flat-square\u0026color=2ea44f\" alt=\"Downloads\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/tonkonozhenko-mi/ai_private_workspace/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/tonkonozhenko-mi/ai_private_workspace/ci.yml?branch=main\u0026style=flat-square\u0026label=CI\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"#install-and-first-run\"\u003e\u003cimg src=\"https://img.shields.io/badge/platform-macOS%20%7C%20Windows-lightgrey.svg?style=flat-square\" alt=\"Platform: macOS | Windows\"\u003e\u003c/a\u003e\n  \u003ca href=\"#safety-model\"\u003e\u003cimg src=\"https://img.shields.io/badge/local--first-no%20cloud-2ea44f.svg?style=flat-square\" alt=\"Local-first, no cloud\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.bestpractices.dev/projects/13357\"\u003e\u003cimg src=\"https://www.bestpractices.dev/projects/13357/badge\" alt=\"OpenSSF Best Practices\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://scorecard.dev/viewer/?uri=github.com/tonkonozhenko-mi/ai_private_workspace\"\u003e\u003cimg src=\"https://img.shields.io/ossf-scorecard/github.com/tonkonozhenko-mi/ai_private_workspace?style=flat-square\u0026label=OpenSSF%20Scorecard\" alt=\"OpenSSF Scorecard\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.codefactor.io/repository/github/tonkonozhenko-mi/ai_private_workspace\"\u003e\u003cimg src=\"https://www.codefactor.io/repository/github/tonkonozhenko-mi/ai_private_workspace/badge\" alt=\"CodeFactor\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://api.reuse.software/info/github.com/tonkonozhenko-mi/ai_private_workspace\"\u003e\u003cimg src=\"https://api.reuse.software/badge/github.com/tonkonozhenko-mi/ai_private_workspace\" alt=\"REUSE compliance\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-Apache_2.0-blue.svg?style=flat-square\" alt=\"License: Apache 2.0\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n**AI Private Workspace** is a local-first desktop app (macOS and Windows) for\nunderstanding your own projects. Point it at a folder and ask anything — about\nyour code, infrastructure, CI/CD, or docs. **It reads, explains, and helps you\nunderstand; it does not change your project.** Once the local model is downloaded\nit runs fully offline and grounds every answer in your real files. Nothing leaves\nyour computer.\n\n### ⬇️ [Download the latest release](https://github.com/tonkonozhenko-mi/ai_private_workspace/releases/latest)\n\nmacOS (Apple Silicon / Intel) and Windows x64 installers are on the\n[releases page](https://github.com/tonkonozhenko-mi/ai_private_workspace/releases/latest).\n\n\u003e This README and [CHANGELOG](CHANGELOG.md) track the `main` branch, which is\n\u003e usually ahead of the latest tagged release. For a stable build, download from\n\u003e the releases page; to try the newest work, build from source.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/screenshots/01-ask.png\" alt=\"Ask a question about your project and get an answer grounded in local sources\" width=\"820\"\u003e\n\u003c/p\u003e\n\n## Contents\n\n- [First launch (unsigned app)](#first-launch-unsigned-app)\n- [Install and first run](#install-and-first-run)\n- [What it does](#what-it-does)\n- [Project intelligence and read-only analysis](#project-intelligence-and-read-only-analysis)\n- [Local engines](#local-engines)\n- [How search works](#how-search-works)\n- [Safety model](#safety-model)\n- [Main product flows](#main-product-flows)\n- [Troubleshooting](#troubleshooting)\n- [Current status](#current-status)\n- [Repository layout](#repository-layout)\n- [Developer startup](#developer-startup)\n- [Validation](#validation)\n- [Contributing](#contributing)\n- [License](#license)\n\n## First launch (unsigned app)\n\nThe app isn't code-signed with a paid certificate yet, so both systems show a\none-time warning for unsigned downloaded apps. It's the standard prompt, not a\nproblem with the app.\n\n**Windows.** SmartScreen may say \"Windows protected your PC.\" Click **More info →\nRun anyway**.\n\n**macOS.** It may say the app \"is damaged and can't be opened.\" It is not\ndamaged — macOS just blocks unsigned downloaded apps. After dragging it into\n**Applications**, run this once in Terminal, then open it normally:\n\n```bash\nxattr -cr \"/Applications/AI Private Workspace.app\"\n```\n\nOn a managed/work machine (configuration profile / MDM), this may be blocked by\nIT policy; there the app needs to be signed/notarized or deployed through your\norganization's device management.\n\n## Install and first run\n\nFrom the download to your first answer — eight steps, every one of them on your\nown Mac (no cloud, no accounts):\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"50%\"\u003e\u003cimg src=\"docs/assets/screenshots/step-1-install.png\" alt=\"Drag the app into the Applications folder\" width=\"100%\"\u003e\u003cbr\u003e\u003csub\u003e\u003cb\u003e1 · Install\u003c/b\u003e — open the downloaded \u003ccode\u003e.dmg\u003c/code\u003e and drag \u003cb\u003eAI Private Workspace\u003c/b\u003e into \u003cb\u003eApplications\u003c/b\u003e.\u003c/sub\u003e\u003c/td\u003e\n    \u003ctd width=\"50%\"\u003e\u003cimg src=\"docs/assets/screenshots/step-2-welcome.png\" alt=\"Local-first welcome screen\" width=\"100%\"\u003e\u003cbr\u003e\u003csub\u003e\u003cb\u003e2 · Welcome\u003c/b\u003e — launch it and click \u003cb\u003eOpen a project folder\u003c/b\u003e. Your files stay on your computer.\u003c/sub\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"50%\"\u003e\u003cimg src=\"docs/assets/screenshots/step-3-create-workspace.png\" alt=\"Create a local workspace and choose a role lens\" width=\"100%\"\u003e\u003cbr\u003e\u003csub\u003e\u003cb\u003e3 · Create a workspace\u003c/b\u003e — name it, pick the folder, choose a role lens (DevOps, Developer, Tester, BA…) and whether the project is remembered.\u003c/sub\u003e\u003c/td\u003e\n    \u003ctd width=\"50%\"\u003e\u003cimg src=\"docs/assets/screenshots/step-4-scan.png\" alt=\"Scan your project files locally\" width=\"100%\"\u003e\u003cbr\u003e\u003csub\u003e\u003cb\u003e4 · Scan\u003c/b\u003e — a quick local pass lists your files so the AI knows what it can search. Nothing leaves the Mac.\u003c/sub\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"50%\"\u003e\u003cimg src=\"docs/assets/screenshots/step-5-engine.png\" alt=\"Choose a local engine and download models\" width=\"100%\"\u003e\u003cbr\u003e\u003csub\u003e\u003cb\u003e5 · Choose an engine\u003c/b\u003e — built-in \u003cb\u003ellama.cpp\u003c/b\u003e (nothing to install) or \u003cb\u003eOllama\u003c/b\u003e. Downloads two small local models (answer + search), then \u003cb\u003eStart engine\u003c/b\u003e.\u003c/sub\u003e\u003c/td\u003e\n    \u003ctd width=\"50%\"\u003e\u003cimg src=\"docs/assets/screenshots/step-6-build-context.png\" alt=\"Build local search context (RAG index)\" width=\"100%\"\u003e\u003cbr\u003e\u003csub\u003e\u003cb\u003e6 · Build context\u003c/b\u003e — turn the scanned files into a searchable local index so answers come from your real project.\u003c/sub\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"50%\"\u003e\u003cimg src=\"docs/assets/screenshots/step-7-folder-access.png\" alt=\"macOS folder access permission prompt\" width=\"100%\"\u003e\u003cbr\u003e\u003csub\u003e\u003cb\u003e7 · Grant folder access\u003c/b\u003e — macOS asks once before the app reads your folder. Click \u003cb\u003eAllow\u003c/b\u003e.\u003c/sub\u003e\u003c/td\u003e\n    \u003ctd width=\"50%\"\u003e\u003cimg src=\"docs/assets/screenshots/step-8-ask.png\" alt=\"Ask questions and get answers grounded in your project\" width=\"100%\"\u003e\u003cbr\u003e\u003csub\u003e\u003cb\u003e8 · Ask\u003c/b\u003e — ask about your code, infra, CI/CD, or setup. Answers cite sources from your project and stay on your computer.\u003c/sub\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\nThe app also follows your system light/dark preference:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/screenshots/06-dark-ask.png\" alt=\"Ask screen in dark theme\" width=\"720\"\u003e\n\u003c/p\u003e\n\n## A few more screens\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"50%\"\u003e\u003cimg src=\"docs/assets/screenshots/14-command-palette.png\" alt=\"Command palette: jump to any repo, group, section or file\" width=\"100%\"\u003e\u003cbr\u003e\u003csub\u003e\u003cb\u003eCommand palette\u003c/b\u003e — \u003ccode\u003eCmd/Ctrl-K\u003c/code\u003e to jump to any repository, group, section, or file.\u003c/sub\u003e\u003c/td\u003e\n    \u003ctd width=\"50%\"\u003e\u003cimg src=\"docs/assets/screenshots/13-security.png\" alt=\"Security lens: scanners in CI and security-relevant findings\" width=\"100%\"\u003e\u003cbr\u003e\u003csub\u003e\u003cb\u003eSecurity lens\u003c/b\u003e — which scan/audit steps run in CI, plus the security-relevant findings, each backed by a file.\u003c/sub\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003e Screenshots are taken on a demo project and any project names, file paths, and contributor details are redacted.\n\n## What it does\n\n- **Understands your project.** Point it at a folder; a local scan recognizes what's there — Terraform, Terragrunt, Kubernetes, Helm, Docker, Python, GitLab CI, docs, and more.\n- **Searches only when you ask.** The local index is built on an explicit action and respects your `.gitignore`, so virtualenvs, build output, caches, and `.env` secrets never enter it.\n- **Answers from your files.** Responses are grounded in retrieved sources with citations — not guesses — and your conversations, history, model choices, and reports stay on your computer.\n- **Groups several repositories into one project.** Real systems span more than one repo. A group lets Ask, Home, and Intelligence work across a whole portfolio at once — environments compared in a repo×environment matrix, technologies split into shared-vs-unique, and risks grouped by pattern — while each repo stays an independent workspace underneath.\n- **Built to navigate.** A **Cmd/Ctrl-K command palette** jumps to any repository, group, section, or file. Click a file anywhere and a **file inspector** opens its owner, what it changes together with, what it connects to in the map, and the risks touching it.\n- **Runs on two local engines.** Built-in **llama.cpp** (nothing to install) or **Ollama**, switchable per project, with the answer and search models managed separately. See [Local engines](#local-engines).\n- **Writes nothing without consent.** Ask can turn an answer into a file draft, written only after you confirm the path and exact content. Nothing else runs on its own — the app reads and explains, it never executes commands or changes your machine.\n\n## Project intelligence and read-only analysis\n\nBeyond search, the app builds a **map of your project** and gives you several\nread-only tools over it. The guiding principle is the same throughout: every\nstatement is backed by something in your own files, the facts are produced\ndeterministically wherever possible, and the analysis is **read-only by\nconstruction** — it looks and explains, it never writes files, runs commands, or\nchanges anything on your computer.\n\n- **Project Intelligence** — a role-neutral evidence graph with an interactive **Map**, **role lenses** (Developer / DevOps / Tester / Business analyst) and an adaptive role dashboard, a **CI/CD flow** view, **Cloud** \u0026 **References** tabs, environment comparison and deployment flow.\n- **Security review** — which scan/audit steps already run in CI and which findings are security-relevant, each with a recommendation and its source file. It reports on scanners; it never runs one.\n- **Project activity \u0026 file inspector** — a read-only briefing from git history (activity, ownership, branch strategy, change coupling) and a per-file lens (owner, what it changes together with, its blast radius, the risks touching it).\n- **Project groups** — treat several repositories as one project: group **Ask**, a portfolio **Home**, and group **Intelligence** that *compares rather than merges*.\n- **Memory \u0026 profile** — local, fully-editable project memory + handbook and a cross-project **\"About you\"** profile, with **review-first** capture.\n- **The Watcher \u0026 change history** — deterministic *\"what changed since I last looked?\"*, kept as a dated, date-grouped **History** journal you can revisit (filled cheaply from git), with an optional one-tap LLM recap of the commits.\n- **Stays current** — when files change, refresh the model's knowledge with an **incremental re-index** that re-embeds only the files whose content changed (by hash, not the whole repo). Then just ask *\"what changed today?\"* in **Ask** — it pulls the dated change journal into the answer.\n- **The Investigator** — a bounded **ReAct** loop over read-only tools that answers multi-step questions with a transparent trace and the sources it consulted.\n\nEvery finding reads as a lead for a human, not a verdict: what was found, **why it\nmay matter**, where (one click to the inspector), and **what to check yourself**.\n\n**Full detail** — each tool, the Investigator's toolbox and ReAct protocol, the\ntrust guarantees, and example questions — lives in\n[`docs/PROJECT_INTELLIGENCE.md`](docs/PROJECT_INTELLIGENCE.md).\n\n## Local engines\n\nEverything runs locally — no cloud, no accounts — on whichever engine you prefer,\nchosen per project and switchable at any time before indexing:\n\n- **Built-in llama.cpp** — the app bundles `llama-server` and runs GGUF models\n  with **nothing to install**. Add any model straight from a Hugging Face repo\n  and the app resolves a sensible quant for you. Best for a zero-setup start.\n- **Ollama** — if you already use Ollama, point the app at it and keep your\n  existing models and tags. Best if you live in the Ollama ecosystem.\n\nBoth paths are first-class: the same setup flow, model manager, answer metrics\n(real token counts, generation speed, and context-window usage), and a live RAM\nindicator work identically. The answer model and the search (embedding) model are\nmanaged separately, so you can mix a strong answer model with a small, fast\nembedder.\n\nThe **bundled llama.cpp** path also unlocks engine features Ollama doesn't expose\nto us: it starts with **Flash Attention** (faster generation, smaller KV cache),\nkeeps a **warm prompt-prefix cache on disk**, can constrain answers to a\n**JSON Schema** (guaranteed-parseable output for agents), and reports **exact\ntoken counts** so the context-window budget is precise rather than estimated.\nThese are best-effort and degrade gracefully — startup falls back to safe\ndefaults if a build doesn't support a flag. Tunables: `AI_WORKSPACE_LLAMA_FLASH_ATTN`\n(default on) and `AI_WORKSPACE_LLAMA_PARALLEL` (default `1`).\n\n## How search works\n\nAnswers are grounded in your project through a **hybrid retrieval** pipeline —\nthe same approach used by strong production RAG systems, running fully on your\nmachine:\n\n- **Dense vector search** — your question and every chunk are embedded; the\n  closest chunks by cosine similarity are retrieved. Great for meaning and\n  paraphrase, but weak at exact names.\n- **Keyword search (BM25)** — a full-text index (SQLite FTS5) over the chunk text\n  **and its file path**, so exact identifiers — folder names like `dev`, variable\n  names like `\u003cproject name\u003e_allowed_cidr` — are matched literally, which pure vector search\n  misses.\n- **Reciprocal Rank Fusion (RRF)** — merges the vector and keyword rankings\n  without having to normalize their very different score scales.\n- **Path / environment boost** — chunks whose file-path segments match query\n  terms (e.g. `dev`, `\u003cproject name\u003e`) are lifted, so environment-specific questions land on\n  the file under that path instead of a similarly-worded one elsewhere.\n- **Per-file diversity** — one large file can't fill the whole answer, so results\n  span more of the codebase.\n\nIt degrades gracefully: if keyword indexing is unavailable it falls back to\nvector-only search. On the roadmap: a cross-encoder **reranker** for an extra\nprecision pass.\n\n## How it all connects\n\nThe end-to-end flow at a glance:\n\n![AI Private Workspace flow](docs/assets/product-flow.svg)\n\n\u003e Capturing the screenshots above? See [`docs/assets/screenshots/CAPTURE_GUIDE.md`](docs/assets/screenshots/CAPTURE_GUIDE.md) for the exact shots and file names.\n\n## Safety model\n\nAI Private Workspace is designed around explicit user control:\n\n- The frontend never executes shell commands.\n- App launch never starts scans, indexing, rebuilds, or model downloads.\n- Model download execution is disabled by default and must be enabled backend-side in trusted local runtime only.\n- The local analysis is read-only — it never executes commands or modifies files.\n- Approval gates record user intent; they do not execute anything automatically.\n- Ask never writes a generated file automatically. The user must open the review panel and explicitly create it.\n- Runtime data, local databases, caches, and build artifacts are excluded from source archives.\n\n## Main product flows\n\nThe frontend keeps the common workflows focused and progressively reveals technical detail:\n\n- **Ask** answers from workspace context and can prepare a safe, editable file draft.\n- **Models** separates Overview, Choose \u0026 install, Compare, and Tuning.\n- **Choose \u0026 install** uses backend-provided recommendations and accepts custom\n  Ollama model tags. A desktop-owned backend can safely run the exact approved\n  `ollama pull \u003cmodel\u003e` job, while browser development keeps downloads disabled\n  unless explicitly configured.\n- **Tuning** holds per-model answer settings, while **Compare** runs explicit model comparisons. The single editable **Skills** library lives in **Settings** (one place to edit or create skills, picked per question in Ask).\n- **Settings** shows a plain-language readiness checklist for the local backend, project scan, search context, and local AI.\n\n## Troubleshooting\n\n**Windows — \"Windows protected your PC\" (SmartScreen).** The app isn't\ncode-signed yet, so Windows warns on first launch. Click **More info → Run\nanyway**. It's the standard prompt for unsigned apps, not a problem with the app.\n\n**macOS — \"AI Private Workspace is damaged and can't be opened\".** Not damaged —\nmacOS blocks unsigned downloaded apps. After dragging it into **Applications**,\nrun this once in Terminal, then open it normally:\n\n```bash\nxattr -cr \"/Applications/AI Private Workspace.app\"\n```\n\n**The app won't start / \"backend startup failed\".** Check the logs and attach\nthem to a bug report:\n\n- macOS: `~/Library/Application Support/AI Private Workspace/logs/`\n- Windows: `%LOCALAPPDATA%\\AI Private Workspace\\logs\\`\n\n`backend.log` has the engine's own output; `desktop-supervisor.log` shows what the\nlauncher searched for.\n\n**Which engine should I pick?** Use **built-in llama.cpp** for a zero-setup start\n(nothing to install). Choose **Ollama** if you already use it and want your\nexisting models. You can switch per project before the index is built.\n\n**Answers ignore my files.** Make sure you ran **Build context** after scanning —\nanswers are grounded only once the local index exists. Changing the embedding\n(search) model requires rebuilding the index, since it creates a different vector\nspace.\n\n## Current status\n\nPre-1.0 and actively developed. Each tagged release builds from CI into\nsigned-per-architecture macOS DMGs (Apple Silicon + Intel) and a Windows x64\ninstaller, with in-app auto-update. The app is usable day to day on both local\nengines; the road to 1.0 focuses on code signing (so there's no SmartScreen /\nGatekeeper warning) and broader QA.\n\nEvery release also publishes **SHA256 checksums** (`SHA256SUMS.txt`), an **SPDX\nSBOM** (`sbom.spdx.json`) of the bundled dependencies, and an **automated-test\nreport** (`TEST-REPORT.md`) of what actually ran — so you can verify what you\ndownload.\n\nThe backend is covered by a deterministic test suite (600+ tests over the domain,\nuse cases, and API), run on every push and pull request. Each CI run renders a\npass/fail summary on its page and attaches the JUnit results, so the test state is\nvisible at a glance rather than buried in logs.\n\nSee:\n\n- [Roadmap](docs/ROADMAP.md)\n- [Start here](docs/START_HERE.md)\n- [Architecture](docs/ARCHITECTURE.md)\n- [v1 product completion roadmap](docs/V1_PRODUCT_COMPLETION_ROADMAP.md)\n\n## Repository layout\n\n```text\nbackend/     FastAPI backend, domain services, adapters, tests\nfrontend/    React/Vite UI\ndocs/        product, architecture, release, and packaging docs\nscripts/     local runtime, audit, packaging, and release helper scripts\nassets/      brand assets (app icons, logos)\n.github/     CI workflows and contribution templates\n```\n\n## Developer startup\n\nBackend:\n\n```bash\ncd backend\npython -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\nuvicorn app.main:app --reload\n```\n\nFrontend:\n\n```bash\ncd frontend\nnpm ci\nnpm run dev\n```\n\nFor the current macOS developer-safe launcher:\n\n```bash\nchmod +x scripts/launch_macos.command scripts/create_macos_shortcut.sh\n./scripts/launch_macos.command\n```\n\nFor the desktop app bundle, double-click `Open AI Private Workspace.command` in\nthe repository root. It rebuilds the packaged app when tracked application\nsources changed since the last successful build, otherwise it opens the\nexisting app immediately and brings its window to the front.\nWhen an update is detected while the app is already open, the launcher\nsmoke-checks the new backend on an isolated port, then asks the known app bundle\nto close cleanly before opening the updated build. It never force-kills an\nunknown process.\n\nIf the launcher cannot build or open the app, it keeps the Terminal window open\nand points to `build/desktop/open-ai-private-workspace.log`. The packaged app\nbackend also writes diagnostics to:\n\n```text\n~/Library/Application Support/AI Private Workspace/logs/\n```\n\n### Use your own models\n\nBring a different answer model on either engine. It is managed separately from\nthe search (embedding) model, so you can pair a strong answer model with a small,\nfast embedder.\n\n**Ollama** — open **Models → Choose \u0026 install**, pick **Custom Ollama model**,\nenter the exact tag (e.g. `deepseek-r1:1.5b`), and choose **Use this AI answer\nmodel**. If Ollama already has it, it is marked ready; if not, and the desktop\ndownload worker is enabled, the app runs a narrowly validated `ollama pull`.\nModels you pulled yourself in Terminal appear as detected installs, so the app\nnever claims it downloaded them.\n\n**Built-in llama.cpp** — open **Models** and, under **Add a model**, paste a\nHugging Face **GGUF** repo (e.g. `bartowski/Qwen2.5-0.5B-Instruct-GGUF`). The app\npicks a sensible quant for you, downloads it, and switches the engine — no\nfilename hunting. Your choice persists across restarts.\n\nChanging the embedding (search) model creates a different vector space, so it\nalways requires an explicit context rebuild.\n\n## Validation\n\nRun the release audit from the repository root:\n\n```bash\n./scripts/audit_release_candidate.sh\n```\n\nRun focused backend checks:\n\n```bash\ncd backend\npytest -q tests/test_final_product_status.py tests/test_product_completion_roadmap.py tests/test_release_candidate_audit.py tests/test_release_candidate_audit_script.py tests/test_source_release_archive_script.py tests/test_api_inventory.py\n```\n\nRun frontend validation:\n\n```bash\ncd frontend\nnpm ci\nnpm run build\n```\n\nCreate a clean source archive:\n\n```bash\n./scripts/prepare_source_release_archive.sh\n```\n\nThe generated archive is written to `build/release/` and must not be committed.\n\n## Runtime data policy\n\nDo not commit:\n\n- `backend/.ai-workbench/`\n- `frontend/node_modules/`\n- `frontend/dist/`\n- `build/`\n- `.pytest_cache/`\n- `__pycache__/`\n- `*.db`, `*.sqlite`, `*.sqlite3`\n\n## Contributing\n\nContributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) for the\nproduct principles, development flow, and source-hygiene rules before opening a\npull request. Security issues should follow [SECURITY.md](SECURITY.md) — please\nreport them privately rather than in a public issue.\n\n## License\n\nLicensed under the [Apache License 2.0](LICENSE). You are free to use, modify,\nand distribute this software, including in commercial and enterprise settings.\nApache-2.0 was chosen so companies can adopt the product without the legal\nfriction that more restrictive copyleft licenses introduce.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftonkonozhenko-mi%2Fai_private_workspace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftonkonozhenko-mi%2Fai_private_workspace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftonkonozhenko-mi%2Fai_private_workspace/lists"}