Working on digital devices, people often face distractions that can lead to a decline in productivity. INA is an intelligent assistant designed to address this challenge. It elicits a user’s intention, clarifies it, and then leverages a Large Language Model (LLM) to continuously analyze on-screen activity. When deviations from the stated goal occur, it provides gentle nudges. Unlike simple rule-based blockers, INA is designed to be a collaborative assistant that understands user context, supporting users in aligning their digital behavior with their intentions.
Get going immediately—no developer setup required.
- ⬇️ Download the latest macOS build:
IntentAssistant-v1.0.0.dmg - 🖥️ Platform: macOS 10.15 Catalina or later
- 📘 App Usage Guide: Page
- macOS 10.15 (Catalina) or later
- Python 3.9+ (3.11 recommended)
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txtpython main.pyOn first launch macOS will prompt for Screen Recording, Accessibility, and Notifications permissions.
Grant them in System Settings so INA can observe the screen and trigger nudges.
Helper script (prefers the system Python and warns about conda environments):
./run_app.shINA calls LLM APIs directly using the key you provide.
- Launch INA and open Settings → Models.
- Select OpenAI GPT or Google Gemini.
- Paste your API key and choose a model.
- Click Test API Key to verify connectivity, then Save.
Configuration is stored locally at ~/.intention_app/api_config.json (encrypted on disk).
Assuming 1 inference / 2 seconds (~1,800 per hour) with ~26,500 input tokens and ~40 output tokens each:
| Model | Price per hour (USD) |
|---|---|
| GPT-4o mini | 7.2 |
| GPT-5 | 60.0 |
| GPT-5 mini | 12.0 |
| GPT-4.1 | 96.0 |
| Gemini 2.5 Pro | 60.0 |
| Gemini 2.5 Flash | 14.5 |
| Gemini 2.5 Flash-Lite (recommended) | 4.8 |
| Gemini 2.0 Flash | 4.8 |
| Gemini 2.0 Flash-Lite | 3.6 |
📂 Repository Layout
| Path | Purpose |
|---|---|
src/app.py |
Orchestrates the PyQt dashboard, notifications, capture loop, and LLM scheduling. |
src/ui/ |
Widgets, dialogs, dashboard logic, and the feedback/reflection managers. |
src/config/ |
Constants, prompt builders, and the API configuration manager. |
src/utils/ |
Screen/app detectors, direct LLM clients, login helpers, etc. |
src/logging/ |
Local storage helpers for _llm_results.json, _feedbacks.json, _reflections.json, etc. |
setup.py |
py2app configuration for packaging into a standalone .app. |
build_dmg.sh, create_dmg_background.py |
Utilities for creating a DMG release. |
architecture.md |
Detailed diagrams for capture and feedback flows. |
📦 Building a macOS App Bundle
Create the standalone bundle via py2app:
python setup.py py2appArtifacts appear under dist/INA.app.
To generate a distributable DMG (with custom background):
./build_dmg.sh📊 Data & Logging
- Session logs (
_llm_results.json,_feedbacks.json,_reflections.json) live in~/INA_Data/session_data/<task_session>/. - Console output is tee’d into
~/INA_Data/logs/. - API settings and UI preferences are stored in
~/.intention_app/api_config.json. - Screenshots are never written to disk; they exist in RAM only long enough to be encoded for the LLM API call.
- Downstream data handling respects each provider’s API policy (OpenAI, Google).
🧱 Architecture
High-level flow:
flowchart LR
User["User task & feedback"]
Dashboard["Dashboard (PyQt)"]
Manager["ThreadManager"]
Capture["Screen capture<br/>& context"]
LLM["LLM API"]
Storage["Local storage"]
Notify["Notifications"]
User --> Dashboard
Dashboard --> Manager
Manager --> Capture
Capture --> Manager
Manager --> LLM
LLM --> Manager
Manager --> Dashboard
Manager --> Storage
Manager --> Notify
For full diagrams (capture pipeline, feedback/reflection) see architecture.md.
- Bug reports and feature suggestions are welcome through GitHub Issues.
- Before opening a Pull Request, please start a discussion describing the change.
This project is released under the MIT License.
