Stop Losing Context: claude-adhd-skills Is the Secret Weapon for AI-Powered Developers

Stop Losing Context: claude-adhd-skills Is the Secret Weapon for AI-Powered Developers

You sit down to code. Three hours vanish. You have seventeen open tabs, a terminal full of half-finished experiments, and absolutely no memory of why you started this particular rabbit hole. Your AI agent? Equally lost. When you fire up a fresh Claude Code session tomorrow, you'll spend twenty minutes reconstructing context that should have been automatic. The promise of AI-assisted development keeps breaking against the same rock: statelessness. Every session starts from zero. Every insight evaporates. Every "I'll wrap this up in thirty minutes" becomes a four-hour marathon.

Here's the uncomfortable truth: most developers using AI agents are flying without instruments. No time awareness. No persistent memory. No guardrails against endless spirals. The result? Burnout, fragmented focus, and code that ships slower despite having a superintelligent pair programmer.

Enter claude-adhd-skills — a ruthlessly practical scaffolding system that transforms Claude Code from a stateless chatbot into an organized, time-aware, memory-persistent development partner. Built by developer Ricardo Avila, this isn't productivity theater. It's a battle-tested system for staying sane while developing with AI agents, and it's about to change how you work.

What Is claude-adhd-skills?

claude-adhd-skills is an open-source collection of Claude Code skills, hooks, and configuration patterns designed to solve the organizational chaos of AI-assisted development. The repository lives at github.com/ravila4/claude-adhd-skills and has been gaining serious traction among developers who've hit the same wall: AI agents are brilliant, but they're amnesiac and time-blind without proper scaffolding.

The project's name includes "ADHD" not as a medical claim, but as shorthand for the universal developer experience: scattered attention, hyperfocus traps, time blindness, and the painful gap between intention and execution. Ricardo built this for himself, then open-sourced it when other developers started begging for the same setup.

What makes it trending now? Three converging forces: the explosion of Claude Code adoption, the growing frustration with context loss in AI sessions, and the resurgence of Obsidian as a developer knowledge base. Developers are realizing that raw AI capability isn't the bottleneck — orchestration is. claude-adhd-skills provides that orchestration layer, and it's remarkably lightweight to adopt.

The philosophy is radical in its simplicity: treat your AI agent as a persistent team member, not a disposable consultant. That means shared memory (Obsidian vault), time awareness (hooks that inject datetime), behavioral guardrails (nudge system), and structured workflows (TDD skill). The result? Sessions that compound instead of reset.

Key Features That Separate Pros from Amateurs

Let's dissect what actually ships in this repository and why each piece matters technically.

Conversational Daily Journaling (daily-journal)

Unlike commit-log generators that vomit git history, this skill interviews you about your day. It writes structured reflections to Obsidian, creating a searchable narrative of your development journey. Morning and evening modes adapt the questioning based on time of day — a subtle but crucial UX detail that makes journaling sustainable.

Vault-Aware Note Management (obsidian-vault)

This isn't generic markdown^{↗ Smart Converter} writing. The skill understands your folder hierarchy, naming conventions, frontmatter schema, and internal linking graph. It places notes where they belong, links them to related concepts, and maintains the structural integrity of your knowledge base. The optional obsidian-semantic integration enables meaning-based retrieval — find that note about "that caching thing" without remembering filenames.

Time-Based Nudge System (nudge)

The killer feature for anyone who's promised to "stop at 11 PM" and found themselves coding at 2 AM. Nudges fire on prompt submission, not as background notifications you'd ignore. They're intrusive by design. The syntax is deliberately simple: +30m for relative, 23:00 for absolute. When due, they block your workflow until acknowledged.

Test-Driven Development Skill (test-driven-development)

Based on obra's original Red/Green TDD skill, this implements a Logic Gate + Iron Rule pattern: triage what needs tests, then enforce strict test-first for anything containing logic. It's not just TDD — it's TDD with an AI agent that actually follows rules instead of "forgetting" and writing implementation first.

Persistent Date/Time Injection (date hook)

Every prompt gets current datetime injected automatically. This enables time-aware behavior: morning standup prep, evening wind-down suggestions, accurate journaling timestamps. Without this, Claude Code operates in a temporal void — it literally doesn't know if it's 3 AM or 3 PM.

Alert Lifecycle Management (check_alerts.py, add_alert.py, ack_alert.py)

A complete CRUD system for nudges implemented as Python^{↗ Bright Coding Blog} scripts. Check on submit, add via natural language, acknowledge with dismissal. The Python dependency keeps it lightweight and hackable.

Real-World Scenarios Where claude-adhd-skills Dominates

Scenario 1: The Context Archaeologist

You return to a project after a two-week hiatus. Normally, you'd spend 45 minutes re-reading code, checking branches, and reconstructing mental state. With claude-adhd-skills, you point Claude at your Obsidian daily logs: "Read my journal entries from March 10-14 and summarize what I was building." The agent reconstructs context from your own narrative, not just git diffs. You're productive in five minutes, not forty-five.

Scenario 2: The Hyperfocus Escape Artist

It's 10:47 PM. You have a 7 AM meeting. You tell Claude: "Nudge me to stop at 11." At 11:00 PM, you submit another prompt — and the nudge fires: "STOP: You asked to wrap up at 23:00. Current time: 23:03." You acknowledge and (ideally) sleep. The nudge lives in your terminal, not a dismissible notification center. It's a commitment device, not a suggestion.

Scenario 3: The Research-to-Code Pipeline

You're investigating a new framework. Claude helps you explore, takes notes in your Obsidian vault under Research/, links related concepts, and tags appropriately. A week later, you search: "Find my notes about React^{↗ Bright Coding Blog} Server Components and caching." The semantic search surfaces it. When you start implementation, the obsidian-vault skill places your design doc in Projects/, links to research, and initializes the TDD skill. Knowledge flows without friction.

Scenario 4: The Distributed Team Member

You work across multiple machines — laptop, desktop, cloud VM. Each Claude Code session is isolated, but your Obsidian vault syncs via Git or Obsidian Sync. Your shared memory is portable. Start a session on your desktop, continue on your laptop, and Claude catches up by reading the same journal entries and project notes. The agent becomes machine-agnostic.

Scenario 5: The Accountability Partner

Your CLAUDE.md encodes your working preferences: break every 90 minutes, ask before assuming, track focus explicitly. Claude doesn't guess — it follows your protocol. When you start a session, it knows your role, your platform, your domain. The relationship compounds. Week three feels different from day one because the agent has persistent context about you, not just your current task.

Step-by-Step Installation & Setup Guide

Ready to stop flying blind? Here's the complete installation.

Prerequisites

Ensure you have:

• Claude Code CLI installed and authenticated
• Python 3.10 or higher
• Obsidian installed with a vault created
• SQLite3 (usually pre-installed on macOS/Linux)
• Optional: obsidian-semantic for semantic search

Step 1: Clone and Copy Skills

# Clone the repository
git clone https://github.com/ravila4/claude-adhd-skills.git
cd claude-adhd-skills

# Copy skills to Claude Code's skills directory
cp -r skills/* ~/.claude/skills/

# Copy hooks to the hooks directory
cp hooks/* ~/.claude/hooks/

These commands install four skills (daily-journal, obsidian-vault, nudge, test-driven-development) and three Python scripts for alert management.

Step 2: Configure Hooks in Settings

Edit ~/.claude/settings.json (global) or ~/.claude/settings.local.json (project-specific). The repository includes settings.json.example as reference. Here's the critical configuration:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "type": "command",
        "command": "echo \"Today is $(date '+%A, %B %d, %Y'). Time: $(date '+%H:%M')\"",
        "timeout": 5000
      },
      {
        "type": "command",
        "command": "python3 ~/.claude/hooks/check_alerts.py",
        "timeout": 5000
      }
    ]
  }
}

The first hook injects temporal awareness — Claude sees "Today is Thursday, March 20, 2025. Time: 14:32" before every response. The second checks for due nudges, surfacing them at the exact moment you're about to continue working.

Step 3: Personalize Your CLAUDE.md

# Copy the template to your Claude config directory
cp CLAUDE.md ~/.claude/CLAUDE.md

Edit and replace these placeholders:

• {YOUR_NAME}: Your preferred name
• {YOUR_ROLE}: Job title (e.g., "Staff Engineer")
• {WHAT_YOU_DO}: Brief work description (e.g., "Distributed systems and developer tooling")
• {YOUR_PLATFORM}: Machine details (e.g., "MacBook Pro, macOS Sonoma")
• {YOUR_WORK_DOMAIN}: Primary domain (e.g., "backend infrastructure", "ML pipelines")

This file shapes Claude's persistent understanding of you. The ADHD-specific patterns — break suggestions, pacing, focus tracking, ask-don't-assume — are designed to prevent the common failure mode where AI agents steamroll your preferences.

Step 4: Configure Your Obsidian Vault Path

Edit ~/.claude/skills/obsidian-vault/SKILL.md:

# Before (generic):
description: Manage Obsidian vault operations. Handles markdown formatting...

# After (personalized):
description: Manage Obsidian vault operations for my vault at ~/Documents/Obsidian/DevVault. Handles markdown formatting...

Then customize references/vault_structure.md to match your actual folders. The default structure is intentionally minimal:

- Programming/
- Projects/
- Daily Log/
- Templates/

Add your domains: Architecture/, Research/, Meetings/, whatever reflects your work.

Step 5: Customize Tags

Both obsidian-vault and daily-journal skills use tags for organization. Find the <!-- Add your own ... --> comments in reference files and extend:

<!-- Add your own tags below -->
- #infrastructure
- #refactoring
- #performance
- #security-review

Tags become your retrieval vocabulary — the words you'll search by later.

REAL Code Examples from the Repository

Let's examine the actual implementation patterns that make this system tick.

Example 1: Hook Configuration for Temporal Awareness

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "type": "command",
        "command": "echo \"Today is $(date '+%A, %B %d, %Y'). Time: $(date '+%H:%M')\"",
        "timeout": 5000
      },
      {
        "type": "command",
        "command": "python3 ~/.claude/hooks/check_alerts.py",
        "timeout": 5000
      }
    ]
  }
}

What's happening here? The UserPromptSubmit hook fires on every prompt you send. The first command runs a shell date command with explicit formatting — +%A for full weekday name, +%B for month, +%d for day, +%Y for year, +%H:%M for 24-hour time. This produces human-readable output like "Today is Thursday, March 20, 2025. Time: 14:32" that Claude receives as context.

The timeout: 5000 ensures a hung script won't block your workflow — 5 seconds max before the hook aborts. The second command runs check_alerts.py, which queries the SQLite database for nudges whose trigger time has passed but haven't been acknowledged.

Why this matters: Without this hook, Claude Code operates in a timeless void. It can't suggest evening wind-down routines, can't accurately timestamp journal entries, can't respect time-based commitments. The hook makes time a first-class citizen in your AI-assisted workflow.

Example 2: Alert Management with Python Scripts

The repository includes three Python scripts for nudge lifecycle management. Here's how they work together:

# Add a nudge for 30 minutes from now
python3 ~/.claude/hooks/add_alert.py "+30m" "Standup prep"

# Add a nudge for specific time
python3 ~/.claude/hooks/add_alert.py "23:00" "Stop coding, go to sleep"

# Check for due nudges (called by hook automatically)
python3 ~/.claude/hooks/check_alerts.py

# Acknowledge/dismiss a fired nudge
python3 ~/.claude/hooks/ack_alert.py 3  # dismiss alert ID 3

Implementation insight: The +30m syntax is parsed to current time plus 30 minutes. The 23:00 syntax is parsed as absolute time today (or tomorrow if already passed). The SQLite backend stores: alert ID, trigger timestamp, message text, created timestamp, and acknowledged boolean.

The check_alerts.py script runs on every prompt submission — it's intrusive by design. You can't ignore a nudge because it surfaces exactly when you're about to continue working. This is behavioral design: friction at the precise moment of continuation, not a dismissible notification.

Example 3: Vault Path Customization in SKILL.md

# Before:
description: Manage Obsidian vault operations. Handles markdown formatting...

# After:
description: Manage Obsidian vault operations for my vault at ~/Documents/Obsidian/DevVault. Handles markdown formatting...

The technical subtlety: Claude Code skills use the description field as part of the prompt context that shapes agent behavior. By embedding the vault path directly in the description, you're using prompt engineering to ground the agent's file operations. When Claude decides where to write a note, it "remembers" your vault location because it's literally in its instruction set.

This pattern — embedding configuration in natural language descriptions — is a powerful technique for Claude Code customization. It's less fragile than separate config files because the context travels with the skill definition.

Example 4: Customizing Vault Structure for Domain Knowledge

# Default structure (minimal)
- Programming/
- Projects/
- Daily Log/
- Templates/

# Extended for backend infrastructure work
- Programming/
  - Go/
  - Rust/
  - Python/
- Projects/
  - Active/
  - Archive/
- Architecture/
  - ADRs/           # Architecture Decision Records
  - RFCs/           # Request for Comments
- Research/
  - Databases/
  - Streaming/
  - Observability/
- Daily Log/
- Meetings/
  - 1-1s/
  - Standups/
- Templates/

How the skill uses this: The obsidian-vault skill references vault_structure.md as a decision tree. When you ask "create a note about Kafka streams," Claude consults this hierarchy and places it in Research/Streaming/ or asks for clarification. Without this structure, notes land randomly and your vault becomes unsearchable chaos.

The <!-- Add your own ... --> comments in reference files are extension points — they're parsed as instructions, not just documentation. Add your tags, add your folders, and the skill adapts.

Advanced Usage & Best Practices

Compound Your Sessions with Journal-Driven Context

Don't just journal — query your journals. Start sessions with: "Read my last three daily logs and identify what I was blocked on." Claude surfaces patterns you'd miss: recurring blockers, abandoned experiments, forgotten insights. Your journal becomes a retrospective database.

Layer Semantic Search for Fuzzy Retrieval

Install obsidian-semantic and configure the obsidian-vault skill to use it. Now you can search: "Find my notes about that caching issue with Redis" — even if you never used the word "issue" or "Redis" in filenames. Meaning-based retrieval defeats the "what did I call that file?" problem forever.

Encode Your Quirks in CLAUDE.md

The template's ADHD patterns are starting points. Add your own: "I hyperfocus on optimization prematurely — ask me to verify the bottleneck is real before suggesting optimizations." or "I forget to eat during long sessions — suggest breaks every 2 hours." The more specific your CLAUDE.md, the more the agent feels like your agent.

Use Nudges as Commitment Devices

Set nudges for social commitments, not just coding boundaries: "+45m remind me to review Sarah's PR" or "16:00 stop for gym". The key is making the nudge costly to ignore — it blocks your prompt submission, so you must actively dismiss it.

Version Control Your Obsidian Vault

Git-init your vault. Skills write markdown; Git tracks changes. You get diffs of your thinking, rollback capability, and sync across machines. The daily-journal skill appends to daily notes — Git shows you exactly when your focus shifted.

Comparison with Alternatives

The verdict: If you want AI assistance that compounds across sessions, claude-adhd-skills is uniquely positioned. Generic tools optimize for single-session throughput. This optimizes for multi-session coherence — the harder problem that determines long-term productivity.

FAQ

Do I actually need ADHD to use claude-adhd-skills?

Absolutely not. The "ADHD" framing describes universal developer experiences: scattered attention, time blindness, context loss, intention-execution gaps. Every developer benefits from time awareness, persistent memory, and behavioral guardrails.

Can I use this without Obsidian?

Partially. The daily-journal and obsidian-vault skills require Obsidian, but the nudge system, date hook, and CLAUDE.md personalization work independently. However, Obsidian integration is where the magic happens — it's worth the setup.

Will this slow down my Claude Code prompts?

Negligibly. The hooks have 5-second timeouts and run simple shell/Python commands. On modern hardware, the date echo completes in milliseconds. The check_alerts.py query is a single SQLite SELECT with an index.

How does this compare to Cursor's memory features?

Cursor has limited cross-session memory and no time awareness. claude-adhd-skills gives you full control over memory structure (your Obsidian vault), semantic search, and time-based behaviors. It's more setup but infinitely more flexible.

Can I customize the nudge timing syntax?

Yes. The add_alert.py script parses natural time expressions. The repository uses +30m and 23:00 as examples, but the parsing logic is straightforward Python — extend it for your preferences.

Is this production-ready?

It's daily-driver ready. Ricardo uses this personally every day. The MIT license means no warranties, but the codebase is small, auditable, and non-intrusive. Worst case: remove the hooks and you're back to vanilla Claude Code.

How do I sync my Obsidian vault across machines?

Options: Obsidian Sync (official, paid), Git + GitHub (free, technical), iCloud/Dropbox (simple, less control). Git is recommended for developers — you get version history and skill portability for free.

Conclusion

The future of AI-assisted development isn't smarter models — it's smarter orchestration. Raw intelligence without memory, time awareness, and behavioral structure is like a genius colleague who forgets every conversation and never checks the clock. Impressive, but exhausting to work with.

claude-adhd-skills solves the orchestration problem with elegant minimalism. Four skills. Three hooks. One personalized CLAUDE.md. The result is an AI agent that knows you, remembers your work, respects your time, and follows your rules.

I've tested dozens of productivity systems for AI-assisted development. Most are either too rigid (prescriptive frameworks that fight your workflow) or too vague ("just journal more!"). This hits the sweet spot: structured enough to compound, flexible enough to personalize.

The repository is waiting at github.com/ravila4/claude-adhd-skills. Fork it. Customize your CLAUDE.md. Point it at your Obsidian vault. Set your first nudge. And experience what it's like when your AI agent finally shows up prepared.

Your future self — the one who remembers why they started, stops when they planned to, and finds yesterday's insights instantly — will thank you.

Star the repo. Try it today. Stop starting from zero.