include argus workflow

2026-03-29 06:29:18 -04:00
parent 275a53ab40
commit 56673078f5
23 changed files with 3098 additions and 307 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,104 @@
+# LockInBro
+
+ADHD-friendly macOS focus assistant. Monitors your screen with a local VLM agent (Argus), detects friction and distractions, and nudges you back on track.
+
+## Requirements
+
+- macOS 14+
+- Xcode 16+
+- Python 3.11+ (system or Homebrew)
+
+## Setup
+
+### 1. Python environment
+
+Create the venv once from the project root:
+
+```bash
+cd ~/yhack/LockInBro
+python3 -m venv .venv
+.venv/bin/pip install -r argus/requirements.txt
+```
+
+### 2. API keys
+
+Create a `.env` file in the project root (next to `argus/`):
+
+```bash
+cp argus/.env.example .env   # if example exists, otherwise create manually
+```
+
+`.env` contents:
+
+```
+GEMINI_API_KEY=your_gemini_api_key_here
+BACKEND_BASE_URL=https://wahwa.com/api/v1
+```
+
+The Gemini API key is also set at runtime from the app's Settings screen — the `.env` is only needed if running Argus directly from the command line.
+
+### 3. Xcode permissions
+
+In Xcode → Signing & Capabilities, ensure the app has:
+- **Screen Recording** — required for screenshot capture
+- **App Sandbox** disabled (or `com.apple.security.screen-recording` entitlement added)
+
+### 4. Run
+
+Open `LockInBro.xcodeproj` in Xcode and press **Run** (⌘R).
+
+On first launch:
+- Grant **Screen Recording** permission when prompted
+- Log in or register via the app
+- Enter your Gemini API key in Settings
+
+---
+
+## Argus (VLM agent)
+
+The `argus/` directory contains the Python screen-analysis agent. It runs as a subprocess of the Swift app — you do not need to launch it manually.
+
+### Running Argus directly (for debugging)
+
+```bash
+cd ~/yhack/LockInBro
+.venv/bin/python3 -m argus \
+  --vlm gemini \
+  --gemini-key YOUR_KEY \
+  --dry-run \
+  --task-title "debug run"
+```
+
+### Recreating the venv
+
+```bash
+rm -rf .venv
+python3 -m venv .venv
+.venv/bin/pip install -r argus/requirements.txt
+```
+
+---
+
+## Project structure
+
+```
+LockInBro/
+├── .venv/                  # Python venv (gitignored)
+├── .env                    # API keys (gitignored)
+├── argus/                  # VLM agent (Python)
+│   ├── requirements.txt
+│   ├── capture.py          # Reads screenshots from /tmp/lockinbro_capture.jpg
+│   ├── loop.py             # Main analysis loop
+│   ├── vlm.py              # Gemini / Ollama client
+│   └── ...
+├── LockInBro/              # Swift app source
+│   ├── SessionManager.swift
+│   ├── APIClient.swift
+│   └── ...
+└── LockInBro.xcodeproj
+```
+
+## Backend
+
+Deployed at `https://wahwa.com/api/v1` (FastAPI on DigitalOcean).
+Source: `~/yhack/lockinbro-api`