🌿 DevWell - Proactive AI Health Companion for Developers

An MCP-powered health companion that evaluates your wellness context on every AI interaction and injects proactive coaching through MCP tools and Kiro hooks, so you do not have to ask for reminders.

Live site · Watch the demo

🎯 Problem

Developers spend 6-10+ hours daily at their desks, leading to:

🥤 Dehydration from forgetting to drink water (impairs cognitive function by 15-25%)
💺 Musculoskeletal issues from prolonged sitting (back pain, RSI, tech neck)
🍕 Poor nutrition from skipped meals and excess caffeine
🧠 Mental fatigue & burnout from continuous focus without mindfulness breaks
👁️ Eye strain affecting 50-90% of computer workers

These issues directly reduce code quality, problem-solving ability, and long-term health.

💡 Solution

DevWell is an MCP server that plugs into your AI coding workflow and adds proactive health coaching, powered by your existing AI subscription. It evaluates your health context on every AI interaction and through Kiro hooks, so you do not have to ask for reminders. Once configured, it:

🤖 Proactive on every interaction - evaluates your health context whenever your AI tool calls it or a Kiro hook fires, then injects coaching without you asking
🧠 Learns over time - tracks which hours and intervention types you respond to. It surfaces correlations once it has enough days of data
📊 Tracks analytics - trends, burnout signals, productivity phases and correlations, all computed from your real history
🎯 Respects your flow - protects deep focus, only interrupts when critical
⚡ Zero extra cost - powered by your existing AI tool's subscription or gateway

🔌 Install it into your coding tool (Kiro first)

DevWell runs inside your AI coding tool, not a second terminal. It is built for Kiro and also works in Claude Code and Codex.

Kiro (its home)

DevWell is a Kiro plugin. Its .kiro/ directory is the whole config: .kiro/settings/mcp.json loads the bundled MCP server (34 tools, nothing to build), .kiro/hooks/ make it proactive (a SessionStart health companion and a PostToolUse nudge), .kiro/agents/wellness-coach.md is the coaching voice and .kiro/specs/ are the specs it was built from. Open the repo in Kiro, or point your Kiro MCP config at node /ABSOLUTE/PATH/TO/devwell/plugin/devwell-mcp.cjs.

Claude Code (one-step install)

/plugin marketplace add zkasuran/devwell
/plugin install devwell@devwell

That is it. DevWell is now inside Claude Code:

34 MCP tools, so you log and check health by asking (for example "log 2 waters" or "how is my health").
Slash commands: /devwell:checkin, /devwell:water, /devwell:break, /devwell:meditate.
Two hooks: a SessionStart hook hands the assistant your health context, a UserPromptSubmit hook injects a nudge only when something is due, so reminders arrive in your flow without you asking.
The wellness-coach agent for a dedicated coaching voice.

The plugin bundles a self-contained server (plugin/devwell-mcp.cjs), so there is nothing to build after installing. For an always-visible badge, optionally add a status line to your Claude Code settings.json:

{ "statusLine": { "type": "command", "command": "node /ABSOLUTE/PATH/TO/devwell/plugin/devwell-cli.cjs statusline" } }

Codex

DevWell runs in OpenAI Codex as a plain MCP server too. See the MCP configuration under Quick Start below.

🚀 Quick Start

Prerequisites

Node.js 18+ (download)
One of: Kiro CLI, Claude Code (claude), or any MCP-compatible tool

Installation

# Clone the repository
git clone https://github.com/zkasuran/devwell.git
cd devwell

# Install dependencies
npm install

# Build the project
npm run build

# Verify it works
node dist/cli.js help

Configure with Your AI Tool

Kiro CLI / Kiro IDE

Add to your MCP configuration (.kiro/settings/mcp.json or via Kiro settings):

{
  "mcpServers": {
    "devwell": {
      "command": "node",
      "args": ["/absolute/path/to/devwell/dist/index.js"],
      "env": {}
    }
  }
}

Claude Code (claude CLI)

Add to your Claude Code MCP settings (~/.claude/settings.json):

{
  "mcpServers": {
    "devwell": {
      "command": "node",
      "args": ["/absolute/path/to/devwell/dist/index.js"]
    }
  }
}

OpenAI Codex CLI

Add to your Codex MCP configuration:

{
  "mcpServers": {
    "devwell": {
      "command": "node",
      "args": ["/absolute/path/to/devwell/dist/index.js"]
    }
  }
}

Run it inside your coding CLI (not another terminal)

The point of DevWell is not a separate devwell window you remember to open. It lives inside the tool you already code in, in two ways.

A status line that is always glanceable. devwell statusline prints a one-line health badge:

[💧5/8 | 🏃45m | ☕0mg | 😌 | 🌟80pts]

Wire it into Claude Code's status line and your hydration, sitting time, caffeine, stress and health score sit at the bottom of the CLI, no extra window.

Hooks that let the assistant nudge you in your flow. devwell nudge prints a short reminder only when something is due, and nothing otherwise, so it never adds noise. devwell context prints the coaching context. Fire them from Claude Code hooks so the assistant raises health in context without you asking.

Ready-to-paste Claude Code config is in integrations/claude-code/settings.json (swap in your absolute path):

{
  "statusLine": { "type": "command", "command": "node /ABS/devwell/dist/cli.js statusline" },
  "hooks": {
    "SessionStart": [{ "hooks": [{ "type": "command", "command": "node /ABS/devwell/dist/cli.js context" }] }],
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "node /ABS/devwell/dist/cli.js nudge" }] }]
  }
}

On Kiro, the same proactive behavior comes from the agent hooks in .kiro/hooks/ (a SessionStart and PostToolUse health hook plus a UserPromptSubmit monitor). On Codex or any MCP client, the assistant calls the DevWell tools and appends the health badge to its responses.

First Use

Once configured, just tell your AI tool:

"Activate DevWell autonomous mode"

That's it. DevWell will:

Set up your health profile with sensible defaults
Begin autonomous monitoring immediately
Learn your patterns over time
Intervene at optimal moments
Get better every day

Or customize first:

"Set up my DevWell health profile"
"Configure DevWell autonomous mode - I prefer minimal interruptions"

🤖 Autonomous Operation

How It Works

DevWell evaluates your health on every AI interaction rather than on a background timer. There is no separate daemon: each time your AI tool calls a DevWell tool or a Kiro hook fires, the engine checks your state and can weave in coaching. Once enabled:

┌─────────────────────────────────────────────────────────┐
│          You code normally. DevWell handles the rest.     │
│                                                         │
│  Every AI interaction → Autonomous evaluation            │
│  Health overdue?      → AI naturally reminds you         │
│  Pattern detected?    → Strategy adapts automatically    │
│  Burnout risk?        → Proactive intervention           │
│  Everything fine?     → Silent, invisible                │
└─────────────────────────────────────────────────────────┘

The Self-Improvement Loop

Your Activity → Record Pattern → Analyze → Adapt Strategy → Better Intervention
      ↑                                                            │
      └──────── You Follow/Ignore → Feedback Loop ←────────────────┘

DevWell continuously:

Records when/how it intervenes and whether you respond
Learns which hours, phases, and styles get the best response from you
Adjusts intervention timing, frequency, and messaging
Correlates health behaviors with productivity (water vs focus, breaks vs output) once it has enough days of data
Predicts optimal behaviors based on your accumulated data

Productivity Phase Detection

Phase	Duration	DevWell Behavior
🟢 warming_up	0-15 min	Silent - let you settle in
🔵 building_focus	15-45 min	Only urgent health items
🟣 deep_flow	45-90 min	PROTECTED - critical only
🟡 sustained	90-120 min	Gentle reminders OK
🟠 declining	120-180 min	Proactive suggestions
🔴 fatigued	180+ min	Active intervention

AI Gateway Integration

DevWell uses your existing AI subscription - no extra API costs:

Kiro: System prompts + hooks inject health coaching context
Claude Code: a status line health badge plus SessionStart and UserPromptSubmit hooks (see "Run it inside your coding CLI")
Codex: Tool calls automatically trigger health evaluation

The AI naturally becomes your health companion through context injection.

Burnout Detection

Multi-factor burnout risk scoring:

Session duration (how long without proper breaks)
Break deficiency (missed vs. expected breaks)
Stress accumulation (tracked over days/weeks)
Health score decline (pattern degradation)
Productivity phase (fatigue signals)

When risk is HIGH or CRITICAL, DevWell will strongly encourage you to stop.

📋 Features

💧 Hydration Tracking

Configurable daily water goal (default: 8 glasses)
Customizable reminder intervals (default: 60 minutes)
Visual progress bars with emoji indicators
Evidence-based hydration tips
Smart reminders based on time since last drink

🏃 Exercise & Movement

18 exercises across 8 categories:
- Stretching | Desk exercises | Standing | Walking
- Eye care | Posture | Strength | Light cardio
Exercises tailored to your work style
Step-by-step instructions with proper form guidance
Physical limitation filtering
20-20-20 eye care rule integration
Urgency escalation for prolonged sitting

🥗 Nutrition & Brain Food

18 food suggestions organized by time of day
Brain boost ratings (1-5 stars) based on cognitive science
Meal and snack logging with schedule awareness
Caffeine tracking with daily limits and cutoff times
Dietary restriction support (vegetarian, vegan, gluten-free, etc.)
Cooking willingness consideration (prep time filtering)

🧘 Mindfulness & Meditation

15 guided meditation techniques across 9 categories:
- Breathing | Body scan | Visualization | Mindful coding
- Micro-meditation | Walking meditation | Focus reset
- Gratitude | Progressive relaxation
Work-style-aware recommendations
Stress level tracking with responsive suggestions
Beginner to advanced difficulty levels
Developer-specific techniques (e.g., "Code Architecture Visualization")

📊 Statistics & Gamification

Real-time health score (0-100)
Daily statistics tracking
Weekly trend reports with improvement suggestions
Streak tracking for consistency motivation
Per-category goal progress

⚙️ Personalization

7 work styles with tailored recommendations
Complete preference customization
Persistent profile across sessions
Working hours awareness

🛠️ All MCP Tools (34 Total)

🤖 Autonomous System

Tool	Description
`check_health`	Autonomous health snapshot with AI analysis & burnout detection
`autonomous_status`	View autonomous engine status & next planned action
`configure_autonomous`	Configure intervention style, flow protection, quiet hours
`get_coaching_context`	Get AI coaching system prompt (powers autonomous behavior)
`adaptive_insights`	View learned patterns, responsiveness, correlations
`analytics_dashboard`	Full analytics: trends, heatmaps, predictions, milestones
`burnout_assessment`	Detailed burnout risk with contributing factors
`record_health_action`	Train the AI - record if you followed a recommendation

💧 Hydration

Tool	Description
`log_water`	Log water intake (feeds adaptive learning)
`water_status`	View hydration progress

🏃 Movement

Tool	Description
`log_break`	Log break (feeds adaptive learning)
`suggest_exercise`	AI-personalized exercise for your phase & style
`movement_status`	Sitting analytics with autonomous scheduling

🥗 Nutrition

Tool	Description
`log_meal`	Log meal (system learns patterns)
`log_caffeine`	Track caffeine for sleep analysis
`suggest_nutrition`	AI-powered brain food suggestion
`nutrition_status`	Meal timing & caffeine analytics

🧘 Mindfulness

Tool	Description
`log_meditation`	Log meditation (correlated with stress/productivity)
`suggest_meditation`	AI-selected technique for your phase & stress
`mindfulness_status`	Stress & mindfulness analytics
`set_stress_level`	Report stress (system adapts interventions)

⚙️ Profile & Stats

Tool	Description
`get_profile`	View profile with autonomous preferences
`set_work_style`	Change work style (adapts all recommendations)
`update_preferences`	Update any health preference
`session_info`	Session with productivity phase detection
`daily_stats`	AI-generated daily insights
`weekly_report`	Trend analysis with coaching
`pause_session` / `resume_session`	Control autonomous monitoring

⚡ Smart Notifications & Quick Actions

Tool	Description
`quick`	Ultra-fast health action via shortcodes (w, b, m, c, ok, skip, ...)
`shortcodes`	Show all available quick-action shortcodes
`health_badge`	Compact one-line health status badge to append to any response
`notification_settings`	Configure notification mode, DND hours, frequency, compact mode
`tracking_report`	Event tracking analytics: actions logged, response rates, patterns

🏗️ Architecture

┌─────────────────────────────────────────────┐
│        AI Tool (Kiro / Claude / Codex)       │
└─────────────────────┬───────────────────────┘
                      │ MCP (stdio)
┌─────────────────────▼───────────────────────┐
│              DevWell MCP Server              │
│                                             │
│  ┌──────────────────────────────────────┐   │
│  │         Session Manager              │   │
│  └──┬──────┬──────┬──────┬─────────────┘   │
│     │      │      │      │                  │
│  ┌──▼──┐┌──▼──┐┌──▼──┐┌──▼────┐            │
│  │Water││Move ││Food ││Medita│            │
│  │Track││Track││Track││tion  │            │
│  └─────┘└─────┘└─────┘└──────┘            │
│     │      │      │      │                  │
│  ┌──▼──────▼──────▼──────▼─────────────┐   │
│  │    Profile + Stats (Persistence)     │   │
│  └─────────────────────────────────────┘   │
└─────────────────────────────────────────────┘

📁 Project Structure

devwell/
├── .kiro/                    # Kiro configuration
│   ├── specs/                # Feature specifications
│   │   ├── devwell-health-mcp.md
│   │   ├── hydration-module.md
│   │   ├── movement-module.md
│   │   ├── nutrition-module.md
│   │   └── mindfulness-module.md
│   ├── steering/             # Development guidelines
│   │   ├── project-conventions.md
│   │   ├── mcp-protocol-guidelines.md
│   │   └── health-science.md
│   └── hooks/                # Automated hooks
│       ├── pre-commit-lint.json
│       ├── test-on-change.json
│       ├── health-reminder.json
│       └── build-check.json
├── src/
│   ├── core/                 # Core engine
│   │   ├── types.ts          # All TypeScript interfaces
│   │   ├── session-manager.ts
│   │   ├── profile-manager.ts
│   │   └── stats-manager.ts
│   ├── modules/              # Health modules
│   │   ├── hydration.ts
│   │   ├── movement.ts
│   │   ├── nutrition.ts
│   │   └── mindfulness.ts
│   ├── mcp/                  # MCP server layer
│   │   └── server.ts
│   ├── data/                 # Health databases
│   │   ├── exercises.ts      # 18 exercises
│   │   ├── nutrition.ts      # 18 food suggestions
│   │   └── meditations.ts    # 15 techniques
│   ├── utils/
│   │   └── paths.ts
│   ├── index.ts              # MCP server entry
│   └── cli.ts                # CLI entry
├── tests/                    # Test suite
├── package.json
├── tsconfig.json
└── README.md

🧪 Testing

# Run all tests
npm test

# Build and verify
npm run build

# Test CLI directly
node dist/cli.js status
node dist/cli.js water 1
node dist/cli.js exercise
node dist/cli.js meditate

# In-CLI integration commands
node dist/cli.js statusline   # one-line health badge for a CLI status line
node dist/cli.js nudge        # a proactive reminder, printed only when one is due
node dist/cli.js context      # the coaching context for a SessionStart hook

🔧 Configuration

Environment Variables

Variable	Description	Default
`DEVWELL_DATA_DIR`	Custom data storage path	Platform-specific
`DEVWELL_CONFIG_DIR`	Custom config path	Platform-specific

Data Storage Paths

Platform	Data Directory
Linux	`~/.local/share/devwell/`
macOS	`~/Library/Application Support/devwell/`
Windows	`%APPDATA%/devwell/`

Customizable Preferences

Water goal: 1-20 glasses/day
Water reminder: 15-120 minutes
Break interval: 15-120 minutes
Exercise intensity: light / moderate / vigorous
Caffeine limit: 0-600mg/day
Caffeine cutoff: any hour
Meditation duration: 1-30 minutes
Dietary restrictions: vegetarian, vegan, gluten_free, dairy_free, nut_free, low_sugar, high_protein, keto, paleo
Work style: deep_focus, pomodoro, collaborative, creative, debugging, review, learning

🎨 How Kiro Was Used

DevWell was built entirely using Kiro, leveraging:

Spec-Driven Development: All features were first defined as specifications in .kiro/specs/ before implementation. The main spec defined the architecture, module-level specs defined each health domain, and the autonomous engine spec drove the self-improving AI system.
Steering Files: Development conventions, MCP protocol guidelines, and health science references in .kiro/steering/ ensured consistent code quality, evidence-based recommendations, and proper autonomous behavior.
Agent Hooks:
- SessionStart hook activates autonomous health monitoring
- UserPromptSubmit hook injects health context into every interaction
- PostFileSave hooks for TypeScript compilation and test running
- PostToolUse hook for autonomous health evaluation
Custom Agent: The wellness-coach.md agent definition provides the AI personality and behavior guidelines for autonomous health coaching.
MCP Configuration: The .kiro/settings/mcp.json configures DevWell as a self-contained MCP server that the AI tool uses for health management.
Iterative Development: Each system was built incrementally with Kiro - from types → core → modules → autonomous engine → adaptive learning → MCP layer.

🔒 Privacy

100% local: All health data stored on your machine only
No telemetry: Zero data transmitted to any server
No cloud: Works completely offline after installation
Your data: Delete ~/.local/share/devwell/ to remove all data

📜 License

MIT License - see LICENSE file.

🙏 Attribution

Model Context Protocol SDK - MCP server framework
Health guidelines based on WHO, FDA, American Academy of Ophthalmology, and published research
Exercise and meditation techniques adapted from established wellness practices

🤝 Contributing

Contributions welcome! Please read the steering files in .kiro/steering/ for code conventions.

Built with 🌿 by a developer, for developers. Because great code starts with a healthy coder.

Name		Name	Last commit message	Last commit date
.claude-plugin		.claude-plugin
.kiro		.kiro
agents		agents
commands		commands
hooks		hooks
integrations/claude-code		integrations/claude-code
plugin		plugin
src		src
tests		tests
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.mcp.json		.mcp.json
LICENSE		LICENSE
README.md		README.md
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Latest commit

History

Folders and files

Repository files navigation