Starting my blogging journey with this year’s Hacktoberfest. #HF26 I’ll be sharing what I learn, build, break, and figure out along the way. A lot more coming soon — follow along and learn with me!

yashraj jangir — Mon, 05 Oct 2026 07:46:06 +0000

Hacktoberfest Weekend Challenge: Build for a Friend Submission 🤝

yashraj jangir

Oct 5

Focus Agent: A Local AI Focus Companion Built for a Friend

#hf26challenge #gemma #linux #productivity

5 min read

Focus Agent: A Local AI Focus Companion Built for a Friend

yashraj jangir — Mon, 05 Oct 2026 06:51:21 +0000

Focus Agent: A Local AI Focus Companion Built for a Friend

This is my submission for the Hacktoberfest Weekend Challenge: Build for a Friend, including the Best Use of Gemma category.

Project: Focus Agent on GitHub

Demo: Watch the captioned walkthrough

The idea: help Raj return to his own priorities

Raj is a friend who is talented and ambitious, but can get pulled into interesting side quests and lose track of the task he meant to finish. A to-do list can remember the plan. A screen-time chart can count applications. Neither can connect the two in a way that gives him a useful, timely nudge.

So I built Focus Agent: a desktop companion that lets Raj state his priorities, observes which application is active, and checks whether that activity seems connected to the current task. If the relationship is unclear, a local Gemma model helps interpret a small, allowlisted context. If distraction remains likely and Raj ignores the check-in, the intervention becomes more visible. Raj can correct the classification, switch tasks, take a break, or pause monitoring.

The agent is meant to help someone act on their own intentions, not to judge their productivity. It explains its reasoning and leaves the decision with Raj.

What works today

Turn a natural-language plan into a short list of tasks and set the current priority.
Track application changes through a small KDE KWin script and local D-Bus bridge.
Save activity sessions, tasks, corrections, breaks, and intervention responses in local SQLite.
Use Gemma through Ollama for ambiguous activity, with strict JSON validation and deterministic policy checks.
Remember Raj's “still related” corrections for a task and application.
Escalate ignored drift prompts from a quiet notification to a full-window intervention.
Pause monitoring for 15 or 30 minutes, 1, 2, or 4 hours, or until Raj resumes it.
Keep planning usable with a deterministic fallback if Ollama or Gemma is unavailable.

Gemma matters to the core loop: application names alone do not tell us whether a window is useful for the task. Running the model locally means activity context does not need to go to a hosted inference service. The project is open source, so the collection and decision flow can be inspected.

Development environment

This prototype currently targets Linux with KDE Plasma 6 on Wayland. To run it, you need:

Node.js 22 or newer and npm;
KDE's KWin script and D-Bus support;
Ollama with a Gemma-family model (the README uses gemma3:1b as a small starting point).

After installing dependencies, the repo documents npm test and npm run dev, plus commands to install the KWin activity bridge. The model download is needed for local reasoning; once the model and dependencies are installed, inference does not need a hosted AI API.

This is a Linux prototype, not a cross-platform release. The activity bridge is KDE-specific, and I have not yet validated it on X11, Windows, or macOS.

What I saw while testing

In one short real desktop session, Firefox, VS Code, and ChatGPT were classified as related to the active task. I then used Chrome for about ten minutes; Focus Agent left it as unknown. That conservative result is useful: an unfamiliar browser should not automatically be called a distraction just because it is a browser. It also showed me a current limitation: without browser-domain or page context, application-level signals can be too coarse to tell what someone is doing.

I also exercised the reasoning path with gemma3:1b: an obvious game launcher produced a high-confidence distraction result, while an unknown browser stayed low-confidence/unknown. These are prototype checks, not a broad accuracy study. More testing with Raj and other users is still needed.

The demo includes representative preview data for the full intervention sequence. Waiting through real cooldowns made it impractical to capture every escalation level in a short walkthrough, so I used preview data for that part rather than implying the video is a continuous live session.

Setbacks that changed the design

One UI bug taught me that activity tracking and interface actions can interfere with each other. When I clicked Still related, Focus Agent itself became the active window before the correction landed, so the action could apply to the wrong activity. I changed the flow to preserve the intended activity target and filter Focus Agent's own window from collected activity.

Another challenge was deciding what an application name can really prove. My Chrome observation remained unknown, and that is preferable to inventing certainty. The bridge currently sees application-level context, not browser URLs, page contents, or documents. I kept that boundary explicit and made corrections available to the user.

I also started after missing the first few days of the challenge, so the scope had to stay focused: a working Linux prototype, a clear demo, and a privacy model I could explain rather than a premature promise of support for every desktop.

What comes next

I want to finish this as a dependable cross-platform project. The next work is to add activity adapters for other Linux desktop environments and X11, then build and test native activity integrations for Windows and macOS. I also want to test with Raj, improve the app-level ambiguity handling without collecting more personal data than necessary, and make packaging and first-run setup easier.

If you work on desktop integrations, local AI, privacy-respecting productivity tools, or testing across Linux setups, contributions and issue reports are welcome. Please open an issue or pull request on the GitHub repository; small, well-scoped contributions are especially helpful.

KDE Wayland release candidate

The Focus Agent v0.1.0-rc.1 GitHub release is available for KDE Plasma 6 on Wayland, x86_64. The AppImage bundles Electron and its Node.js runtime, so you do not need to install Node.js separately. Ollama with Gemma is still needed for local reasoning, and the KWin activity bridge is available as a separate download on the release page. The README includes setup steps. This is an unsigned release candidate built on Kali Linux Rolling; it has not been validated on other distributions.

DEV Community: yashraj jangir

Starting my blogging journey with this year’s Hacktoberfest. #HF26 I’ll be sharing what I learn, build, break, and figure out along the way. A lot more coming soon — follow along and learn with me!

Focus Agent: A Local AI Focus Companion Built for a Friend

Focus Agent: A Local AI Focus Companion Built for a Friend

Focus Agent: A Local AI Focus Companion Built for a Friend

The idea: help Raj return to his own priorities

What works today

Development environment

What I saw while testing

Setbacks that changed the design

What comes next

KDE Wayland release candidate

Related reading from DEV