{"id":48963557,"url":"https://github.com/wyofalcon/huminloop","last_synced_at":"2026-04-18T03:00:52.400Z","repository":{"id":346908890,"uuid":"1190581412","full_name":"wyofalcon/HuminLoop","owner":"wyofalcon","description":"HuminLoop — ADHD-friendly AI-powered knowledge capture for developers. Screenshot, annotate, get coding prompts. Electron + Gemini 2.5 Flash. Windows \u0026 Linux.","archived":false,"fork":false,"pushed_at":"2026-04-17T00:41:22.000Z","size":527,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-17T02:36:17.993Z","etag":null,"topics":["adhd","ai","cross-platform","electron","gemini","huminloop","knowledge-management","linux","postgresql","productivity","screenshot","sqlite","windows"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/wyofalcon.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":null,"dco":null,"cla":null}},"created_at":"2026-03-24T12:27:06.000Z","updated_at":"2026-04-17T00:41:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/wyofalcon/HuminLoop","commit_stats":null,"previous_names":["wyofalcon/sciurus","wyofalcon/huminloop"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/wyofalcon/HuminLoop","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wyofalcon%2FHuminLoop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wyofalcon%2FHuminLoop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wyofalcon%2FHuminLoop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wyofalcon%2FHuminLoop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wyofalcon","download_url":"https://codeload.github.com/wyofalcon/HuminLoop/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wyofalcon%2FHuminLoop/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31954736,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T00:39:45.007Z","status":"online","status_checked_at":"2026-04-18T02:00:07.018Z","response_time":103,"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":["adhd","ai","cross-platform","electron","gemini","huminloop","knowledge-management","linux","postgresql","productivity","screenshot","sqlite","windows"],"created_at":"2026-04-18T03:00:35.203Z","updated_at":"2026-04-18T03:00:52.389Z","avatar_url":"https://github.com/wyofalcon.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/icon.png\" width=\"128\" height=\"128\" alt=\"HuminLoop icon\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eHuminLoop\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eKeeping humans in the loop.\u003c/strong\u003e\u003cbr\u003e\n  AI-powered knowledge capture for developers who build with AI.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/wyofalcon/huminloop/releases/latest\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/wyofalcon/huminloop?style=flat-square\u0026label=download\" alt=\"Latest Release\" /\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-blue?style=flat-square\" alt=\"Platform\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/AI-Gemini%202.5%20Flash-orange?style=flat-square\" alt=\"AI\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/electron-33-teal?style=flat-square\" alt=\"Electron\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/status-work%20in%20progress-yellow?style=flat-square\" alt=\"Status: WIP\" /\u003e\n\u003c/p\u003e\n\n\u003e **Heads up:** This project is a work in progress. I built it as a side tool while working on another project and it's been evolving fast. The pre-built executables are **untested** — building from source is the most reliable way to run it right now. Expect rough edges. Coming soon: full integration of the AI dev workflow system with smart triggers, hooks, and automated orchestration across your entire coding session.\n\n---\n\n## A smart note organizer that grew teeth\n\nHuminLoop started as a simple screenshot-and-note tool. Clip something from your screen, tag it, find it later. It's still great at that — **a fast, AI-organized knowledge base** for anyone who captures a lot of visual information.\n\nBut when you're deep in an AI-assisted coding session — bouncing between Claude Code, Copilot, and your terminal — you don't just need to *remember* issues, you need to *act on them*. So it evolved.\n\nNow HuminLoop is also the bridge between what you see on screen and what your AI coding tools need to fix it. Screenshot a bug, annotate it with colors your AI understands, and get a ready-to-paste prompt in seconds.\n\n**Use it as a smart note organizer.** Use it as a dev workflow tool. Or both.\n\n\u003e Built by a developer with ADHD who needed to stop losing context every time a new issue appeared. Like a squirrel burying acorns before darting to the next tree.\n\n---\n\n## Download\n\nGrab the latest release for your platform:\n\n| Platform | Download | Format |\n|----------|----------|--------|\n| **Windows** | [**Download .exe**](https://github.com/wyofalcon/huminloop/releases/latest) | NSIS installer |\n| **Linux** | [**Download .AppImage**](https://github.com/wyofalcon/huminloop/releases/latest) | AppImage (universal) or .deb |\n| **macOS** | [**Download .dmg**](https://github.com/wyofalcon/huminloop/releases/latest) | Disk image |\n\n\u003e **No Node.js required.** Download, install, run. The setup wizard handles everything else.\n\u003e\n\u003e **Note:** Pre-built executables are untested and may have issues. Building from source (below) is recommended for now.\n\u003e\n\u003e **The app is not code-signed.** Your OS will show a security warning on install:\n\u003e - **Windows:** \"Windows protected your PC\" — click **More info** then **Run anyway**\n\u003e - **macOS:** \"can't be opened because it is from an unidentified developer\" — go to **System Settings \u003e Privacy \u0026 Security** and click **Open Anyway**\n\u003e - **Linux:** No warning (AppImage may need `chmod +x` to run)\n\nOr build from source (recommended):\n\n```bash\ngit clone https://github.com/wyofalcon/huminloop.git\ncd huminloop\nnpm install\nnpm start\n```\n\n---\n\n## How It Works\n\n### Full Mode — Capture everything, let AI sort it\n\n```\nScreenshot  --\u003e  Capture popup  --\u003e  Rule engine auto-categorizes  --\u003e  AI enriches in background\n    ^                                     |                                     |\n    |                              instant match by                    summary, tags, fix prompt,\n clipboard                       window title, repo path,              URL extraction, project\n  watcher                        process name, keywords                    assignment\n```\n\n1. Take a screenshot with **Windows Snipping Tool** (`Ctrl+Win+S`) or any clipboard tool\n2. HuminLoop auto-detects it, grabs the active window title + process name\n3. The rule engine categorizes instantly (7 strategies, priority-ordered)\n4. Gemini 2.5 Flash enriches asynchronously: summary, tags, actionable fix prompt\n5. Browse, search, filter, and act on clips in the tabbed viewer\n\n### Lite Mode — Annotate, capture, get a prompt\n\n```\nDraw on screen  --\u003e  Take snippet  --\u003e  Type what needs to change  --\u003e  AI generates coding prompt\n  (red/green/pink)                                                           |\n                                                                    paste into Claude Code,\n                                                                    Copilot, or any AI tool\n```\n\n1. Open the floating **Toolbar** (tray menu) and draw on your screen\n2. Use **red** (remove/fix), **green** (add/create), **pink** (reference point)\n3. Take a snippet and type what needs to change\n4. AI generates an actionable coding prompt enriched with project context\n5. Copy or **Send to IDE** with one click\n\n---\n\n## Features\n\n### Smart Capture\n- **Clipboard watcher** that auto-detects screenshots (zero interaction)\n- **Window metadata capture** — knows what app and file you're looking at (Win32 API / xdotool / gdbus)\n- **Global hotkey** (`Ctrl+Shift+Q`) for manual capture anytime\n\n### AI-Powered Organization\n- **7-strategy rule engine** — categorizes instantly without AI (repo path, window title, process, keywords)\n- **Gemini 2.5 Flash vision** — analyzes screenshots + notes as AI fallback\n- **Inline AI prompts** — every clip gets an actionable fix prompt you can copy or send to your IDE\n- **Natural language search** — find any clip by describing what you remember\n- **1-click project summarization** — generates a side-by-side summary panel for all project notes\n\n### Annotation Colors\nThe AI understands your markup:\n- **Red** = remove, delete, or fix what is marked\n- **Green** = add or create something at this location\n- **Pink** = reference point (context, may not need changes)\n\n### Developer Workflow\n- **Send to IDE** — stage prompts + screenshots directly to your project's `.ai-workflow/context/` directory\n- **MCP Server** — 19 tools that bridge HuminLoop to Claude Code, Gemini CLI, or any MCP-compatible agent\n- **Prompt filter** — filter project clips by \"Prompts Built\" vs \"No Prompt\" to focus on what's actionable\n- **Sent-to-IDE tracking** — see which clips have already been sent to your AI coding tool\n- **Multi-clip combine** — select multiple clips and generate a unified prompt\n- **Workflow context bridge** — AI prompts enriched with current branch, recent commits, and audit findings\n- **Active-in-IDE tracking** — mark which projects are currently open\n\n### Project Management\n- **Project organization** with repo path auto-matching\n- **Complete/Trash system** with restore from trash\n- **Tag management** — add, remove, filter by tags\n- **Threaded comments** on any clip\n- **Summarize tracking** — clips darken progressively each time they're summarized\n\n### Infrastructure\n- **Dual database** — PostgreSQL (Docker) for power users, SQLite (built-in) for zero-setup\n- **Disk-based image storage** — screenshots on filesystem, not bloating the database\n- **Local HTTP API** on port 7277 — same capabilities as the UI, for external tools\n- **Cross-platform** — Windows, Linux (AppImage, deb), macOS\n- **System tray** — runs quietly in background\n- **Setup wizard** — guided first-run configuration\n\n---\n\n## Full Mode vs Lite Mode\n\n| | Full Mode | Lite Mode |\n|---|---|---|\n| **Purpose** | Capture and organize everything | Fast iteration during active dev |\n| **Tabs** | General Notes, Projects, Workflow, Settings, Help | Projects only |\n| **Project selection** | Optional | Required (one active project) |\n| **Capture popup** | Full: category, project, tags | Minimal: note + save |\n| **AI output** | Category, tags, summary, URL, fix prompt | Summary + focused coding prompt |\n| **Best for** | Research, triage, knowledge base | \"Fix this now\" during a coding session |\n\nToggle via tray menu: right-click **Switch to Lite/Full Mode**.\n\n---\n\n## Installation Guide\n\n### Option 1: Download (recommended)\n\n1. Go to the [**Releases page**](https://github.com/wyofalcon/huminloop/releases/latest)\n2. Download the installer for your platform\n3. Install and launch — the setup wizard walks you through database + AI configuration\n\n### Option 2: Build from source\n\n**Prerequisites:** Node.js 18+ and Git. Optionally Docker (for PostgreSQL).\n\n```bash\ngit clone https://github.com/wyofalcon/huminloop.git\ncd huminloop\nnpm install\nnpm start          # Launch the app\nnpm run dev        # Launch with DevTools (development mode)\n```\n\n#### Platform-specific build tools\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eWindows\u003c/strong\u003e\u003c/summary\u003e\n\n`better-sqlite3` requires C++ compilation:\n```powershell\nwinget install Microsoft.VisualStudio.2022.BuildTools\n```\nDocker Desktop from [docker.com](https://www.docker.com/products/docker-desktop/) if using PostgreSQL.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eLinux (Ubuntu/Debian)\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\nsudo apt install build-essential python3 libsqlite3-dev\nsudo apt install xdotool   # For window metadata capture on X11\n```\nDocker Engine from [docs.docker.com](https://docs.docker.com/engine/install/) if using PostgreSQL.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003emacOS\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\nxcode-select --install\n```\nWindow metadata capture is not yet implemented on macOS. All other features work.\n\n\u003c/details\u003e\n\n#### Building installers\n\n```bash\nnpm run build:win    # Windows .exe (NSIS installer)\nnpm run build:linux  # Linux .AppImage + .deb\nnpm run build:mac    # macOS .dmg\nnpm run build        # All platforms\n```\n\nOutput goes to `dist/`. Must build on the target platform (native modules).\n\n---\n\n## Database Setup\n\n### SQLite (zero setup, default)\n\nNo Docker, no config. The app uses SQLite automatically:\n- **Windows:** `%APPDATA%/huminloop/huminloop.db`\n- **Linux:** `~/.config/huminloop/huminloop.db`\n- **macOS:** `~/Library/Application Support/huminloop/huminloop.db`\n\n### PostgreSQL (Docker)\n\n```bash\ndocker compose up -d    # Starts PostgreSQL 16 on port 5433\n```\n\n| Setting | Value |\n|---|---|\n| Host | `localhost` |\n| Port | `5433` |\n| Database | `huminloop` |\n| User | `huminloop` |\n| Password | `huminloop_dev` |\n\n---\n\n## AI Setup (Optional)\n\nAI features are optional. The rule engine handles most categorization without it.\n\n### Gemini API Key (recommended — free tier)\n\n1. Go to [Google AI Studio](https://aistudio.google.com/apikey)\n2. Create an API key\n3. Add to `.env`:\n   ```\n   AI_AUTH_MODE=apikey\n   GEMINI_API_KEY=AIzaSy...\n   ```\n\n### Vertex AI (GCP)\n\n1. Enable Vertex AI API, create a Service Account with \"Vertex AI User\" role\n2. Save JSON key as `credentials.json` in project root\n3. Set `AI_AUTH_MODE=vertex` in `.env`\n\nUses native JWT auth — no Google SDK dependencies.\n\n---\n\n## MCP Server\n\nHuminLoop includes an MCP server (19 tools) that bridges AI IDE agents to your clip database. Works with Claude Code, Gemini CLI, or any MCP-compatible tool.\n\n```json\n{\n  \"mcpServers\": {\n    \"huminloop\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/huminloop/mcp-server/index.js\"]\n    }\n  }\n}\n```\n\n**Key tools:** `clip_list`, `clip_search`, `project_match`, `get_pending_prompt`, `session_context`\n\nThe MCP server auto-detects devcontainers/Codespaces and connects to the Electron app on the host.\n\n---\n\n## Environment Variables\n\nCopy `.env.example` to `.env` and customize:\n\n| Variable | Default | Description |\n|---|---|---|\n| `DB_BACKEND` | `auto` | `pg`, `sqlite`, or `auto` |\n| `POSTGRES_PASSWORD` | `huminloop_dev` | PostgreSQL password |\n| `AI_AUTH_MODE` | `auto` | `apikey`, `vertex`, or `auto` |\n| `GEMINI_API_KEY` | — | Gemini API key |\n| `HOTKEY_COMBO` | `ctrl+shift+q` | Global capture hotkey |\n| `HUMINLOOP_DEV` | — | Set to `1` for DevTools on launch |\n\n---\n\n## Architecture\n\n## Steerability \u0026 Prompt Architecture\n\nTo ensure the AI generates actionable, safe, and contextually accurate outputs, HuminLoop utilizes a structured system prompt framework. The AI (Gemini 2.5 Flash) is tightly constrained to act strictly as a localized code-assistant. During the background enrichment process, the model is forced to extract URL context and required to output structured JSON rather than raw text. This deterministic constraint minimizes parsing errors in the IPC layer and ensures the prompt generation remains highly steerable and predictable.\n\n## Limitations \u0026 Interpretability (Current Failure Modes)\n\nAs a rapid prototype exploring agentic context-switching, the system currently has known edge cases:\n* **Visual Context Extraction:** The model occasionally misinterprets highly customized, low-contrast IDE themes or deeply nested, unstructured terminal outputs. \n* **Hallucination Mitigation:** Currently, the human remains strictly \"in the loop\" to verify the generated prompt before execution. \n* **Future Roadmap:** Upcoming iterations will introduce a confidence-score threshold before auto-generating a prompt, and a migration path toward localized, containerized models to fully eliminate external API dependency for sensitive codebase context.\n\n```\nRenderer (5 windows + 2 overlays)    Main Process\n  index.html — tabbed notes viewer      Tray + global hotkey\n  capture.html — full capture popup     Clipboard watcher (1s poll)\n  lite-capture.html — lite capture      Window metadata capture\n  toolbar.html — floating draw bar      Background AI tasks\n  overlay.html — fullscreen annotator   HTTP API (localhost:7277)\n  setup.html — first-run wizard         Mode switching (full/lite)\n         |                                     |\n         +-------- IPC (preload.js) -----------+\n                                               |\n                                        Module Layer\n                                    db.js -\u003e pg | sqlite\n                                    ai.js -\u003e Gemini 2.5 Flash\n                                    rules.js -\u003e 7-strategy chain\n                                    api-server.js -\u003e REST API\n                                    window-info.js -\u003e OS-native\n```\n\n| Layer | Technology |\n|---|---|\n| Runtime | Electron 33 (context-isolated, no nodeIntegration) |\n| Database | PostgreSQL 16 or SQLite (auto-detected) |\n| AI | Gemini 2.5 Flash (API key or Vertex AI with native JWT) |\n| Rules | 7-strategy priority chain with 5-min cache |\n| Build | electron-builder (NSIS, AppImage, deb, dmg) |\n| MCP | stdio transport, 19 tools, container-aware |\n\n---\n\n## Troubleshooting\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ccode\u003enpm install\u003c/code\u003e fails on \u003ccode\u003ebetter-sqlite3\u003c/code\u003e\u003c/summary\u003e\n\nNative module needs C++ compilation:\n- **Windows:** `winget install Microsoft.VisualStudio.2022.BuildTools`\n- **Linux:** `sudo apt install build-essential python3`\n- **macOS:** `xcode-select --install`\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eApp launches as plain Node.js (no window)\u003c/summary\u003e\n\nVS Code terminals set `ELECTRON_RUN_AS_NODE=1`. Use `npm start` (the launch script fixes this automatically).\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eDocker database won't connect\u003c/summary\u003e\n\nDefault port is **5433** (not 5432). Check with:\n```bash\ndocker ps --filter name=huminloop-db\ndocker logs huminloop-db\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eAI not categorizing\u003c/summary\u003e\n\nCheck terminal for `[AI] Gemini API key ready` or `[AI] Vertex AI ready`. Verify `.env` has `AI_AUTH_MODE` and credentials. AI is optional — rules work without it.\n\n\u003c/details\u003e\n\n---\n\n## Project Structure\n\n```\nhuminloop/\n├── src/\n│   ├── main.js            # Electron main process\n│   ├── preload.js         # IPC context bridge\n│   ├── db.js / db-pg.js / db-sqlite.js\n│   ├── ai.js              # Gemini AI (native JWT, zero SDK deps)\n│   ├── rules.js           # 7-strategy categorization engine\n│   ├── api-server.js      # Local HTTP API (port 7277)\n│   ├── window-info.js     # OS-native window capture\n│   └── images.js / workflow-context.js\n├── renderer/              # 5 windows + 2 overlays\n├── mcp-server/            # MCP server (separate package)\n├── docker/init.sql        # PostgreSQL schema\n├── .github/workflows/     # CI/CD (build + release)\n├── assets/                # App icons\n└── package.json\n```\n\n---\n\n## Roadmap\n\nThis started as a quick side project and has been growing fast. Here's where it's headed:\n\n- **AI dev workflow integration** — Smart triggers and hooks that automate the full cycle: capture an issue, generate a prompt, route it to the right AI agent, track the fix, and close the loop. The workflow system (Architect/Builder/Reviewer/Screener roles) already exists in `.ai-workflow/` — the next step is wiring it directly into the capture and prompt pipeline with automated orchestration.\n- **Tested executables** — CI builds exist but haven't been validated across platforms yet. This is next.\n- **Auto-update** — electron-builder supports it, just needs to be wired up.\n- **macOS window capture** — App runs on macOS, but window metadata capture isn't implemented yet.\n\nIf you run into issues or have ideas, [open an issue](https://github.com/wyofalcon/huminloop/issues).\n\n---\n\n## License\n\nMIT License. See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwyofalcon%2Fhuminloop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwyofalcon%2Fhuminloop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwyofalcon%2Fhuminloop/lists"}