ADHD-OS

The Problem

Productivity apps assume you have the executive function to use them. For people with ADHD, the problem isn't knowing what to do. It's starting, staying on track, and not losing an entire afternoon to a rabbit hole. To-do lists don't help when the real barrier is emotional, temporal, or cognitive overload.

I built ADHD-OS because I needed it. Traditional task managers don't account for energy levels, medication windows, or the fact that "clean the garage" isn't one task, it's thirty. I wanted a system that understood those realities and could meet me where I actually am.

The Insight

Executive dysfunction isn't one problem. Getting stuck, getting overwhelmed, spiraling, and losing track of time each call for different interventions. One general agent can fake its way through that, but it usually gives shallow advice. A set of specialist agents can be much more specific, with an orchestrator deciding which one to bring in.

The Solution

ADHD-OS is a CLI-based multi-agent system where you talk to it like a co-worker and it routes your input to the right specialist. If you're stuck on a report, it helps you start. If a task is too big, it breaks it down. If your brain is spiraling, it switches into a different kind of support. The point is not generic advice. It's the right intervention for the kind of friction you're actually dealing with.

All data stays local in a SQLite database. No cloud sync, no accounts, no friction between you and getting unstuck.

How It Works

1. Step 01

   Describe what's happening

   The system starts with natural language, not a rigid form, because the hardest part is often saying what's wrong in the first place.

2. Step 02

   Route to the right specialist

   The orchestrator decides whether the issue is about activation, time, emotion, or reflection.

3. Step 03

   Get one clear intervention

   Instead of general advice, the selected agent gives a response shaped for that exact type of block.

4. Step 04

   Keep momentum locally

   Timers, check-ins, and state recovery help carry the session forward without adding account or sync friction.

Architecture

How the Agent System Splits the Work

Build Process

ADHD-OS started as my capstone project for the Google and Kaggle AI Agents Intensive course in December 2024. The initial version was a proof of concept: a few agents, basic routing, minimal state. It demonstrated the multi-agent architecture pattern using Google ADK and earned completion of the program.

I've iterated on it several times since then. The v2.1 release added the full 13-agent roster, a dynamic time multiplier that adjusts based on real-time state, deterministic state machines for body doubling and focus timing, semantic task caching, structured logging, session persistence with context recovery, a crisis safety layer, and an optional React + FastAPI dashboard for visualizing energy levels and task history.

Key Design Decisions

• Specialist agents over a single generalist: Each executive dysfunction needs a different intervention strategy. A decomposition agent thinks in checklists. An emotional regulation agent thinks in reframes. Routing to specialists produces better results than one agent trying to do everything.
• Dynamic multiplier over static estimates: Time estimates adjust in real time based on energy level (1–10), medication peak window, time of day, and historical accuracy. A task estimated at 20 minutes might get calibrated to 34 minutes if energy is low and it's past the afternoon slump.
• Deterministic accountability: Body double check-ins and focus timer warnings run as state machines, not LLM calls. Accountability has to be reliable. If the API is slow or down, the check-in still fires.
• Crisis safety as a hard-coded layer: Keyword detection for crisis language bypasses all LLM processing and immediately surfaces 988 Suicide & Crisis Lifeline resources. No AI interpretation, no latency, no risk of a model responding inappropriately.
• Local-first data: Everything stays in a local SQLite file. No accounts, no cloud sync. The barrier to using the tool should be as close to zero as possible because friction is the enemy when executive function is already compromised.
• Microscopic steps: Task decomposition targets steps of 10 minutes or less with clear completion states. For ADHD, a task that feels "too big" simply won't get started. Making every step small enough to feel doable is the core design principle.

Application Features

• Task initiation: Identifies the real barrier (fear, boredom, overwhelm) and generates a first step small enough to take in under 5 minutes.
• Task decomposition: Breaks complex tasks into microscopic, checkpointed steps with rabbit-hole warnings and time calibration built in.
• Body doubling: A deterministic accountability machine that runs timed check-ins with desktop notifications. No LLM needed.
• Time calibration: A dynamic multiplier that corrects time blindness using energy level, medication window, time of day, and task history.
• Emotional regulation: Anxiety reality-testing, rejection sensitivity reframing, and dopamine-based motivation strategies (speedruns, streaks, rewards).
• Pattern analysis: Finds correlations in task history, like discovering that admin tasks consistently get avoided on low-energy afternoons.
• Context recovery: Resumes your last session within a 12-hour window, including what you were working on and your state at the time.
• Morning activation: A structured startup routine that asks energy level, medication time, and priorities, then builds a day structure around your peak focus window.

Tech Stack

What It Demonstrates

• Multi-agent orchestration: The system routes different kinds of ADHD friction to specialists instead of treating everything like the same prompt problem.
• Hybrid design: LLMs handle reasoning, while timers and accountability flows stay deterministic.
• Problem-shaped architecture: The system is organized around lived ADHD patterns, not around whatever agent pattern happened to be trendy.
• Personal product loop: This is a tool I built for myself and kept iterating because the problem was real.