As a developer who also has ADHD, I know the pain points of this brain type: it's not that we don't want to do things, but we struggle with prioritizing, getting started, and getting lost when switching tasks.
To solve this, I built the ADHD Timebox Agent based on the ConnectOnion framework. This isn't just a normal To-Do List; it is a full-process execution coach based on the "Timeboxing" methodology. It doesn't just record tasks—it acts as an AI agent that takes over my "prefrontal cortex" functions: planning, supervising execution, and providing dopamine feedback.
Ensure your system has Python 3.10 or higher installed.
# Clone the repository
git clone <repository_url>
cd ADHD-Timebox
# Create a virtual environment
python3 -m venv venv
# Activate the virtual environment
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate
pip install -r requirements.txt
To let the Agent manage your calendar, you need to configure the Google Calendar API:
- Go to the Google Cloud Console and create a project.
- Enable the Google Calendar API.
- Create OAuth 2.0 Client IDs (Desktop app).
- Download the JSON credential file, rename it to
credentials.json, and place it in the project root directory. - On the first run, a browser window will pop up for authorization, creating a
token.jsonfile automatically.
This project uses the connectonion framework to connect to LLMs. You need to configure the API Key (e.g., Gemini, OpenAI).
Set environment variables or create a .env file:
export GEMINI_API_KEY="your_api_key_here"
# OR
export OPENAI_API_KEY="your_api_key_here"
(The specific model is configured as co/gemini-3-pro-preview in backend/main.py. Ensure you have access or change it to another model in the code).
This app uses Clerk for Google/Apple sign-in. You only need Clerk keys in .env:
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="your_publishable_key"
CLERK_SECRET_KEY="your_secret_key"Enable Google/Apple in the Clerk dashboard. No provider client IDs are required in this repo.
This mode includes the full "Plan-Monitor-Reward" loop.
python backend/main_mas.py
Features:
- Orchestrator: The central router. It identifies if you need to plan, start focusing, or if you have a sudden distracting thought.
- Focus Agent: Your companion during deep work. It detects if you are getting distracted.
- Idle Watcher: (Requires permissions) Monitors computer idle status to remind you to return to the task.
- Parking Lot: A "Save for later" feature. It stores distracting thoughts so they don't break your current flow.
backend/adhd_brain/: The Agent's "Brain". Stores memories, logs, and generated plan files.backend/agents/: Code for each specific agent (Focus, Planner, Reward, etc.).backend/tools/: Utility tools (Calendar tools, idle detection, etc.).backend/main_mas.py: Entry point for the Multi-Agent mode.
Q: ModuleNotFoundError: No module named 'connectonion'?
A: Make sure you activated your virtual environment and ran pip install -r requirements.txt.
Q: Calendar isn't syncing?
A: Check if credentials.json exists. On the first run, you must manually authorize it in the browser.
Q: How do I change the AI model?
A: Open backend/main_mas.py (or the specific agent file), find model="co/gemini-3-pro-preview", and change it to a model name supported by connectonion (e.g., gpt-4o, claude-3-5-sonnet).
ADHD Timebox Agent is an AI assistant designed to help people with ADHD effectively use the Timeboxing method. It addresses common ADHD problems like "difficulty prioritizing," "trouble starting," "time blindness," and "interrupted execution." It lowers cognitive load to help users enter and stay in a "Flow State."
Timeboxing is a method where you lock a single task into a specific time slot. It’s not just a list; it binds a task to a specific time. Crucially, you must produce a result within that time. It’s like locking a task in a box: you define the start and end time, and you only do that one thing inside the box.
(Elon Musk reportedly uses timeboxing to achieve 8x the workload of an average person).
Step 1: Box it (Planning Phase)
- List it: List all tasks before the day starts.
- Pick the best: Select only the top 3-5 most important tasks. Don't try to do everything.
- Set time: Put them on the calendar with clear start/end times (e.g., 15, 30, or 60 minutes).
Step 2: Close the Box (Execution Phase)
- Start on time: Even if you don't want to, start at the scheduled minute. Even a micro-action (like opening a document) counts.
- Single Core: Remove phones/distractions. Focus on one thing. Do not question the plan; just execute.
Step 3: Open the Box (Review Phase)
- Stop on time: When time is up, stop. Don't chase perfection; aim for "acceptable."
- Celebrate: Cross it off the list or eat a snack. Give your brain positive feedback.
- Use Verbs: "Write Report" (not just "Report").
- Imperfect is fine: The goal is "Done," not "Perfect."
- Trust the Box: Don't waste energy wondering "Is this the right thing to do?" Just do it.
- Box your Rest: Rest is for recovery. Schedule 5-10 minute "Rest Boxes."
- Break it down:
- Huge task -> Break into steps (e.g., "Annual Report" becomes "Gather Data," "Analyze," "Write Summary").
- Tiny tasks -> Group them together (e.g., "Reply to emails" + "File sorting" = one box).
- Fights Parkinson's Law: Work expands to fill the time available. Limits force efficiency.
- Saves Brain Power: You plan once, so you don't have to make decisions all day.
- Control: You aren't pushed by events; you control your time.
Every design decision in the ADHD Timebox Agent is based on the science of Timeboxing. For an ADHD brain, simply "making a list" often fails. The system uses a Multi-Agent Collaboration Architecture:
Role: The system's brain and router.
- Intent Recognition: Listens to what you say and sends you to the right Agent (Plan, Focus, or Reward).
- Agent Lock: When a specific Agent (like the Planner) is doing a complex job, the Orchestrator "locks" the conversation to that Agent so the context doesn't get lost.
Role: Your external "Prefrontal Cortex."
-
List to Timebox: You just dump your messy thoughts ("Write code, learn English, buy groceries"). The Agent organizes them into 15/30/60 minute boxes.
-
Task Shaping:
-
Turns nouns into Verbs.
-
Breaks big tasks down and merges small tasks.
-
Syncs directly to Google Calendar.
-
Dynamic Rescheduling: If you say "Push everything back 30 minutes," it automatically adjusts your whole schedule so you don't feel like you failed.
Role: Protects your Flow State.
- Micro-steps: If you are procrastinating, it suggests tiny steps (e.g., "Just open the file") to bypass anxiety.
- Thought Parking Lot: If you suddenly think "I need to check if my camera fits in my bag," the Agent searches for you or saves the note without you leaving your work window.
- Distraction Detection: Monitors your mouse/keyboard. If you are idle for 5 minutes, it gently reminds you to come back.
Role: Provides Dopamine.
- Instant Feedback: Celebrates when you finish a task.
- Visuals: Generates fun ASCII art (like cows or animals) to give you a sense of achievement.
Challenge: Originally, one giant prompt tried to do everything. It was expensive and fragile. Solution: Split into Orchestrator, Plan, Focus, and Reward. Each agent is small, specialized, and easier to manage.
Challenge: Switching to a separate "Note-taking Agent" just to write down a thought was too slow and broke the user's focus. Solution: I turned features into Tools. Now, the Focus Agent can use a "Parking Lot Tool" to save a note without leaving the conversation.
Challenge: In long conversations, the main Orchestrator would forget who you were talking to (e.g., thinking "9:00 PM" was a new command rather than an answer to the Planner). Solution: Implemented a Sticky Session / Lock Mechanism. If the Planner asks a question, the Orchestrator forces the next reply to go back to the Planner, ignoring other logic until the task is done.
Challenge: When the program restarted, the Agent forgot the plan it just made. Solution: State Injection. Before every message, the code reads the current schedule from the disk and "injects" it into the Agent's prompt. The Agent always knows the real-time status of your day.
Challenge: The system could remember tasks, but not user preferences (e.g., "I get tired at 2 PM"). Solution: Added ConnectOnion Memory. Now, the Plan Agent can leave a "sticky note" for the Focus Agent saying: "User is stressed today, be gentle." The system learns your habits over time.
The ADHD Timebox Agent uses the power of ConnectOnion's Memory and Multi-Agent orchestration to turn a mechanical schedule into a smart, empathetic partner. It has memory, intuition, and helps my brain function better.
作为一个开发者，同时也是 ADHD 人群的一员，我深知这种大脑的痛点：并非不想做，而是优先级混乱、启动困难以及极易在任务切换中迷失。 为了解决这个问题，我基于 ConnectOnion 框架开发了 ADHD Timebox Agent。这不是一个普通的 To-do List，而是一个基于“时间盒”方法论的全流程执行教练。它不仅仅是记录任务，更是通过 AI 代理接管了我的“前额叶皮层”功能——负责规划、监督执行，并提供多巴胺反馈。
确保你的系统已安装 Python 3.10 或更高版本。
# 克隆仓库 (如果你是从 GitHub 下载)
git clone <repository_url>
cd ADHD-Timebox
# 创建虚拟环境
python3 -m venv venv
# 激活虚拟环境
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activatepip install -r requirements.txt为了让 Agent 管理你的日历，你需要配置 Google Calendar API：
- 前往 Google Cloud Console 创建一个项目。
- 启用 Google Calendar API。
- 创建 OAuth 2.0 Client IDs (Desktop app)。
- 下载 JSON 凭证文件，重命名为
credentials.json并放置在项目根目录（或ConnectOnion/目录下，取决于库的配置，建议放在根目录）。 - 首次运行时，系统会弹出浏览器窗口进行授权，授权后会生成
token.json。
本项目使用 connectonion 框架连接大模型。你需要配置相应的 API Key（例如 Gemini、OpenAI 等）。
请设置环境变量或创建 .env 文件（如果支持）：
export GEMINI_API_KEY="your_api_key_here"
# 或
export OPENAI_API_KEY="your_api_key_here"(具体使用的模型在 backend/main.py 中配置为 co/gemini-3-pro-preview，请确保你有访问权限或在代码中修改为其他模型)
包含完整的“执行-监测-奖励”闭环。
python backend/main_mas.py功能：
- Orchestrator: 中央路由，识别你是要规划、还是要开始专注、或者是突然有了杂念。
- Focus Agent: 专注时的伴侣，检测走神。
- Idle Watcher: (需要额外权限) 监测电脑空闲状态，提醒你回到任务。
- Parking Lot: "记一下..." 功能，把干扰想法暂存，不打断当前心流。
backend/adhd_brain/: Agent 的“大脑”，存储记忆、日志和生成的计划文件。backend/agents/: 各个智能体的实现代码 (Focus, Planner, Reward 等)。backend/tools/: 实用工具集 (日历工具、空闲检测等)。backend/main_mas.py: 多智能体模式入口。
Q: 启动时报错 ModuleNotFoundError: No module named 'connectonion'?
A: 请确保你已激活虚拟环境并运行了 pip install -r requirements.txt。
Q: 日历无法同步？
A: 请检查 credentials.json 是否存在且有效。首次运行需要手动在浏览器中点击授权。
Q: 如何修改使用的 AI 模型？
A: 打开 backend/main.py (单体) 或 backend/agents/orchestrator.py (MAS)，找到 model="co/gemini-3-pro-preview" 并修改为你支持的模型名称 (如 gpt-4o, claude-3-5-sonnet 等，需 connectonion 支持)。
ADHD Timebox Agent 是一个帮助 ADHD人群 有效的使用时间盒设计的AI辅助系统。它不仅仅是一个待办清单，更是一个基于“时间盒” 方法论的全流程执行教练。
ADHD Timebox Agent 通过Plan、Focus、Rewards 多个agent 配合多个tools ，解决 ADHD 人群常见的“优先级难划分”、“启动困难”、“时间盲区”和“执行中断”问题，通过降低认知负荷，帮助用户进入并保持心流状态。
时间盒是一种将任务「锁」进特定时间段的单任务管理方法。 它不是普通的 To-do List，而是把任务与具体时间点绑定。 而且要求在规定时间内必须产出成果。就像把任务关进一个个「盒子」里， 规定好开始和结束时间， 最重要的是在这个盒子里只做这一件事。
马斯克用时间盒管理法 一年完成的工作量，几乎是别人的八倍。
执行分为 计划阶段 、执行阶段和验收阶段 。
- 列清单
在每天开始前，列出所有待办事项。 - 挑重点
只挑出 最重要的 3–5 项任务，而不是试图做完所有事。 - 定时间
把任务填入日程表，设定明确的起止时间。
常见规格：15 分钟 / 30 分钟 / 60 分钟。
- 准时开启
即使不想做，也要准时开始，
哪怕只是一个微小的启动动作（例如：打开文档）。 - 单核工作
移除手机等干扰，一次只专注一件事。
不质疑计划，不中途切换任务。
-
准时结束
时间一到就停止，
不追求完美，只要达到「可接受标准」。 -
简单庆祝
划掉清单或奖励自己（比如吃点零食），
给大脑一个正向反馈。
为了保证时间盒真正有效，需要遵守以下规则：
-
动词导向
任务要用动词描述（如「撰写报告」而不是「报告」）。 -
不求完美
目标是在有限时间内「完成」，
而不是无限期拖延追求完美。 -
信任盒子
一旦设定时间盒，执行时不要再纠结
「现在做这个对不对」，直接执行。 -
休息也要装盒
休息不是偷懒，而是恢复精力。
在任务之间安排 5–10 分钟的休息盒。 -
大拆小，小合并
- 大任务 → 拆解成小步骤 比如“完成年度报告”这个任务就太大了，你需要把它分解成：收 集Q1-Q4的业务数据、分析增长趋势、写市场分析部分、制作数据 图表、撰写总结和建议，等等。
- 碎事（回微信、整理文件）→ 合并到一个时间盒集中处理
-
对抗帕金森定律
工作会自动膨胀占满所有时间。
时间限制倒逼你提高效率，剔除细枝末节。 -
符合帕累托原则（二八法则）
强迫你把精力集中在最重要的 20% 任务上。 -
节省脑力
提前规划，执行时不再消耗脑力做选择，
避免决策疲劳。 -
获得掌控感与自由
你不再被事情推着走，
而是获得专注于真正重要事情的自由。 -
提升专注力
明确的截止时间能激活大脑前额叶皮层，
增强自我控制力。
ADHD Timebox Agent的所有核心设计决策，都是建立在 时间盒（Timeboxing）管理法的科学原理上。
对于 ADHD 大脑，单纯要求“罗列任务”往往是无效的。因为 ADHD 的核心挑战正是难以确立任务的优先级，面对需要组织与整理的庞杂事务更是一场认知的灾难。
ADHD Timebox Agent采用了 Multi-Agent 协作架构，由一个中心调度Agent 和三个功能性 Agent 组成。系统通过状态锁机制 管理上下文，确保复杂的多轮对话任务能够完整执行。
角色： 系统的大脑与路由中心。
-
意图识别与分发： 实时监听用户自然语言输入，分析意图并将任务路由至最合适的 Agent（Plan, Focus 或 Reward）。
-
Agent Lock (会话锁定机制)： 当某个 Agent 进入复杂任务流， 如规划任务 时，Orchestrator 会锁定控制权，直到该 Agent 明确发出
Task Completed信号，才会重新接管调度。这确保了任务上下文的连续性，防止逻辑跳跃。
角色： 外置的“前额叶皮层”，负责任务的整理、整形与时间管理。
-
清单转时间盒 (List to Timebox)： 用户只需倾倒碎片化的想法，比如：“今天要写agent代码 学英语 买菜 回邮件 ”，无需提前整理、排序或决策。Plan Agent 会自动分析认知负荷，将其整理并塞入 15/30/60 分钟 的时间盒中，将“混乱”转化为可执行的秩序。
-
任务整形 (Task Shaping)：
- 自动动词化： 将模糊的名词（如“周报”）转化为清晰的动作（如“撰写周报”）。
- 拆解与合并： 自动将大任务拆解为30分钟内的子任务，或将碎片杂事合并，确保难度适中。
-
会自动把这些日程 同步到 google calendar 里
-
弹性日程 (Dynamic Rescheduling)： 支持“推迟 30 分钟”等自然语言指令，自动顺延后续计划，防止因一次超时导致整体计划崩塌的挫败感。
角色： 心流守护者，负责对抗拖延与维持注意力。
-
微步启动 (Micro-steps)： 检测到用户犹豫或拖延时，不进行施压，而是给出极低门槛的建议（如“先打开文档就好”），绕过杏仁核的焦虑反应。
-
念头停车场 ： 当用户在执行中产生杂念 如“突然想查新买的一次性胶片机能不能过安检 ”，Agent 会代替用户在后台搜索并存储摘要，让用户无需切换窗口，保护心流的连续性。
还会保存到 thought_parking 文件中
-
走神检测 (Distraction Detection)： 实时监测输入设备状态。如果用户超过 5 分钟无鼠标/键盘操作，系统会主动发出温和提醒，拉回注意力。
-
状态追踪： 负责标记当前正在进行的任务及上下文管理。
角色： 多巴胺提供者。
-
即时正反馈： 当任务被标记为“完成”时，触发即时奖励。
-
可视化激励： 生成趣味性的 ASCII Art（如 Cowsay 动物形象）与鼓励语，为枯燥的任务结尾提供成就感与情绪价值。
- 挑战： 早期尝试使用单一 Agent 处理所有逻辑包括 规划、监督、奖励，导致 Prompt 过于臃肿。不仅 Token 消耗巨大，且系统极其脆弱——修改一个指令往往会导致其他无关功能的退化，调试难度呈指数级上升。
- 收获： 采用 Orchestrator-Worker 的多智能体协作模式，通过拆分为
Plan、Focus、Reward三个独立 Agent，实现了模块化开发。现在每个 Agent 仅维护最小必要上下文，既降低了认知负荷，也使得针对性优化 变得安全且高效。
在系统的早期设计中，我曾陷入“万物皆 Agent”的误区，例如设计了一个独立的 Parking Agent 专门负责记录用户的杂念。但在实际运行中，我发现了严重的问题，并最终通过 Tool Use 完成了架构重构。
ConnectOnion 的设计哲学——"Functions are Tools" 极大地简化了开发。我不需要写复杂的封装类，只需要写标准的 Python 函数，就能直接变成 Agent 可调用的工具。这不仅让我能快速迭代 Google Calendar、System Lock 等功能，而且还解决了这个痛苦的问题
当用户在专注时说“我想查个资料”，Orchestrator 需要将对话从 Focus Agent 切换到 Parking Agent。这种设计导致了不必要的上下文切换。
路由抖动： 纯 Prompt 的路由切换往往不稳定，Orchestrator 容易在频繁的切换中丢失原始任务的上下文。
体验割裂 仅仅为了“记个笔记”就切换整个 Agent 人格，不仅消耗 Token，还破坏了用户的心流体验。
- 重构时 我将“念头停车场”降级为 作为
Focus Agent的一个 Tool。 用户无需离开当前的专注模式，Agent 只需调用工具即可完成“卸载杂念”，保持了对话的连续性和稳定性。
在开发早期，Orchestrator agent采用的是朴素的无状态路由 模式。这导致了一个严重的上下文漂移问题： 就是当Plan Agent 发起追问 例如：“你想定在几点？”，回复 “九点” 时，Orchestrator 往往因为丢失了上一轮的上下文，无法理解“九点”的含义，甚至错误地将其路由给其他 Agent，导致对话流程断裂，Agent 表现得“呆滞”。
为了解决这个问题，我放弃了依赖 LLM 自身记忆的做法，转而采用了 “外部状态管理 + 确定性路由” 的方案。
-
LLM 的意图识别是概率性的。当
Plan Agent需要与用户进行多轮交互 比如确认任务细节时，Orchestrator 经常误以为任务已结束，从而过早接管对话，导致逻辑断裂。 -
因此引入了类似 有限状态机的锁定机制。
-
当 Agent 调用
acquire_lock()工具时，系统进入 Sticky Session 模式。 -
Orchestrator 会暂时旁路意图识别逻辑，将后续所有的 User Input 强制路由给当前持有锁的 Agent，直到其显式调用
release_lock()。这确保了Workflow 的原子性和完整性。
-
Plan Agent 缺乏“状态持久化感知”。尽管代码已经将用户的计划保存为 daily_tasks.json 文件，但每当程序重启或开始新会话时，Agent 表现得像第一次启动一样，完全不知道已有计划的存在。
根本原因 (Root Cause)：
-
LLM 的无状态性 (Statelessness)： LLM 本身不具备长时记忆，只依赖当前的
Context Window（上下文窗口）。 -
上下文断层： 虽然数据在磁盘上（持久化层），但在 Agent 初始化时，没有将这些数据加载回内存（应用层）并注入到 Prompt 中。Agent 和磁盘文件之间隔了一堵墙。
为了解决这个问题，我引入了一个架构层的中间件——State Manager，将“记忆的维护”从 Agent 的推理逻辑中剥离出来，交给确定性的代码处理。
状态注水 不再依赖 Agent 主动去“查”文件，而是采用主动注入策略：
我将 LLM 视为无状态 (Stateless) 的推理引擎。在每一轮对话发起前，代码层会先从后端读取最新的 System State（如当前时间、任务列表、剩余时间），将其组装成 Prompt 动态注入 到当次请求中。
这样无论对话进行了多久，Agent 在每一轮都能看到“最新鲜、最客观”的世界状态，彻底根除了因记忆衰减导致的逻辑漂移。
在引入 ConnectOnion 的 Memory 模块之前， ADHD Timebox Agent 通过 daily_tasks.json 和 上下文注 实现了状态持久化。它精确地记得“现在是 14:00，你在做任务 B，进度 50%”。哪怕重启，它读取 JSON 也能立刻恢复状态。
也能知道现在的任务是什么。但它的局限在于：它只能记住“设计好”的字段，比如 : start_time、end_time、status、title。但如果用户说了一句：“我发现我下午 2 点特别容易困，以后这个时间别排重活”。旧系统会因找不到 user_energy_pattern 这种字段，只能把这句话当做闲聊处理，或者存进 thought_parking 仅仅是个备忘录 别的agent 不会读 ，而在下次 Plan agent 排期时，依然会在下午 2 点排重活。
加入 Memory 后，拥有了“非结构化认知” 像一个贴身管家。它不仅看表格，还会拿个小本本记下用户的“脾气”和“习惯”。
-
旧系统：Plan Agent把任务扔给 Focus 就不管了。
-
新系统：Plan Agent 可以在 Memory 里留个便条——focus_note: "这个用户最近压力大，执行阶段多鼓励，少催促"。Focus Agent 虽然没参与排期，但看到这个便条，对你的语气就会变温柔。它让系统能从过去的互动中学习，产生那些 JSON 字段里装不下的“默契”和“直觉”。
ADHD Timebox Agent 利用 ConnectOnion 强大的 Memory 能力和灵活的 Multi-Agent 编排，成功将一个“只会看日程表的机械程序”，升级成了一个“有记忆、懂默契、能进化”的聪明Agent。 感谢 ConnectOnion，让复杂的事情变得简单，让 AI 成为了我大脑的延伸。