105 lines
2.5 KiB
Markdown
105 lines
2.5 KiB
Markdown
|
# 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`
|