Gurren

Gurren is a Windows desktop overlay for developers. Press Ctrl+Shift+Space (or F4), ask how to use Cursor, VS Code, or Google Antigravity, and get answers from a local knowledge vault—with an optional on-screen pointer to UI elements.

• Local-first: Levels 1–2 use a tag index and ChromaDB over your vault; no network required for routine answers.
• Level 3: Optional escalation to the Anthropic API (BOB_MODEL, e.g. Claude Sonnet) when the vault is not confident.
• Memory: Usage patterns are written under vault/user/ (profile, history, unknown queries, memory insights).

This repository ships the knowledge vault (vault/) and search index (data/) needed to run out of the box. Personal state under vault/user/ is created on your machine at runtime and is not committed to git.

Chroma collection name: The app expects a collection named gurren_vault. If you rebuild the index from an older artifact using guren_vault, run python scripts/index_vault.py again so names stay in sync.

---

Requirements

Tool	Version	Notes
Windows	10/11	Primary target; overlay and IDE detection are Windows-focused
Node.js	20+	For Electron, React, and the build toolchain
npm	9+	Bundled with Node
Python	3.10+	For Chroma server binary, indexing scripts, and optional vault rebuild
Git	any recent	To clone the repository

Optional (Level 3 only):

• Anthropic API key — set in .env as ANTHROPIC_API_KEY

---

Installation and run (step by step)

1. Clone the repository

git clone https://github.com/nothariharan/gurren.git
cd gurren

The clone must include vault/ and data/ at the project root (next to package.json). If either folder is missing, pull the latest main branch or ensure the repository was pushed with those directories.

2. Install Node.js dependencies

npm install

This installs Electron, React, ChromaDB client (chromadb npm package), and build tools. No global Node packages are required.

3. Set up Python (virtual environment recommended)

Create and activate a virtual environment in the project root:

python -m venv .venv
.\.venv\Scripts\Activate.ps1

If PowerShell blocks activation, run once:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Install Python dependencies (includes ChromaDB and the chroma CLI used by the app):

pip install -r requirements.txt

Verify the Chroma server binary is available:

where chroma

You should see a path under .venv\Scripts\chroma.exe. The Electron app prefers that binary automatically; you can override with CHROMA_BIN in .env if needed.

4. Configure environment variables

copy .env.example .env

Edit .env in the project root:

Variable	Required	Description
ANTHROPIC_API_KEY	Level 3 only	Your Anthropic API key; leave empty if you only use local vault answers
BOB_MODEL	Level 3 only	e.g. claude-sonnet-4-20250514
CHROMA_PORT	No	Default 8765 — HTTP port for the local Chroma server
CHROMA_HOST	No	Default 127.0.0.1
CHROMA_BIN	No	Full path to chroma.exe if not found in .venv

Levels 1–2 work without ANTHROPIC_API_KEY.

5. Build and start the application

npm start

This runs npm run build (TypeScript main process + Vite renderer) and launches Electron in production mode.

For development after the first build:

npm run dev

6. Use Gurren

1. Open Cursor, VS Code, or Antigravity (supported IDEs).
2. Press Ctrl+Shift+Space or F4 to open the Gurren panel.
3. Type a question (e.g. “How do I open the command palette?”) and submit.
4. If the answer references a UI control, a mint pointer appears on screen over your desktop.
5. Tray icon: click to show/hide the panel; Quit exits the app.

On first query, Gurren creates vault/user/ and writes profile/history files locally. Do not commit those files.

---

What gets installed where

gurren/
├── node_modules/     ← npm install
├── .venv/            ← python -m venv + pip install (local, gitignored)
├── vault/            ← knowledge markdown (committed, except vault/user/*)
├── data/             ← tag-index.json, coordinate-map.json, chroma_db/ (committed)
├── dist/             ← built app (npm run build, gitignored)
└── .env              ← your secrets (gitignored; copy from .env.example)

---

Troubleshooting

Chroma port already in use

If you see errors about 8765 or heartbeat failures:

taskkill /IM chroma.exe /F

Or set a different CHROMA_PORT in .env and restart the app.

“Search index is not ready yet”

• Ensure data/chroma_db exists in the repo root.
• Confirm chroma runs: after npm start, check the terminal for [chroma] logs.
• Rebuild the index (see below) if the collection name or files are missing.

Python / Chroma not found

• Activate .venv before pip install and ensure where chroma points to .venv\Scripts\chroma.exe.
• Set CHROMA_BIN in .env to that full path.

Level 3 / LLM

• Anthropic: ANTHROPIC_API_KEY (optional BOB_MODEL).
• Bedrock: If the Anthropic key is empty or the Anthropic request fails, Gurren uses Amazon Bedrock when AWS_REGION, AWS_ACCESS_KEY_ID, and AWS_SECRET_ACCESS_KEY are set (optional BEDROCK_MODEL_ID; defaults align with scripts/bedrock_client.py).
• Levels 1–2 do not call an LLM.

Rebuild after pulling changes: npm run build, then restart the app so dist/ picks up the new main bundle.

PowerShell npm or python not recognized

Install Node.js LTS and Python, then reopen the terminal. Enable “Add Python to PATH” during Python setup.

---

Rebuilding the index (advanced)

If you change vault notes or need a fresh vector index:

.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python scripts/index_vault.py

This regenerates data/chroma_db and data/tag-index.json from all markdown under vault/ except vault/user/. It does not regenerate data/coordinate-map.json or data/intent-keywords.json—keep those from the repo unless you maintain them separately.

Indexing downloads the embedding model on first run and may take about a minute.

---

Project layout

├── package.json
├── electron-builder.yml
├── vite.config.ts
├── requirements.txt
├── .env.example
├── src/
│   ├── main/          # Electron main, retrieval, memory, IPC
│   ├── renderer/      # Panel UI + overlay pointer
│   └── types/
├── scripts/           # Vault scrape / seed / index (Python)
├── vault/             # Knowledge notes (vault/user/ is runtime-only, gitignored)
└── data/              # Tag index, ChromaDB, coordinate map, intent keywords

---

Packaging (Windows installer)

With vault/ and data/ present at build time:

npm run pack

electron-builder outputs to release/. Personal vault/user/ content is excluded from the packaged vault.

---

License

MIT (see team / hackathon submission for attribution).