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:

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/):

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)

cd ~/yhack/LockInBro
.venv/bin/python3 -m argus \
  --vlm gemini \
  --gemini-key YOUR_KEY \
  --dry-run \
  --task-title "debug run"

Recreating the venv

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