Merge branch 'auto-claude/028-fix-kanban-view-task-display-styling'

fix to spec runner paths
auto-claude: subtask-1-1 - Restructure SortableFeatureCard badge layout
2025-12-17 22:19:09 +01:00 · 2025-12-17 22:18:11 +01:00 · 2025-12-17 22:04:47 +01:00 · 2025-12-17 21:42:53 +01:00 · 2025-12-17 18:23:47 +01:00 · 2025-12-17 17:28:02 +01:00
896 changed files with 126895 additions and 45153 deletions
@@ -0,0 +1,166 @@
+# App.tsx Refactoring Summary
+
+## Overview
+Successfully refactored the monolithic App.tsx file (2,217 lines) into a well-organized, modular structure with 488 lines in the main App.tsx file - a **78% reduction** in file size.
+
+## File Size Comparison
+- **Original**: 2,217 lines
+- **Refactored**: 488 lines
+- **Reduction**: 1,729 lines (78%)
+
+## New Directory Structure
+
+```
+src/
+├── animations/
+│   ├── constants.ts       # Animation variants and transition presets
+│   └── index.ts
+├── components/
+│   ├── Avatar.tsx         # Avatar and AvatarGroup components
+│   ├── Badge.tsx          # Badge component with variants
+│   ├── Button.tsx         # Button component with sizes and variants
+│   ├── Card.tsx           # Card container component
+│   ├── Input.tsx          # Input field component
+│   ├── ProgressCircle.tsx # Circular progress indicator
+│   ├── Toggle.tsx         # Toggle switch component
+│   └── index.ts
+├── demo-cards/
+│   ├── CalendarCard.tsx          # Calendar widget demo
+│   ├── IntegrationsCard.tsx      # Integrations panel demo
+│   ├── MilestoneCard.tsx         # Milestone tracking demo
+│   ├── NotificationsCard.tsx     # Notifications panel demo
+│   ├── ProfileCard.tsx           # User profile card demo
+│   ├── ProjectStatusCard.tsx     # Project status demo
+│   ├── TeamMembersCard.tsx       # Team members list demo
+│   └── index.ts
+├── theme/
+│   ├── constants.ts       # Theme definitions (7 color themes)
+│   ├── ThemeSelector.tsx  # Theme dropdown and mode toggle UI
+│   ├── types.ts           # TypeScript interfaces for themes
+│   ├── useTheme.ts        # Custom hook for theme management
+│   └── index.ts
+├── lib/
+│   └── utils.ts           # Utility functions (cn helper)
+├── sections/
+│   └── (empty - ready for future section extractions)
+└── App.tsx                # Main application entry point (488 lines)
+```
+
+## Extracted Modules
+
+### 1. Theme System (`theme/`)
+- **types.ts**: ColorTheme, Mode, ThemeConfig, ThemePreviewColors, ColorThemeDefinition
+- **constants.ts**: COLOR_THEMES array with 7 themes (default, dusk, lime, ocean, retro, neo, forest)
+- **useTheme.ts**: Custom React hook for theme state management with localStorage persistence
+- **ThemeSelector.tsx**: UI component for theme switching with dropdown and light/dark toggle
+
+### 2. Base Components (`components/`)
+All reusable UI components extracted with proper TypeScript interfaces:
+- **Button**: 5 variants (primary, secondary, ghost, success, danger), 3 sizes, pill option
+- **Badge**: 6 variants (default, primary, success, warning, error, outline)
+- **Avatar**: 6 sizes (xs, sm, md, lg, xl, 2xl), with AvatarGroup for multiple avatars
+- **Card**: Container with optional padding
+- **Input**: Text input with focus states and disabled support
+- **Toggle**: Switch component with checked state
+- **ProgressCircle**: SVG-based circular progress indicator with 3 sizes
+
+### 3. Demo Cards (`demo-cards/`)
+Feature showcase components demonstrating the design system:
+- **ProfileCard**: User profile with avatar, name, role, and skill badges
+- **NotificationsCard**: Notification list with actions
+- **CalendarCard**: Interactive calendar widget
+- **TeamMembersCard**: Team member list with payment integrations
+- **ProjectStatusCard**: Project progress with team avatars
+- **MilestoneCard**: Milestone tracker with progress and assignees
+- **IntegrationsCard**: Integration toggles for Slack, Google Meet, GitHub
+
+### 4. Animations (`animations/`)
+- **constants.ts**: Animation variants (fadeIn, scaleIn, slideUp, slideDown, slideLeft, slideRight, pop, bounce)
+- **constants.ts**: Transition presets (instant, fast, normal, slow, spring variants, easing functions)
+
+## Benefits of Refactoring
+
+### 1. Improved Maintainability
+- Each component is in its own file with clear responsibility
+- Easy to locate and modify specific functionality
+- Reduced cognitive load when working with the codebase
+
+### 2. Better Code Organization
+- Logical grouping of related functionality
+- Clear separation of concerns (theme, components, demos, animations)
+- Consistent file naming conventions
+
+### 3. Enhanced Reusability
+- Components can be easily imported and reused
+- Type definitions are shared across modules
+- Theme system can be used independently
+
+### 4. Easier Testing
+- Individual components can be tested in isolation
+- Smaller files are easier to unit test
+- Mock dependencies are simpler to manage
+
+### 5. Better TypeScript Support
+- Explicit type definitions in separate files
+- Improved IDE autocomplete and IntelliSense
+- Type safety across module boundaries
+
+### 6. Scalability
+- Easy to add new components without cluttering App.tsx
+- Ready for future extractions (animations section, themes section)
+- Clear pattern for organizing new features
+
+## What Remains in App.tsx
+
+The refactored App.tsx now only contains:
+1. Import statements for all extracted modules
+2. Main App component with:
+   - Section navigation state
+   - Theme hook integration
+   - Header with ThemeSelector
+   - Section content (overview, colors, typography, components, animations, themes)
+   - Inline section rendering (can be further extracted if needed)
+
+## Build Verification
+
+The refactored code successfully builds with no errors:
+```
+✓ 1723 modules transformed
+✓ built in 1.38s
+```
+
+All functionality remains intact with the same user experience.
+
+## Future Improvements
+
+The codebase is now ready for additional refactoring:
+
+1. **Section Components**: Extract remaining inline sections:
+   - `ColorsSection.tsx`
+   - `TypographySection.tsx`
+   - `ComponentsSection.tsx`
+   - `AnimationsSection.tsx` (with all animation demos)
+   - `ThemesSection.tsx`
+
+2. **Animation Demos**: Extract individual animation demo components:
+   - `HoverCardDemo`, `ButtonPressDemo`, `StaggeredListDemo`
+   - `ToastDemo`, `ModalDemo`, `CounterDemo`
+   - `LoadingDemo`, `DragDemo`, `ProgressAnimationDemo`
+   - `IconAnimationsDemo`, `AccordionDemo`
+
+3. **Utilities**: Additional helper functions as the codebase grows
+
+4. **Hooks**: Extract more custom hooks for common patterns
+
+5. **Types**: Centralized type definitions file if needed
+
+## Migration Notes
+
+- Original file backed up as `App.tsx.original` and `App.tsx.backup`
+- All imports updated to use new module structure
+- No breaking changes to external API
+- Build process remains unchanged
+
+## Conclusion
+
+This refactoring significantly improves code quality and maintainability while preserving all functionality. The new modular structure makes the codebase easier to understand, test, and extend.
@@ -0,0 +1,75 @@
+export const animationVariants = {
+  // Fade animations
+  fadeIn: {
+    initial: { opacity: 0 },
+    animate: { opacity: 1 },
+    exit: { opacity: 0 }
+  },
+
+  // Scale animations
+  scaleIn: {
+    initial: { opacity: 0, scale: 0.9 },
+    animate: { opacity: 1, scale: 1 },
+    exit: { opacity: 0, scale: 0.9 }
+  },
+
+  // Slide animations
+  slideUp: {
+    initial: { opacity: 0, y: 20 },
+    animate: { opacity: 1, y: 0 },
+    exit: { opacity: 0, y: -20 }
+  },
+
+  slideDown: {
+    initial: { opacity: 0, y: -20 },
+    animate: { opacity: 1, y: 0 },
+    exit: { opacity: 0, y: 20 }
+  },
+
+  slideLeft: {
+    initial: { opacity: 0, x: 20 },
+    animate: { opacity: 1, x: 0 },
+    exit: { opacity: 0, x: -20 }
+  },
+
+  slideRight: {
+    initial: { opacity: 0, x: -20 },
+    animate: { opacity: 1, x: 0 },
+    exit: { opacity: 0, x: 20 }
+  },
+
+  // Spring pop
+  pop: {
+    initial: { opacity: 0, scale: 0.5 },
+    animate: {
+      opacity: 1,
+      scale: 1,
+      transition: { type: 'spring', stiffness: 500, damping: 25 }
+    },
+    exit: { opacity: 0, scale: 0.5 }
+  },
+
+  // Bounce
+  bounce: {
+    initial: { opacity: 0, y: -50 },
+    animate: {
+      opacity: 1,
+      y: 0,
+      transition: { type: 'spring', stiffness: 300, damping: 10 }
+    }
+  }
+}
+
+// Transition presets
+export const transitions = {
+  instant: { duration: 0.05 },
+  fast: { duration: 0.15 },
+  normal: { duration: 0.25 },
+  slow: { duration: 0.4 },
+  spring: { type: 'spring' as const, stiffness: 400, damping: 25 },
+  springBouncy: { type: 'spring' as const, stiffness: 300, damping: 10 },
+  springSmooth: { type: 'spring' as const, stiffness: 200, damping: 20 },
+  easeOut: { duration: 0.25, ease: [0, 0, 0.2, 1] as [number, number, number, number] },
+  easeIn: { duration: 0.25, ease: [0.4, 0, 1, 1] as [number, number, number, number] },
+  easeInOut: { duration: 0.25, ease: [0.4, 0, 0.2, 1] as [number, number, number, number] }
+}
@@ -0,0 +1 @@
+export * from './constants'
@@ -0,0 +1,67 @@
+import React from 'react'
+import { cn } from '../lib/utils'
+
+export interface AvatarProps {
+  src?: string
+  name?: string
+  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'
+  color?: string
+}
+
+export function Avatar({ src, name = 'User', size = 'md', color }: AvatarProps) {
+  const sizes = {
+    xs: 'w-6 h-6 text-[10px]',
+    sm: 'w-8 h-8 text-xs',
+    md: 'w-10 h-10 text-sm',
+    lg: 'w-14 h-14 text-base',
+    xl: 'w-20 h-20 text-xl',
+    '2xl': 'w-[120px] h-[120px] text-3xl'
+  }
+
+  const initials = name.split(' ').map(n => n[0]).join('').slice(0, 2).toUpperCase()
+
+  // Default to neutral gray, can be overridden with color prop
+  const bgStyle = color
+    ? { backgroundColor: color }
+    : {}
+
+  return (
+    <div
+      className={cn(
+        'rounded-full flex items-center justify-center font-semibold border-2 border-(--color-surface-card) overflow-hidden',
+        !color && 'bg-(--color-border-default)',
+        sizes[size]
+      )}
+      style={bgStyle}
+    >
+      {src ? (
+        <img src={src} alt={name} className="w-full h-full object-cover" />
+      ) : (
+        <span className={cn(color ? 'text-white' : 'text-(--color-text-primary)')}>{initials}</span>
+      )}
+    </div>
+  )
+}
+
+interface AvatarGroupProps {
+  avatars: { name: string; src?: string }[]
+  max?: number
+}
+
+export function AvatarGroup({ avatars, max = 4 }: AvatarGroupProps) {
+  const visible = avatars.slice(0, max)
+  const remaining = avatars.length - max
+
+  return (
+    <div className="flex -space-x-2">
+      {visible.map((avatar, i) => (
+        <Avatar key={i} {...avatar} size="sm" />
+      ))}
+      {remaining > 0 && (
+        <div className="w-8 h-8 rounded-full bg-(--color-background-secondary) flex items-center justify-center text-xs font-medium text-(--color-text-secondary) border-2 border-(--color-surface-card)">
+          +{remaining}
+        </div>
+      )}
+    </div>
+  )
+}
@@ -0,0 +1,27 @@
+import React from 'react'
+import { cn } from '../lib/utils'
+
+export interface BadgeProps {
+  children: React.ReactNode
+  variant?: 'default' | 'primary' | 'success' | 'warning' | 'error' | 'outline'
+}
+
+export function Badge({ children, variant = 'default' }: BadgeProps) {
+  const variants = {
+    default: 'bg-(--color-background-secondary) text-(--color-text-secondary)',
+    primary: 'bg-(--color-accent-primary-light) text-(--color-accent-primary)',
+    success: 'bg-(--color-semantic-success-light) text-(--color-semantic-success)',
+    warning: 'bg-(--color-semantic-warning-light) text-(--color-semantic-warning)',
+    error: 'bg-(--color-semantic-error-light) text-(--color-semantic-error)',
+    outline: 'bg-transparent border border-(--color-border-default) text-(--color-text-secondary)'
+  }
+
+  return (
+    <span className={cn(
+      'inline-flex items-center px-3 py-1 rounded-full text-label-small',
+      variants[variant]
+    )}>
+      {children}
+    </span>
+  )
+}
@@ -0,0 +1,44 @@
+import React from 'react'
+import { cn } from '../lib/utils'
+
+export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: 'primary' | 'secondary' | 'ghost' | 'success' | 'danger'
+  size?: 'sm' | 'md' | 'lg'
+  pill?: boolean
+}
+
+export function Button({
+  children,
+  variant = 'primary',
+  size = 'md',
+  pill = false,
+  className,
+  ...props
+}: ButtonProps) {
+  const baseStyles = 'inline-flex items-center justify-center font-medium transition-all duration-200 focus:outline-none focus:ring-2 focus:ring-offset-2'
+
+  const variants = {
+    primary: 'bg-(--color-accent-primary) text-(--color-text-inverse) hover:bg-(--color-accent-primary-hover) focus:ring-(--color-accent-primary)',
+    secondary: 'bg-transparent border border-(--color-border-default) text-(--color-text-primary) hover:bg-(--color-background-secondary)',
+    ghost: 'bg-transparent text-(--color-text-secondary) hover:bg-(--color-background-secondary)',
+    success: 'bg-(--color-semantic-success) text-white hover:opacity-90',
+    danger: 'bg-(--color-semantic-error) text-white hover:opacity-90'
+  }
+
+  const sizes = {
+    sm: 'h-8 px-3 text-xs',
+    md: 'h-10 px-4 text-sm',
+    lg: 'h-12 px-6 text-base'
+  }
+
+  const radius = pill ? 'rounded-full' : 'rounded-md'
+
+  return (
+    <button
+      className={cn(baseStyles, variants[variant], sizes[size], radius, className)}
+      {...props}
+    >
+      {children}
+    </button>
+  )
+}
@@ -0,0 +1,24 @@
+import React from 'react'
+import { cn } from '../lib/utils'
+
+export interface CardProps {
+  children: React.ReactNode
+  className?: string
+  padding?: boolean
+}
+
+export function Card({
+  children,
+  className,
+  padding = true
+}: CardProps) {
+  return (
+    <div className={cn(
+      'bg-(--color-surface-card) rounded-xl shadow-md',
+      padding && 'p-6',
+      className
+    )}>
+      {children}
+    </div>
+  )
+}
@@ -0,0 +1,24 @@
+import React from 'react'
+import { cn } from '../lib/utils'
+
+export function Input({
+  placeholder,
+  className,
+  ...props
+}: React.InputHTMLAttributes<HTMLInputElement>) {
+  return (
+    <input
+      className={cn(
+        'h-10 w-full px-4 rounded-md border border-(--color-border-default)',
+        'bg-(--color-surface-card) text-(--color-text-primary) text-sm',
+        'focus:outline-none focus:border-(--color-accent-primary) focus:ring-2 focus:ring-(--color-accent-primary)/20',
+        'placeholder:text-(--color-text-tertiary)',
+        'transition-all duration-200',
+        'disabled:bg-(--color-background-secondary) disabled:opacity-60',
+        className
+      )}
+      placeholder={placeholder}
+      {...props}
+    />
+  )
+}
@@ -0,0 +1,55 @@
+import React from 'react'
+import { cn } from '../lib/utils'
+
+export interface ProgressCircleProps {
+  value: number
+  size?: 'sm' | 'md' | 'lg'
+  color?: string
+}
+
+export function ProgressCircle({
+  value,
+  size = 'md',
+  color = 'var(--color-accent-primary)'
+}: ProgressCircleProps) {
+  const sizes = {
+    sm: { width: 40, stroke: 4, fontSize: 'text-[10px]' },
+    md: { width: 56, stroke: 5, fontSize: 'text-xs' },
+    lg: { width: 80, stroke: 6, fontSize: 'text-base' }
+  }
+
+  const { width, stroke, fontSize } = sizes[size]
+  const radius = (width - stroke) / 2
+  const circumference = 2 * Math.PI * radius
+  const offset = circumference - (value / 100) * circumference
+
+  return (
+    <div className="relative inline-flex items-center justify-center">
+      <svg width={width} height={width} className="-rotate-90">
+        <circle
+          cx={width / 2}
+          cy={width / 2}
+          r={radius}
+          fill="none"
+          stroke="var(--color-border-default)"
+          strokeWidth={stroke}
+        />
+        <circle
+          cx={width / 2}
+          cy={width / 2}
+          r={radius}
+          fill="none"
+          stroke={color}
+          strokeWidth={stroke}
+          strokeDasharray={circumference}
+          strokeDashoffset={offset}
+          strokeLinecap="round"
+          className="transition-all duration-500"
+        />
+      </svg>
+      <span className={cn('absolute font-semibold', fontSize)}>
+        {value}%
+      </span>
+    </div>
+  )
+}
@@ -0,0 +1,28 @@
+import React from 'react'
+import { cn } from '../lib/utils'
+
+export interface ToggleProps {
+  checked: boolean
+  onChange: (checked: boolean) => void
+}
+
+export function Toggle({ checked, onChange }: ToggleProps) {
+  return (
+    <button
+      role="switch"
+      aria-checked={checked}
+      onClick={() => onChange(!checked)}
+      className={cn(
+        'relative inline-flex h-6 w-11 items-center rounded-full transition-colors duration-200',
+        checked ? 'bg-(--color-accent-primary)' : 'bg-(--color-border-default)'
+      )}
+    >
+      <span
+        className={cn(
+          'inline-block h-5 w-5 rounded-full bg-white shadow-sm transition-transform duration-200',
+          checked ? 'translate-x-[22px]' : 'translate-x-[2px]'
+        )}
+      />
+    </button>
+  )
+}
@@ -0,0 +1,7 @@
+export * from './Button'
+export * from './Badge'
+export * from './Avatar'
+export * from './Card'
+export * from './Input'
+export * from './Toggle'
+export * from './ProgressCircle'
@@ -0,0 +1,56 @@
+import { ChevronLeft, ChevronRight } from 'lucide-react'
+import { cn } from '../lib/utils'
+import { Card } from '../components'
+
+export function CalendarCard() {
+  const days = ['M', 'T', 'W', 'T', 'F', 'S', 'S']
+  const dates = [
+    [29, 30, 31, 1, 2, 3, 4],
+    [5, 6, 7, 8, 9, 10, 11],
+    [12, 13, 14, 15, 16, 17, 18],
+    [19, 20, 21, 22, 23, 24, 25],
+    [26, 27, 28, 29, 30, 31, 1]
+  ]
+
+  return (
+    <Card className="w-[300px]">
+      <div className="flex items-center justify-between mb-4">
+        <button className="p-1 hover:bg-(--color-background-secondary) rounded transition-colors">
+          <ChevronLeft className="w-5 h-5 text-(--color-text-tertiary)" />
+        </button>
+        <h3 className="text-heading-small">February, 2021</h3>
+        <button className="p-1 hover:bg-(--color-background-secondary) rounded transition-colors">
+          <ChevronRight className="w-5 h-5 text-(--color-text-tertiary)" />
+        </button>
+      </div>
+
+      <div className="grid grid-cols-7 gap-1 text-center">
+        {days.map((day, i) => (
+          <div key={i} className="text-label-small text-(--color-text-tertiary) py-2">
+            {day}
+          </div>
+        ))}
+        {dates.flat().map((date, i) => {
+          const isCurrentMonth = (i < 3 && date > 20) || (i > 30 && date < 10) ? false : true
+          const isSelected = date === 26 && isCurrentMonth
+          const isToday = date === 16 && isCurrentMonth
+
+          return (
+            <button
+              key={i}
+              className={cn(
+                'w-9 h-9 rounded-md text-body-medium transition-colors',
+                !isCurrentMonth && 'text-(--color-text-tertiary)',
+                isSelected && 'bg-(--color-accent-primary) text-(--color-text-inverse) rounded-full',
+                isToday && !isSelected && 'text-(--color-accent-primary) font-semibold',
+                !isSelected && 'hover:bg-(--color-background-secondary)'
+              )}
+            >
+              {date}
+            </button>
+          )
+        })}
+      </div>
+    </Card>
+  )
+}
@@ -0,0 +1,39 @@
+import { useState } from 'react'
+import { Slack, Video, Github } from 'lucide-react'
+import { Card, Toggle } from '../components'
+
+export function IntegrationsCard() {
+  const [slack, setSlack] = useState(true)
+  const [meet, setMeet] = useState(true)
+  const [github, setGithub] = useState(false)
+
+  const integrations = [
+    { icon: Slack, name: 'Slack', desc: 'Used as a main source of communication', enabled: slack, toggle: setSlack, color: '#E91E63' },
+    { icon: Video, name: 'Google meet', desc: 'Used for all types of calls', enabled: meet, toggle: setMeet, color: '#00897B' },
+    { icon: Github, name: 'Github', desc: 'Enables automated workflows, code synchronization', enabled: github, toggle: setGithub, color: '#333' }
+  ]
+
+  return (
+    <Card className="w-[320px]">
+      <h3 className="text-heading-medium mb-4">Integrations</h3>
+
+      <div className="space-y-4">
+        {integrations.map((int, i) => (
+          <div key={i} className="flex items-center gap-3">
+            <div
+              className="w-10 h-10 rounded-lg flex items-center justify-center"
+              style={{ backgroundColor: `${int.color}15` }}
+            >
+              <int.icon className="w-5 h-5" style={{ color: int.color }} />
+            </div>
+            <div className="flex-1 min-w-0">
+              <p className="text-heading-small">{int.name}</p>
+              <p className="text-body-small text-(--color-text-secondary) truncate">{int.desc}</p>
+            </div>
+            <Toggle checked={int.enabled} onChange={int.toggle} />
+          </div>
+        ))}
+      </div>
+    </Card>
+  )
+}
@@ -0,0 +1,35 @@
+import { Card, Button, ProgressCircle, AvatarGroup } from '../components'
+
+export function MilestoneCard() {
+  return (
+    <Card className="w-[380px]">
+      <div className="flex items-center justify-between mb-4">
+        <h3 className="text-heading-medium">Wireframes milestone</h3>
+        <Button variant="secondary" size="sm" pill>View details</Button>
+      </div>
+
+      <div className="flex items-center gap-6">
+        <div>
+          <p className="text-body-small text-(--color-text-secondary)">Due date:</p>
+          <p className="text-heading-small">March 20th</p>
+        </div>
+
+        <ProgressCircle value={39} size="lg" />
+
+        <div>
+          <p className="text-body-small text-(--color-text-secondary)">Asignees:</p>
+          <AvatarGroup
+            avatars={[
+              { name: 'A' },
+              { name: 'B' },
+              { name: 'C' },
+              { name: 'D' },
+              { name: 'E' }
+            ]}
+            max={4}
+          />
+        </div>
+      </div>
+    </Card>
+  )
+}
@@ -0,0 +1,63 @@
+import { MoreVertical, Check, X } from 'lucide-react'
+import { Card, Avatar, Badge, Button } from '../components'
+
+export function NotificationsCard() {
+  return (
+    <Card className="w-[320px]" padding={false}>
+      <div className="p-4 border-b border-(--color-border-default)">
+        <div className="flex items-center justify-between">
+          <h3 className="text-heading-small">Notifications</h3>
+          <Badge variant="primary">6</Badge>
+        </div>
+        <p className="text-body-small text-(--color-text-tertiary) mt-1">Unread</p>
+      </div>
+
+      <div className="divide-y divide-(--color-border-default)">
+        <div className="p-4 flex gap-3">
+          <Avatar size="sm" name="Ashlynn George" />
+          <div className="flex-1 min-w-0">
+            <p className="text-body-small">
+              <span className="font-semibold">Ashlynn George</span>
+              <span className="text-(--color-text-tertiary)"> · 1h</span>
+            </p>
+            <p className="text-body-small text-(--color-text-secondary)">
+              has invited you to access "Magma project"
+            </p>
+            <div className="flex gap-2 mt-2">
+              <Button size="sm" variant="success" pill>
+                <Check className="w-3 h-3 mr-1" /> Accept
+              </Button>
+              <Button size="sm" variant="secondary" pill>
+                <X className="w-3 h-3 mr-1" /> Deny request
+              </Button>
+            </div>
+          </div>
+          <button className="p-1 hover:bg-(--color-background-secondary) rounded self-start transition-colors">
+            <MoreVertical className="w-4 h-4 text-(--color-text-tertiary)" />
+          </button>
+        </div>
+
+        <div className="p-4 flex gap-3">
+          <Avatar size="sm" name="Ashlynn George" />
+          <div className="flex-1">
+            <p className="text-body-small">
+              <span className="font-semibold">Ashlynn George</span>
+              <span className="text-(--color-text-tertiary)"> · 1h</span>
+            </p>
+            <p className="text-body-small text-(--color-text-secondary)">
+              changed status of task in "Magma project"
+            </p>
+          </div>
+          <button className="p-1 hover:bg-(--color-background-secondary) rounded self-start transition-colors">
+            <MoreVertical className="w-4 h-4 text-(--color-text-tertiary)" />
+          </button>
+        </div>
+      </div>
+
+      <div className="p-4 flex gap-2 border-t border-(--color-border-default)">
+        <Button variant="secondary" className="flex-1" pill>Mark all as read</Button>
+        <Button variant="primary" className="flex-1" pill>View all</Button>
+      </div>
+    </Card>
+  )
+}
@@ -0,0 +1,24 @@
+import { MoreVertical } from 'lucide-react'
+import { Card, Avatar, Badge } from '../components'
+
+export function ProfileCard() {
+  return (
+    <Card className="w-[280px]">
+      <div className="flex justify-end mb-4">
+        <button className="p-1 hover:bg-(--color-background-secondary) rounded transition-colors">
+          <MoreVertical className="w-5 h-5 text-(--color-text-tertiary)" />
+        </button>
+      </div>
+      <div className="flex flex-col items-center text-center">
+        <Avatar size="2xl" name="Christine Thompson" />
+        <h3 className="text-heading-large mt-4">Christine Thompson</h3>
+        <p className="text-body-medium text-(--color-text-secondary)">Project manager</p>
+        <div className="flex flex-wrap gap-2 mt-4 justify-center">
+          <Badge variant="outline">UI/UX Design</Badge>
+          <Badge variant="outline">Project management</Badge>
+          <Badge variant="outline">Agile methodologies</Badge>
+        </div>
+      </div>
+    </Card>
+  )
+}
@@ -0,0 +1,31 @@
+import { MoreVertical } from 'lucide-react'
+import { Card, ProgressCircle, AvatarGroup } from '../components'
+
+export function ProjectStatusCard() {
+  return (
+    <Card className="w-[380px]">
+      <div className="flex justify-between items-start mb-4">
+        <ProgressCircle value={43} size="md" />
+        <button className="p-1 hover:bg-(--color-background-secondary) rounded transition-colors">
+          <MoreVertical className="w-5 h-5 text-(--color-text-tertiary)" />
+        </button>
+      </div>
+
+      <h3 className="text-heading-large mb-2">Amber website redesign</h3>
+      <p className="text-body-medium text-(--color-text-secondary) mb-4">
+        In today's fast-paced digital landscape, our mission is to transform our website into a more intuitive, engaging, and user-friendly platfor...
+      </p>
+
+      <AvatarGroup
+        avatars={[
+          { name: 'User 1' },
+          { name: 'User 2' },
+          { name: 'User 3' },
+          { name: 'User 4' },
+          { name: 'User 5' }
+        ]}
+        max={4}
+      />
+    </Card>
+  )
+}
@@ -0,0 +1,40 @@
+import { MoreVertical, MessageSquare } from 'lucide-react'
+import { Card, Avatar } from '../components'
+
+export function TeamMembersCard() {
+  const members = [
+    { name: 'Julie Andrews', role: 'Project manager' },
+    { name: 'Kevin Conroy', role: 'Project manager' },
+    { name: 'Jim Connor', role: 'Project manager' },
+    { name: 'Tom Kinley', role: 'Project manager' }
+  ]
+
+  return (
+    <Card className="w-[320px]" padding={false}>
+      <div className="divide-y divide-(--color-border-default)">
+        {members.map((member, i) => (
+          <div key={i} className="p-4 flex items-center gap-3">
+            <Avatar name={member.name} />
+            <div className="flex-1">
+              <p className="text-heading-small">{member.name}</p>
+              <p className="text-body-small text-(--color-text-secondary)">{member.role}</p>
+            </div>
+            <button className="p-1 hover:bg-(--color-background-secondary) rounded transition-colors">
+              <MoreVertical className="w-4 h-4 text-(--color-text-tertiary)" />
+            </button>
+            <button className="p-2 bg-(--color-semantic-error-light) text-(--color-semantic-error) rounded-md hover:opacity-80 transition-opacity">
+              <MessageSquare className="w-4 h-4" />
+            </button>
+          </div>
+        ))}
+      </div>
+
+      <div className="p-4 border-t border-(--color-border-default) flex justify-center gap-3">
+        <img src="https://upload.wikimedia.org/wikipedia/commons/b/ba/Stripe_Logo%2C_revised_2016.svg" alt="Stripe" className="h-6" />
+        <div className="px-3 py-1 bg-[#1A1F71] text-white text-sm font-bold rounded">VISA</div>
+        <div className="px-2 py-1 bg-[#003087] text-white text-xs font-bold rounded">PayPal</div>
+        <div className="w-8 h-8 bg-gradient-to-r from-red-500 to-yellow-500 rounded-full" />
+      </div>
+    </Card>
+  )
+}
@@ -0,0 +1,7 @@
+export * from './ProfileCard'
+export * from './NotificationsCard'
+export * from './CalendarCard'
+export * from './TeamMembersCard'
+export * from './ProjectStatusCard'
+export * from './MilestoneCard'
+export * from './IntegrationsCard'
@@ -0,0 +1,104 @@
+import { useState } from 'react'
+import { ChevronLeft, Check, Sun, Moon } from 'lucide-react'
+import { cn } from '../lib/utils'
+import { ColorTheme, Mode, ColorThemeDefinition } from './types'
+
+interface ThemeSelectorProps {
+  colorTheme: ColorTheme
+  mode: Mode
+  onColorThemeChange: (theme: ColorTheme) => void
+  onModeToggle: () => void
+  themes: ColorThemeDefinition[]
+}
+
+export function ThemeSelector({
+  colorTheme,
+  mode,
+  onColorThemeChange,
+  onModeToggle,
+  themes
+}: ThemeSelectorProps) {
+  const [isOpen, setIsOpen] = useState(false)
+
+  // Find theme with fallback to first theme (default)
+  const currentTheme = themes.find(t => t.id === colorTheme) || themes[0]
+
+  return (
+    <div className="flex items-center gap-3">
+      {/* Color Theme Dropdown */}
+      <div className="relative">
+        <button
+          onClick={() => setIsOpen(!isOpen)}
+          className="flex items-center gap-2 px-3 py-2 rounded-lg bg-(--color-background-secondary) hover:bg-(--color-border-default) transition-colors"
+        >
+          <div
+            className="w-4 h-4 rounded-full border-2 border-white shadow-sm"
+            style={{ backgroundColor: mode === 'dark' ? currentTheme.previewColors.accent : currentTheme.previewColors.bg }}
+          />
+          <span className="text-body-medium font-medium">{currentTheme.name}</span>
+          <ChevronLeft className={cn(
+            "w-4 h-4 text-(--color-text-tertiary) transition-transform",
+            isOpen ? "rotate-90" : "-rotate-90"
+          )} />
+        </button>
+
+        {isOpen && (
+          <>
+            <div
+              className="fixed inset-0 z-40"
+              onClick={() => setIsOpen(false)}
+            />
+            <div className="absolute top-full right-0 mt-2 w-64 p-2 bg-(--color-surface-card) rounded-lg shadow-lg border border-(--color-border-default) z-50">
+              {themes.map((theme) => (
+                <button
+                  key={theme.id}
+                  onClick={() => {
+                    onColorThemeChange(theme.id)
+                    setIsOpen(false)
+                  }}
+                  className={cn(
+                    "w-full flex items-center gap-3 px-3 py-2 rounded-md transition-colors text-left",
+                    colorTheme === theme.id
+                      ? "bg-(--color-accent-primary-light)"
+                      : "hover:bg-(--color-background-secondary)"
+                  )}
+                >
+                  <div className="flex -space-x-1">
+                    <div
+                      className="w-5 h-5 rounded-full border-2 border-white shadow-sm"
+                      style={{ backgroundColor: theme.previewColors.bg }}
+                    />
+                    <div
+                      className="w-5 h-5 rounded-full border-2 border-white shadow-sm"
+                      style={{ backgroundColor: theme.previewColors.accent }}
+                    />
+                  </div>
+                  <div className="flex-1 min-w-0">
+                    <p className="text-body-medium font-medium">{theme.name}</p>
+                    <p className="text-body-small text-(--color-text-tertiary) truncate">{theme.description}</p>
+                  </div>
+                  {colorTheme === theme.id && (
+                    <Check className="w-4 h-4 text-(--color-accent-primary)" />
+                  )}
+                </button>
+              ))}
+            </div>
+          </>
+        )}
+      </div>
+
+      {/* Light/Dark Toggle */}
+      <button
+        onClick={onModeToggle}
+        className="p-2 rounded-lg bg-(--color-background-secondary) hover:bg-(--color-border-default) transition-colors"
+        aria-label={`Switch to ${mode === 'light' ? 'dark' : 'light'} mode`}
+      >
+        {mode === 'light' ? (
+          <Moon className="w-5 h-5 text-(--color-text-secondary)" />
+        ) : (
+          <Sun className="w-5 h-5 text-(--color-text-secondary)" />
+        )}
+      </button>
+    </div>
+  )
+}
@@ -0,0 +1,46 @@
+import { ColorThemeDefinition } from './types'
+
+export const COLOR_THEMES: ColorThemeDefinition[] = [
+  {
+    id: 'default',
+    name: 'Default',
+    description: 'Oscura-inspired with pale yellow accent',
+    previewColors: { bg: '#F2F2ED', accent: '#E6E7A3', darkBg: '#0B0B0F', darkAccent: '#E6E7A3' }
+  },
+  {
+    id: 'dusk',
+    name: 'Dusk',
+    description: 'Warmer variant with slightly lighter dark mode',
+    previewColors: { bg: '#F5F5F0', accent: '#E6E7A3', darkBg: '#131419', darkAccent: '#E6E7A3' }
+  },
+  {
+    id: 'lime',
+    name: 'Lime',
+    description: 'Fresh, energetic lime with purple accents',
+    previewColors: { bg: '#E8F5A3', accent: '#7C3AED', darkBg: '#0F0F1A' }
+  },
+  {
+    id: 'ocean',
+    name: 'Ocean',
+    description: 'Calm, professional blue tones',
+    previewColors: { bg: '#E0F2FE', accent: '#0284C7', darkBg: '#082F49' }
+  },
+  {
+    id: 'retro',
+    name: 'Retro',
+    description: 'Warm, nostalgic amber vibes',
+    previewColors: { bg: '#FEF3C7', accent: '#D97706', darkBg: '#1C1917' }
+  },
+  {
+    id: 'neo',
+    name: 'Neo',
+    description: 'Modern cyberpunk pink/magenta',
+    previewColors: { bg: '#FDF4FF', accent: '#D946EF', darkBg: '#0F0720' }
+  },
+  {
+    id: 'forest',
+    name: 'Forest',
+    description: 'Natural, earthy green tones',
+    previewColors: { bg: '#DCFCE7', accent: '#16A34A', darkBg: '#052E16' }
+  }
+]
@@ -0,0 +1,4 @@
+export * from './types'
+export * from './constants'
+export * from './useTheme'
+export * from './ThemeSelector'
@@ -0,0 +1,21 @@
+export type ColorTheme = 'default' | 'dusk' | 'lime' | 'ocean' | 'retro' | 'neo' | 'forest'
+export type Mode = 'light' | 'dark'
+
+export interface ThemeConfig {
+  colorTheme: ColorTheme
+  mode: Mode
+}
+
+export interface ThemePreviewColors {
+  bg: string
+  accent: string
+  darkBg: string
+  darkAccent?: string
+}
+
+export interface ColorThemeDefinition {
+  id: ColorTheme
+  name: string
+  description: string
+  previewColors: ThemePreviewColors
+}
@@ -0,0 +1,64 @@
+import { useState, useEffect } from 'react'
+import { ThemeConfig, ColorTheme, Mode } from './types'
+import { COLOR_THEMES } from './constants'
+
+export function useTheme() {
+  const [config, setConfig] = useState<ThemeConfig>(() => {
+    if (typeof window !== 'undefined') {
+      const stored = localStorage.getItem('design-system-theme-config')
+      if (stored) {
+        try {
+          const parsed = JSON.parse(stored)
+          // Validate that the stored theme still exists
+          const themeExists = COLOR_THEMES.some(t => t.id === parsed.colorTheme)
+          if (themeExists) {
+            return parsed
+          }
+          // Fall back to default if theme was removed
+          return {
+            colorTheme: 'default' as ColorTheme,
+            mode: parsed.mode || 'light'
+          }
+        } catch {}
+      }
+      return {
+        colorTheme: 'default' as ColorTheme,
+        mode: window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
+      }
+    }
+    return { colorTheme: 'default', mode: 'light' }
+  })
+
+  useEffect(() => {
+    const root = document.documentElement
+
+    // Set color theme
+    if (config.colorTheme === 'default') {
+      root.removeAttribute('data-theme')
+    } else {
+      root.setAttribute('data-theme', config.colorTheme)
+    }
+
+    // Set mode
+    if (config.mode === 'dark') {
+      root.classList.add('dark')
+    } else {
+      root.classList.remove('dark')
+    }
+
+    localStorage.setItem('design-system-theme-config', JSON.stringify(config))
+  }, [config])
+
+  const setColorTheme = (colorTheme: ColorTheme) => setConfig(c => ({ ...c, colorTheme }))
+  const setMode = (mode: Mode) => setConfig(c => ({ ...c, mode }))
+  const toggleMode = () => setConfig(c => ({ ...c, mode: c.mode === 'light' ? 'dark' : 'light' }))
+
+  return {
+    colorTheme: config.colorTheme,
+    mode: config.mode,
+    setColorTheme,
+    setMode,
+    toggleMode,
+    themes: COLOR_THEMES
+  }
+}
@@ -0,0 +1,103 @@
+name: Bug Report
+description: Report a bug or unexpected behavior
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug! Please fill out the sections below.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug Description
+      description: A clear and concise description of the bug.
+      placeholder: What happened?
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What did you expect to happen?
+      placeholder: What should have happened?
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to Reproduce
+      description: Steps to reproduce the behavior.
+      placeholder: |
+        1. Run command '...'
+        2. Click on '...'
+        3. See error
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Error Messages / Logs
+      description: If applicable, paste any error messages or logs.
+      render: shell
+
+  - type: textarea
+    id: screenshots
+    attributes:
+      label: Screenshots
+      description: If applicable, add screenshots to help explain the problem.
+
+  - type: dropdown
+    id: component
+    attributes:
+      label: Component
+      description: Which part of Auto Claude is affected?
+      options:
+        - Python Backend (auto-claude/)
+        - Electron UI (auto-claude-ui/)
+        - Both
+        - Not sure
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Auto Claude Version
+      description: What version are you running? (check package.json or git tag)
+      placeholder: "v2.0.1"
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating System
+      options:
+        - macOS
+        - Windows
+        - Linux
+        - Other
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python Version
+      description: Output of `python --version`
+      placeholder: "3.12.0"
+
+  - type: input
+    id: node-version
+    attributes:
+      label: Node.js Version (for UI issues)
+      description: Output of `node --version`
+      placeholder: "20.10.0"
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: Any other context about the problem.
@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Questions & Discussions
+    url: https://github.com/AndyMik90/Auto-Claude/discussions
+    about: Ask questions and discuss ideas with the community
+  - name: Documentation
+    url: https://github.com/AndyMik90/Auto-Claude#readme
+    about: Check the documentation before opening an issue
@@ -0,0 +1,70 @@
+name: Feature Request
+description: Suggest a new feature or enhancement
+labels: ["enhancement", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting a feature! Please describe your idea below.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem Statement
+      description: What problem does this feature solve? Is this related to a frustration?
+      placeholder: I'm always frustrated when...
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: Describe the solution you'd like to see.
+      placeholder: I would like Auto Claude to...
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Have you considered any alternative solutions or workarounds?
+      placeholder: I've tried...
+
+  - type: dropdown
+    id: component
+    attributes:
+      label: Component
+      description: Which part of Auto Claude would this affect?
+      options:
+        - Python Backend (auto-claude/)
+        - Electron UI (auto-claude-ui/)
+        - Both
+        - New component
+        - Not sure
+    validations:
+      required: true
+
+  - type: dropdown
+    id: priority
+    attributes:
+      label: How important is this feature to you?
+      options:
+        - Nice to have
+        - Important for my workflow
+        - Critical / Blocking my use
+
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: Contribution
+      description: Would you be willing to help implement this?
+      options:
+        - label: I'm willing to submit a PR for this feature
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: Add any other context, mockups, or screenshots about the feature request.
@@ -0,0 +1,44 @@
+## Summary
+
+<!-- Brief description of what this PR does -->
+
+## Type of Change
+
+- [ ] Bug fix (non-breaking change that fixes an issue)
+- [ ] New feature (non-breaking change that adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to change)
+- [ ] Documentation update
+- [ ] Refactoring (no functional changes)
+- [ ] Tests (adding or updating tests)
+
+## Related Issues
+
+<!-- Link any related issues: Fixes #123, Closes #456 -->
+
+## Changes Made
+
+<!-- List the main changes in this PR -->
+
+-
+-
+-
+
+## Screenshots
+
+<!-- If applicable, add screenshots for UI changes -->
+
+## Checklist
+
+- [ ] I have run `pre-commit run --all-files` and fixed any issues
+- [ ] I have added tests for my changes (if applicable)
+- [ ] All existing tests pass locally
+- [ ] I have updated documentation (if applicable)
+- [ ] My code follows the project's code style
+
+## Testing
+
+<!-- Describe how you tested these changes -->
+
+## Additional Notes
+
+<!-- Any additional context or notes for reviewers -->
@@ -0,0 +1,83 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  # Python tests
+  test-python:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.12', '3.13']
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        working-directory: auto-claude
+        run: |
+          uv venv
+          uv pip install -r requirements.txt
+          uv pip install -r ../tests/requirements-test.txt
+
+      - name: Run tests
+        working-directory: auto-claude
+        run: |
+          source .venv/bin/activate
+          pytest ../tests/ -v --tb=short -x
+
+      - name: Run tests with coverage
+        if: matrix.python-version == '3.12'
+        working-directory: auto-claude
+        run: |
+          source .venv/bin/activate
+          pytest ../tests/ -v --cov=. --cov-report=xml --cov-report=term-missing
+
+      - name: Upload coverage reports
+        if: matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v4
+        with:
+          file: ./auto-claude/coverage.xml
+          fail_ci_if_error: false
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+  # Frontend tests
+  test-frontend:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Install dependencies
+        working-directory: auto-claude-ui
+        run: pnpm install --frozen-lockfile --ignore-scripts
+
+      - name: Run tests
+        working-directory: auto-claude-ui
+        run: pnpm test
@@ -0,0 +1,25 @@
+name: Discord Release Notification
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  discord-notification:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Send to Discord
+        uses: SethCohen/github-releases-to-discord@v1.19.0
+        with:
+          webhook_url: ${{ secrets.DISCORD_WEBHOOK_URL }}
+          color: "5793266"
+          username: "Auto Claude Releases"
+          avatar_url: "https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png"
+          footer_title: "Auto Claude Changelog"
+          footer_timestamp: true
+          reduce_headings: true
+          remove_github_reference_links: true
+
@@ -0,0 +1,58 @@
+name: Lint
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  # Python linting
+  python:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install ruff
+        run: pip install ruff
+
+      - name: Run ruff check
+        run: ruff check auto-claude/ --output-format=github
+
+      - name: Run ruff format check
+        run: ruff format auto-claude/ --check --diff
+
+  # TypeScript/React linting
+  frontend:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Install dependencies
+        working-directory: auto-claude-ui
+        run: pnpm install --frozen-lockfile --ignore-scripts
+
+      - name: Run ESLint
+        working-directory: auto-claude-ui
+        run: pnpm lint
+
+      - name: Run TypeScript check
+        working-directory: auto-claude-ui
+        run: pnpm typecheck
@@ -0,0 +1,66 @@
+name: Test on Tag
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  # Python tests
+  test-python:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.12', '3.13']
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        working-directory: auto-claude
+        run: |
+          uv venv
+          uv pip install -r requirements.txt
+          uv pip install -r ../tests/requirements-test.txt
+
+      - name: Run tests
+        working-directory: auto-claude
+        run: |
+          source .venv/bin/activate
+          pytest ../tests/ -v --tb=short
+
+  # Frontend tests
+  test-frontend:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Install dependencies
+        working-directory: auto-claude-ui
+        run: pnpm install --frozen-lockfile --ignore-scripts
+
+      - name: Run tests
+        working-directory: auto-claude-ui
+        run: pnpm test
@@ -2,6 +2,10 @@
 .DS_Store
 Thumbs.db

+# Environment files (contain API keys)
+.env
+.env.local
+
 # Git worktrees (used by auto-build parallel mode)
 .worktrees/

@@ -74,4 +78,11 @@ dmypy.json
 # Development of Auto Build with Auto Build
 dev/

-.auto-claude/
+.auto-claude/
+
+/docs
+
+_bmad
+_bmad-output
+
+.claude
@@ -0,0 +1,6 @@
+#!/bin/sh
+
+# Run lint-staged in auto-claude-ui if there are staged files there
+if git diff --cached --name-only | grep -q "^auto-claude-ui/"; then
+  cd auto-claude-ui && pnpm exec lint-staged
+fi
@@ -0,0 +1,36 @@
+repos:
+  # Python linting (auto-claude/)
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.3
+    hooks:
+      - id: ruff
+        args: [--fix]
+        files: ^auto-claude/
+      - id: ruff-format
+        files: ^auto-claude/
+
+  # Frontend linting (auto-claude-ui/)
+  - repo: local
+    hooks:
+      - id: eslint
+        name: ESLint
+        entry: bash -c 'cd auto-claude-ui && pnpm lint'
+        language: system
+        files: ^auto-claude-ui/.*\.(ts|tsx|js|jsx)$
+        pass_filenames: false
+
+      - id: typecheck
+        name: TypeScript Check
+        entry: bash -c 'cd auto-claude-ui && pnpm typecheck'
+        language: system
+        files: ^auto-claude-ui/.*\.(ts|tsx)$
+        pass_filenames: false
+
+  # General checks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
@@ -1,3 +1,282 @@
+## 2.3.1 - Linux Compatibility Fix
+
+### 🐛 Bug Fixes
+
+- Resolved path handling issues on Linux systems for improved cross-platform compatibility
+
+---
+
+## What's Changed
+
+- fix: Fix to linux path issue by @AndyMik90 in 3276034
+
+## 2.2.0 - 2025-12-17
+
+### ✨ New Features
+
+- Add usage monitoring with profile swap detection to prevent cascading resource issues
+
+- Option to stash changes before merge operations for safer branch integration
+
+- Add hideCloseButton prop to DialogContent component for improved UI flexibility
+
+### 🛠️ Improvements
+
+- Enhance AgentManager to manage task context cleanup and preserve swapCount on restarts
+
+- Improve changelog feature with version tracking, markdown/preview, and persistent styling options
+
+- Refactor merge conflict handling to use branch names instead of commit hashes for better clarity
+
+- Streamline usage monitoring logic by removing unnecessary dynamic imports
+
+- Better handling of lock files during merge conflicts
+
+- Refactor code for improved readability and maintainability
+
+- Refactor IdeationHeader and update handleDeleteSelected logic
+
+### 🐛 Bug Fixes
+
+- Fix worktree merge logic to correctly handle branch operations
+
+- Fix spec_runner.py path resolution after move to runners/ directory
+
+- Fix Discord release webhook failing on large changelogs
+
+- Fix branch logic for merge AI operations
+
+- Hotfix for spec-runner path location
+
+---
+
+## What's Changed
+
+- fix: hotfix/spec-runner path location by @AndyMik90 in f201f7e
+
+- refactor: Remove unnecessary dynamic imports of getUsageMonitor in terminal-handlers.ts to streamline usage monitoring logic by @AndyMik90 in 0da4bc4
+
+- feat: Improve changelog feature, version tracking, markdown/preview, persistent styling options by @AndyMik90 in a0d142b
+
+- refactor: Refactor code for improved readability and maintainability by @AndyMik90 in 473b045
+
+- feat: Enhance AgentManager to manage task context cleanup and preserve swapCount on restarts. Update UsageMonitor to delay profile usage checks to prevent cascading swaps by @AndyMik90 in e5b9488
+
+- feat: Usage-monitoring by @AndyMik90 in de33b2c
+
+- feat: option to stash changes before merge by @AndyMik90 in 7e09739
+
+- refactor: Refactor merge conflict check to use branch names instead of commit hashes by @AndyMik90 in e6d6cea
+
+- fix: worktree merge logic by @AndyMik90 in dfb5cf9
+
+- test: Sign off - all verification passed by @AndyMik90 in 34631c3
+
+- feat: Pass hideCloseButton={showFileExplorer} to DialogContent by @AndyMik90 in 7c327ed
+
+- feat: Add hideCloseButton prop to DialogContent component by @AndyMik90 in 5f9653a
+
+- fix: branch logic for merge AI by @AndyMik90 in 2d2a813
+
+- fix: spec_runner.py path resolution after move to runners/ directory by @AndyMik90 in ce9c2cd
+
+- refactor: Better handling of lock files during merge conflicts by @AndyMik90 in 460c76d
+
+- fix: Discord release webhook failing on large changelogs by @AndyMik90 in 4eb66f5
+
+- chore: Update CHANGELOG with new features, improvements, bug fixes, and other changes by @AndyMik90 in 788b8d0
+
+- refactor: Enhance merge conflict handling by excluding lock files by @AndyMik90 in 957746e
+
+- refactor: Refactor IdeationHeader and update handleDeleteSelected logic by @AndyMik90 in 36338f3
+
+## What's New
+
+### ✨ New Features
+
+- Added GitHub OAuth integration for seamless authentication
+
+- Implemented roadmap feature management with kanban board and drag-and-drop support
+
+- Added ability to select AI model during task creation with agent profiles
+
+- Introduced file explorer integration and referenced files section in task creation wizard
+
+- Added .gitignore entry management during project initialization
+
+- Created comprehensive onboarding wizard with OAuth configuration, Graphiti setup, and first spec guidance
+
+- Introduced Electron MCP for debugging and validation support
+
+- Added BMM workflow status tracking and project scan reporting
+
+### 🛠️ Improvements
+
+- Refactored IdeationHeader component and improved deleteSelected logic
+
+- Refactored backend for upcoming features with improved architecture
+
+- Enhanced RouteDetector to exclude specific directories from route detection
+
+- Improved merge conflict resolution with parallel processing and AI-assisted resolution
+
+- Optimized merge conflict resolution performance and context sending
+
+- Refactored AI resolver to use async context manager and Claude SDK patterns
+
+- Enhanced merge orchestrator logic and frontend UX for conflict handling
+
+- Refactored components for better maintainability and faster development
+
+- Refactored changelog formatter for GitHub Release compatibility
+
+- Enhanced onboarding wizard completion logic and step progression
+
+- Updated README to clarify Auto Claude's role as an AI coding companion
+
+### 🐛 Bug Fixes
+
+- Fixed GraphitiStep TypeScript compilation error
+
+- Added missing onRerunWizard prop to AppSettingsDialog
+
+- Improved merge lock file conflict handling
+
+### 🔧 Other Changes
+
+- Removed .auto-claude and _bmad-output from git tracking (already in .gitignore)
+
+- Updated Python versions in CI workflows
+
+- General linting improvements and code cleanup
+
+---
+
+## What's Changed
+
+- feat: New github oauth integration by @AndyMik90 in afeb54f
+- feat: Implement roadmap feature management kanban with drag-and-drop support by @AndyMik90 in 9403230
+- feat: Agent profiles, be able to select model on task creation by @AndyMik90 in d735c5c
+- feat: Add Referenced Files Section and File Explorer Integration in Task Creation Wizard by @AndyMik90 in 31e4e87
+- feat: Add functionality to manage .gitignore entries during project initialization by @AndyMik90 in 2ac00a9
+- feat: Introduce electron mcp for electron debugging/validation by @AndyMik90 in 3eb2ead
+- feat: Add BMM workflow status tracking and project scan report by @AndyMik90 in 7f6456f
+- refactor: Refactor IdeationHeader and update handleDeleteSelected logic by @AndyMik90 in 36338f3
+- refactor: Big backend refactor for upcoming features by @AndyMik90 in 11fcdf4
+- refactor: Refactoring for better codebase by @AndyMik90 in feb0d4e
+- refactor: Refactor Roadmap component to utilize RoadmapGenerationProgress for better status display by @AndyMik90 in d8e5784
+- refactor: refactoring components for better future maintence and more rapid coding by @AndyMik90 in 131ec4c
+- refactor: Enhance RouteDetector to exclude specific directories from route detection by @AndyMik90 in 08dc24c
+- refactor: Update AI resolver to use Claude Opus model and improve error logging by @AndyMik90 in 1d830ba
+- refactor: Use claude sdk pattern for ai resolver by @AndyMik90 in 4bba9d1
+- refactor: Refactor AI resolver to use async context manager for client connection by @AndyMik90 in 579ea40
+- refactor: Update changelog formatter for GitHub Release compatibility by @AndyMik90 in 3b832db
+- refactor: Enhance onboarding wizard completion logic by @AndyMik90 in 7c01638
+- refactor: Update GraphitiStep to proceed to the next step after successful configuration save by @AndyMik90 in a5a1eb1
+- fix: Add onRerunWizard prop to AppSettingsDialog (qa-requested) by @AndyMik90 in 6b5b714
+- fix: Add first-run detection to App.tsx by @AndyMik90 in 779e36f
+- fix: Add TypeScript compilation check - fix GraphitiStep type error by @AndyMik90 in f90fa80
+- improve: ideation improvements and linting by @AndyMik90 in 36a69fc
+- improve: improve merge conflicts for lock files by @AndyMik90 in a891225
+- improve: Roadmap competitor analysis by @AndyMik90 in ddf47ae
+- improve: parallell merge conflict resolution by @AndyMik90 in f00aa33
+- improve: improvement to speed of merge conflict resolution by @AndyMik90 in 56ff586
+- improve: improve context sending to merge agent by @AndyMik90 in e409ae8
+- improve: better conflict handling in the frontend app for merge contlicts (better UX) by @AndyMik90 in 65937e1
+- improve: resolve claude agent sdk by @AndyMik90 in 901e83a
+- improve: Getting ready for BMAD integration by @AndyMik90 in b94eb65
+- improve: Enhance AI resolver and debugging output by @AndyMik90 in bf787ad
+- improve: Integrate profile environment for OAuth token in task handlers by @AndyMik90 in 01e801a
+- chore: Remove .auto-claude from tracking (already in .gitignore) by @AndyMik90 in 87f353c
+- chore: Update Python versions in CI workflows by @AndyMik90 in 43a338c
+- chore: Linting gods pleased now? by @AndyMik90 in 6aea4bb
+- chore: Linting and test fixes by @AndyMik90 in 140f11f
+- chore: Remove _bmad-output from git tracking by @AndyMik90 in 4cd7500
+- chore: Add _bmad-output to .gitignore by @AndyMik90 in dbe27f0
+- chore: Linting gods are happy by @AndyMik90 in 3fc1592
+- chore: Getting ready for the lint gods by @AndyMik90 in 142cd67
+- chore: CLI testing/linting by @AndyMik90 in d8ad17d
+- chore: CLI and tests by @AndyMik90 in 9a59b7e
+- chore: Update implementation_plan.json - fixes applied by @AndyMik90 in 555a46f
+- chore: Update parallel merge conflict resolution metrics in workspace.py by @AndyMik90 in 2e151ac
+- chore: merge logic v0.3 by @AndyMik90 in c5d33cd
+- chore: merge orcehestrator logic by @AndyMik90 in e8b6669
+- chore: Merge-orchestrator by @AndyMik90 in d8ba532
+- chore: merge orcehstrator logic by @AndyMik90 in e8b6669
+- chore: Electron UI fix for merge orcehstrator by @AndyMik90 in e08ab62
+- chore: Frontend lints by @AndyMik90 in 488bbfa
+- docs: Revise README.md to enhance clarity and focus on Auto Claude's capabilities by @AndyMik90 in f9ef7ea
+- qa: Sign off - all verification passed by @AndyMik90 in b3f4803
+- qa: Rejected - fixes required by @AndyMik90 in 5e56890
+- qa: subtask-6-2 - Run existing tests to verify no regressions by @AndyMik90 in 5f989a4
+- qa: subtask-5-2 - Enhance OAuthStep to detect and display if token is already configured by @AndyMik90 in 50f22da
+- qa: subtask-5-1 - Add settings migration logic - set onboardingCompleted by @AndyMik90 in f57c28e
+- qa: subtask-4-1 - Add 'Re-run Wizard' button to AppSettings navigation by @AndyMik90 in 9144e7f
+- qa: subtask-3-1 - Add first-run detection to App.tsx by @AndyMik90 in 779e36f
+- qa: subtask-2-8 - Create index.ts barrel export for onboarding components by @AndyMik90 in b0af2dc
+- qa: subtask-2-7 - Create OnboardingWizard component by @AndyMik90 in 3de8928
+- qa: subtask-2-6 - Create CompletionStep component - success message by @AndyMik90 in aa0f608
+- qa: subtask-2-5 - Create FirstSpecStep component - guided first spec by @AndyMik90 in 32f17a1
+- qa: subtask-2-4 - Create GraphitiStep component - optional Graphiti/FalkorDB configuration by @AndyMik90 in 61184b0
+- qa: subtask-2-3 - Create OAuthStep component - Claude OAuth token configuration step by @AndyMik90 in 79d622e
+- qa: subtask-2-2 - Create WelcomeStep component by @AndyMik90 in a97f697
+- qa: subtask-2-1 - Create WizardProgress component - step progress indicator by @AndyMik90 in b6e604c
+- qa: subtask-1-2 - Add onboardingCompleted to DEFAULT_APP_SETTINGS by @AndyMik90 in c5a0331
+- qa: subtask-1-1 - Add onboardingCompleted to AppSettings type interface by @AndyMik90 in 7c24b48
+- chore: Version 2.0.1 by @AndyMik90 in 4b242c4
+- test: Merge-orchestrator by @AndyMik90 in d8ba532
+- test: test for ai merge AI by @AndyMik90 in 9d9cf16
+
+## What's New in 2.0.1
+
+### 🚀 New Features
+- **Update Check with Release URLs**: Enhanced update checking functionality to include release URLs, allowing users to easily access release information
+- **Markdown Renderer for Release Notes**: Added markdown renderer in advanced settings to properly display formatted release notes
+- **Terminal Name Generator**: New feature for generating terminal names
+
+### 🔧 Improvements
+- **LLM Provider Naming**: Updated project settings to reflect new LLM provider name
+- **IPC Handlers**: Improved IPC handlers for external link management
+- **UI Simplification**: Refactored App component to simplify project selection display by removing unnecessary wrapper elements
+- **Docker Infrastructure**: Updated FalkorDB service container naming in docker-compose configuration
+- **Documentation**: Improved README with dedicated CLI documentation and infrastructure status information
+
+### 📚 Documentation
+- Enhanced README with comprehensive CLI documentation and setup instructions
+- Added Docker infrastructure status documentation
+
+## What's New in v2.0.0
+
+### New Features
+- **Task Integration**: Connected ideas to tasks with "Go to Task" functionality across the UI
+- **File Explorer Panel**: Implemented file explorer panel with directory listing capabilities
+- **Terminal Task Selection**: Added task selection dropdown in terminal with auto-context loading
+- **Task Archiving**: Introduced task archiving functionality
+- **Graphiti MCP Server Integration**: Added support for Graphiti memory integration
+- **Roadmap Functionality**: New roadmap visualization and management features
+
+### Improvements
+- **File Tree Virtualization**: Refactored FileTree component to use efficient virtualization for improved performance with large file structures
+- **Agent Parallelization**: Improved Claude Code agent decision-making for parallel task execution
+- **Terminal Experience**: Enhanced terminal with task features and visual feedback for better user experience
+- **Python Environment Detection**: Auto-detect Python environment readiness before task execution
+- **Version System**: Cleaner version management system
+- **Project Initialization**: Simpler project initialization process
+
+### Bug Fixes
+- Fixed project settings bug
+- Fixed insight UI sidebar
+- Resolved Kanban and terminal integration issues
+
+### Changed
+- Updated project-store.ts to use proper Dirent type for specDirs variable
+- Refactored codebase for better code quality
+- Removed worktree-worker logic in favor of Claude Code's internal agent system
+- Removed obsolete security configuration file (.auto-claude-security.json)
+
+### Documentation
+- Added CONTRIBUTING.md with development guidelines
+
 ## What's New in v1.1.0

 ### New Features
@@ -60,17 +60,20 @@ python auto-claude/run.py --spec 001 --qa-status

 ### Testing
 ```bash
-# Run all tests
-pytest tests/ -v
+# Install test dependencies (required first time)
+cd auto-claude && uv pip install -r ../tests/requirements-test.txt
+
+# Run all tests (use virtual environment pytest)
+auto-claude/.venv/bin/pytest tests/ -v

 # Run single test file
-pytest tests/test_security.py -v
+auto-claude/.venv/bin/pytest tests/test_security.py -v

 # Run specific test
-pytest tests/test_security.py::test_bash_command_validation -v
+auto-claude/.venv/bin/pytest tests/test_security.py::test_bash_command_validation -v

 # Skip slow tests
-pytest tests/ -m "not slow"
+auto-claude/.venv/bin/pytest tests/ -m "not slow"
 ```

 ### Spec Validation
@@ -8,8 +8,10 @@ Thank you for your interest in contributing to Auto Claude! This document provid
 - [Development Setup](#development-setup)
  - [Python Backend](#python-backend)
  - [Electron Frontend](#electron-frontend)
+- [Pre-commit Hooks](#pre-commit-hooks)
 - [Code Style](#code-style)
 - [Testing](#testing)
+- [Continuous Integration](#continuous-integration)
 - [Git Workflow](#git-workflow)
  - [Branch Naming](#branch-naming)
  - [Commit Messages](#commit-messages)
@@ -78,6 +80,54 @@ pnpm build
 pnpm package
 ```

+## Pre-commit Hooks
+
+We use [pre-commit](https://pre-commit.com/) to run linting and formatting checks before each commit. This ensures code quality and consistency across the project.
+
+### Setup
+
+```bash
+# Install pre-commit
+pip install pre-commit
+
+# Install the git hooks (run once after cloning)
+pre-commit install
+```
+
+### What Runs on Commit
+
+When you commit, the following checks run automatically:
+
+| Check | Scope | Description |
+|-------|-------|-------------|
+| **ruff** | `auto-claude/` | Python linter with auto-fix |
+| **ruff-format** | `auto-claude/` | Python code formatter |
+| **eslint** | `auto-claude-ui/` | TypeScript/React linter |
+| **typecheck** | `auto-claude-ui/` | TypeScript type checking |
+| **trailing-whitespace** | All files | Removes trailing whitespace |
+| **end-of-file-fixer** | All files | Ensures files end with newline |
+| **check-yaml** | All files | Validates YAML syntax |
+| **check-added-large-files** | All files | Prevents large file commits |
+
+### Running Manually
+
+```bash
+# Run all checks on all files
+pre-commit run --all-files
+
+# Run a specific hook
+pre-commit run ruff --all-files
+
+# Skip hooks temporarily (not recommended)
+git commit --no-verify -m "message"
+```
+
+### If a Check Fails
+
+1. **Ruff auto-fixes**: Some issues are fixed automatically. Stage the changes and commit again.
+2. **ESLint errors**: Fix the reported issues in your code.
+3. **Type errors**: Resolve TypeScript type issues before committing.
+
 ## Code Style

 ### Python
@@ -192,6 +242,43 @@ Before submitting a PR:
 3. **Bug fixes should include a regression test**
 4. **Test coverage should not decrease significantly**

+## Continuous Integration
+
+All pull requests and pushes to `main` trigger automated CI checks via GitHub Actions.
+
+### Workflows
+
+| Workflow | Trigger | What it checks |
+|----------|---------|----------------|
+| **CI** | Push to `main`, PRs | Python tests (3.11 & 3.12), Frontend tests |
+| **Lint** | Push to `main`, PRs | Ruff (Python), ESLint + TypeScript (Frontend) |
+| **Test on Tag** | Version tags (`v*`) | Full test suite before release |
+
+### PR Requirements
+
+Before a PR can be merged:
+
+1. All CI checks must pass (green checkmarks)
+2. Python tests pass on both Python 3.11 and 3.12
+3. Frontend tests pass
+4. Linting passes (no ruff or eslint errors)
+5. TypeScript type checking passes
+
+### Running CI Checks Locally
+
+```bash
+# Python tests
+cd auto-claude
+source .venv/bin/activate
+pytest ../tests/ -v
+
+# Frontend tests
+cd auto-claude-ui
+pnpm test
+pnpm lint
+pnpm typecheck
+```
+
 ## Git Workflow

 ### Branch Naming
@@ -1,49 +1,73 @@
 # Auto Claude

-A production-ready framework for autonomous multi-session AI coding. Build complete applications or add features to existing projects through coordinated AI agent sessions.
+Your AI coding companion. Build features, fix bugs, and ship faster — with autonomous agents that plan, code, and validate for you.

-## What It Does
+![Auto Claude Kanban Board](.github/assets/Auto-Claude-Kanban.png)

-Auto Claude uses a **multi-agent pattern** to build software autonomously:
+[![Discord](https://img.shields.io/badge/Discord-Join%20Community-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/maj9EWmY)

-### Spec Creation Pipeline (8 phases)
-1. **Discovery** - Analyzes project structure
-2. **Requirements Gatherer** - Collects user requirements interactively
-3. **Research Agent** - Validates external integrations against documentation
-4. **Context Discovery** - Finds relevant files in codebase
-5. **Spec Writer** - Creates comprehensive spec.md
-6. **Spec Critic** - Uses ultrathink to find and fix issues before implementation
-7. **Planner** - Creates chunk-based implementation plan
-8. **Validation** - Ensures all outputs are valid
+## What It Does ✨

-### Implementation Pipeline
-1. **Planner Agent** (Session 1) - Analyzes spec, creates chunk-based implementation plan
-2. **Coder Agent** (Sessions 2+) - Implements chunks one-by-one with verification
-3. **QA Reviewer Agent** - Validates all acceptance criteria before sign-off
-4. **QA Fixer Agent** - Fixes issues found by QA in a self-validating loop
+**Auto Claude is a desktop app that supercharges your AI coding workflow.** Whether you're a vibe coder just getting started or an experienced developer, Auto Claude meets you where you are.

-Each session runs with a fresh context window. Progress is tracked via `implementation_plan.json` and Git commits.
+- **Autonomous Tasks** — Describe what you want to build, and agents handle planning, coding, and validation while you focus on other work
+- **Agent Terminals** — Run Claude Code in up to 12 terminals with a clean layout, smart naming based on context, and one-click task context injection
+- **Safe by Default** — All work happens in git worktrees, keeping your main branch undisturbed until you're ready to merge
+- **Self-Validating** — Built-in QA agents check their own work before you review

-## Quick Start
+**The result?** 10x your output while maintaining code quality.
+
+## Key Features
+
+- **Parallel Agents**: Run multiple builds simultaneously while you focus on other work
+- **Context Engineering**: Agents understand your codebase structure before writing code
+- **Self-Validating**: Built-in QA loop catches issues before you review
+- **Isolated Workspaces**: All work happens in git worktrees — your code stays safe
+- **AI Merge Resolution**: Intelligent conflict resolution when merging back to main — no manual conflict fixing
+- **Memory Layer**: Agents remember insights across sessions for smarter decisions
+- **Cross-Platform**: Desktop app runs on Mac, Windows, and Linux
+- **Any Project Type**: Build web apps, APIs, CLIs — works with any software project
+
+## 🚀 Quick Start (Desktop UI)
+
+The Desktop UI is the recommended way to use Auto Claude. It provides visual task management, real-time progress tracking, and a Kanban board interface.

 ### Prerequisites

- Python 3.8+
- Claude Code CLI (`npm install -g @anthropic-ai/claude-code`)
+1. **Node.js 18+** - [Download Node.js](https://nodejs.org/)
+2. **Python 3.9+** - [Download Python](https://www.python.org/downloads/)
+3. **Docker Desktop** - Required for the Memory Layer
+4. **Claude Code CLI** - `npm install -g @anthropic-ai/claude-code`
+5. **Claude Subscription** - Requires [Claude Pro or Max](https://claude.ai/upgrade) for Claude Code access

-### Setup
+---

-**Step 1:** Copy the `auto-claude` folder into your project
+### Installing Docker Desktop
+
+Docker runs the FalkorDB database that powers Auto Claude's cross-session memory.
+
+| Operating System | Download Link |
+|------------------|---------------|
+| **Mac (Apple Silicon M1/M2/M3/M4)** | [Download for Apple Chip](https://desktop.docker.com/mac/main/arm64/Docker.dmg) |
+| **Mac (Intel)** | [Download for Intel Chip](https://desktop.docker.com/mac/main/amd64/Docker.dmg) |
+| **Windows** | [Download for Windows](https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe) |
+| **Linux** | [Installation Guide](https://docs.docker.com/desktop/install/linux-install/) |
+
+> **Not sure which Mac?** Click the Apple menu (🍎) → "About This Mac". Look for "Chip" - M1/M2/M3/M4 = Apple Silicon, otherwise Intel.
+
+**After installing:** Open Docker Desktop and wait for the whale icon (🐳) to appear in your menu bar/system tray.
+
+> **Using the Desktop UI?** It automatically detects Docker status and offers one-click FalkorDB setup. No terminal commands needed!
+
+📚 **For detailed installation steps, troubleshooting, and advanced configuration, see [guides/DOCKER-SETUP.md](guides/DOCKER-SETUP.md)**
+
+---
+
+### Step 1: Set Up the Python Backend
+
+The Desktop UI runs Python scripts behind the scenes. Set up the Python environment:

 ```bash
-# Copy the auto-claude folder to your project root
-cp -r auto-claude /path/to/your/project/
-```
-
-**Step 2:** Set up Python environment
-
-```bash
-cd your-project
 cd auto-claude

 # Using uv (recommended)
@@ -53,373 +77,208 @@ uv venv && uv pip install -r requirements.txt
 python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt
 ```

-**Step 3:** Configure environment
+### Step 2: Start the Memory Layer
+
+The Auto Claude Memory Layer provides cross-session context retention using a graph database:

 ```bash
-cp .env.example .env
-
-# Get your OAuth token
-claude setup-token
-
-# Add the token to .env
-# CLAUDE_CODE_OAUTH_TOKEN=your-token-here
+# Make sure Docker Desktop is running, then:
+docker-compose up -d falkordb
 ```

-**Step 4:** Create a spec using the orchestrator
+### Step 3: Install and Launch the Desktop UI

 ```bash
-# Activate the virtual environment
-source auto-claude/.venv/bin/activate
+cd auto-claude-ui

-# Create a spec interactively
-python auto-claude/spec_runner.py --interactive
+# Install dependencies (pnpm recommended, npm works too)
+pnpm install
+# or: npm install

-# Or with a task description
-python auto-claude/spec_runner.py --task "Add user authentication with OAuth"
+# Build and start the application
+pnpm run build && pnpm run start
+# or: npm run build && npm run start
 ```

-The spec orchestrator will:
-1. Analyze your project structure
-2. Gather requirements interactively
-3. **Research external integrations** against documentation
-4. Discover relevant codebase context
-5. Write the specification
-6. **Self-critique using ultrathink** to find and fix issues
-7. Generate an implementation plan
-8. Validate all outputs
+### Step 4: Start Building

-**Step 5:** Run the autonomous build
+1. Add your project in the UI
+2. Create a new task describing what you want to build
+3. Watch as Auto Claude creates a spec, plans, and implements your feature
+4. Review changes and merge when satisfied

-```bash
-python auto-claude/run.py --spec 001
-```
+---

-### Managing Specs
+## 🎯 Features

-```bash
-# List all specs and their status
-python auto-claude/run.py --list
+### Kanban Board

-# Run a specific spec
-python auto-claude/run.py --spec 001
-python auto-claude/run.py --spec 001-feature-name
+Plan tasks and let AI handle the planning, coding, and validation — all in a visual interface. Track progress from "Planning" to "Done" while agents work autonomously.

-# Run with parallel workers (2-3x speedup for independent phases)
-python auto-claude/run.py --spec 001 --parallel 2
-python auto-claude/run.py --spec 001 --parallel 3
+### Agent Terminals

-# Limit iterations for testing
-python auto-claude/run.py --spec 001 --max-iterations 5
-```
+Spawn up to 12 AI-powered terminals for hands-on coding. Inject task context with a click, reference files from your project, and work rapidly across multiple sessions.

-### QA Validation
+**Power users:** Connect multiple Claude Code subscriptions to run even more agents in parallel — perfect for teams or heavy workloads.

-After all chunks are complete, QA validation runs automatically:
+![Auto Claude Agent Terminals](.github/assets/Auto-Claude-Agents-terminals.png)

-```bash
-# QA runs automatically after build completes
-# To skip automatic QA:
-python auto-claude/run.py --spec 001 --skip-qa
+### Insights

-# Run QA validation manually on a completed build
-python auto-claude/run.py --spec 001 --qa
+Have a conversation about your project in a ChatGPT-style interface. Ask questions, get explanations, and explore your codebase through natural dialogue.

-# Check QA status
-python auto-claude/run.py --spec 001 --qa-status
-```
+### Roadmap

-The QA validation loop:
-1. **QA Reviewer** checks all acceptance criteria (unit tests, integration tests, E2E, browser verification, database migrations)
-2. If issues found → creates `QA_FIX_REQUEST.md`
-3. **QA Fixer** applies fixes
-4. Loop repeats until approved (up to 50 iterations)
-5. Final sign-off recorded in `implementation_plan.json`
+Based on your target audience, AI anticipates and plans the most impactful features you should focus on. Prioritize what matters most to your users.

-### Spec Creation Pipeline (Dynamic Complexity)
+![Auto Claude Roadmap](.github/assets/Auto-Claude-roadmap.png)

-The `spec_runner.py` orchestrator **automatically assesses task complexity** and adapts the number of phases accordingly:
+### Ideation

-```bash
-# Simple task (auto-detected) - runs 3 phases
-python auto-claude/spec_runner.py --task "Fix button color in Header"
+Let AI help you create a project that shines. Rapidly understand your codebase and discover:
+- Code improvements and refactoring opportunities
+- Performance bottlenecks
+- Security vulnerabilities
+- Documentation gaps
+- UI/UX enhancements
+- Overall code quality issues

-# Complex task (auto-detected) - runs 8 phases
-python auto-claude/spec_runner.py --task "Add Graphiti memory integration with FalkorDB"
+### Changelog

-# Force a specific complexity level
-python auto-claude/spec_runner.py --task "Update text" --complexity simple
+Write professional changelogs effortlessly. Generate release notes from completed Auto Claude tasks or integrate with GitHub to create masterclass changelogs automatically.

-# Interactive mode
-python auto-claude/spec_runner.py --interactive
+### Context

-# Continue an interrupted spec
-python auto-claude/spec_runner.py --continue 001-feature
-```
+See exactly what Auto Claude understands about your project — the tech stack, file structure, patterns, and insights it uses to write better code.

-**Complexity Tiers:**
+### AI Merge Resolution

-| Tier | Phases | When Used |
-|------|--------|-----------|
-| **SIMPLE** | 3 | 1-2 files, single service, no integrations (UI fixes, text changes) |
-| **STANDARD** | 6 | 3-10 files, 1-2 services, minimal integrations (features, bug fixes) |
-| **COMPLEX** | 8 | 10+ files, multiple services, external integrations (integrations, migrations) |
-
-**Phase Matrix:**
-
-| Phase | Simple | Standard | Complex |
-|-------|--------|----------|---------|
-| Discovery | ✓ | ✓ | ✓ |
-| Requirements | - | ✓ | ✓ |
-| **Research** | - | - | ✓ |
-| Context | - | ✓ | ✓ |
-| Spec Writing | Quick | Full | Full |
-| **Self-Critique** | - | - | ✓ |
-| Planning | Auto | ✓ | ✓ |
-| Validation | ✓ | ✓ | ✓ |
-
-**Complexity Detection Signals:**
- Keywords: "fix", "typo", "color" → Simple | "integrate", "migrate", "oauth" → Complex
- External integrations detected (redis, postgres, graphiti, etc.)
- Number of files/services mentioned
- Infrastructure changes (docker, deploy, schema)
-
-**Manual validation:**
-```bash
-python auto-claude/validate_spec.py --spec-dir auto-claude/specs/001-feature --checkpoint all
-```
-
-### Isolated Worktrees (Safe by Default)
-
-Auto Claude uses Git worktrees to keep your work completely safe. All AI-generated code is built in a separate workspace (`.worktrees/auto-claude/`) - your current files are never touched until you explicitly merge.
+When your main branch evolves while a build is in progress, Auto Claude automatically resolves merge conflicts using AI — no manual `<<<<<<< HEAD` fixing required.

 **How it works:**
+1. **Git Auto-Merge First** — Simple non-conflicting changes merge instantly without AI
+2. **Conflict-Only AI** — For actual conflicts, AI receives only the specific conflict regions (not entire files), achieving ~98% prompt reduction
+3. **Parallel Processing** — Multiple conflicting files resolve simultaneously for faster merges
+4. **Syntax Validation** — Every merge is validated before being applied

-1. When you run auto-claude, it creates an isolated workspace
-2. All coding happens in `.worktrees/auto-claude/` on its own branch
-3. You can `cd` into the worktree to test the feature before accepting
-4. Only when you're satisfied, merge the changes into your project
+**The result:** A build that was 50+ commits behind main merges in seconds instead of requiring manual conflict resolution.

-**After a build completes, you can:**
+---

-```bash
-# Test the feature in the isolated workspace
-cd .worktrees/auto-claude/
-npm run dev  # or your project's run command
+## CLI Usage (Terminal-Only)

-# See what was changed
-python auto-claude/run.py --spec 001 --review
+For terminal-based workflows, headless servers, or CI/CD integration, see **[guides/CLI-USAGE.md](guides/CLI-USAGE.md)**.

-# Add changes to your project
-python auto-claude/run.py --spec 001 --merge
+## ⚙️ How It Works

-# Discard if you don't like it (requires confirmation)
-python auto-claude/run.py --spec 001 --discard
-```
+Auto Claude focuses on three core principles: **context engineering** (understanding your codebase before writing code), **good coding standards** (following best practices and patterns), and **validation logic** (ensuring code works before you see it).

-**Key benefits:**
+### The Agent Pipeline

- **Safety**: Your uncommitted work is protected - auto-claude won't touch it
- **Testability**: Run and test the feature before committing to it
- **Easy rollback**: Don't like it? Just discard the worktree
- **Parallel-safe**: Multiple workers can build without conflicts
+**Phase 1: Spec Creation** (3-8 phases based on complexity)

-If you have uncommitted changes, auto-claude automatically uses isolated mode. With a clean working directory, you can choose between isolated (recommended) or direct mode.
+Before any code is written, agents gather context and create a detailed specification:

-### Interactive Controls
+1. **Discovery** — Analyzes your project structure and tech stack
+2. **Requirements** — Gathers what you want to build through interactive conversation
+3. **Research** — Validates external integrations against real documentation
+4. **Context Discovery** — Finds relevant files in your codebase
+5. **Spec Writer** — Creates a comprehensive specification document
+6. **Spec Critic** — Self-critiques using extended thinking to find issues early
+7. **Planner** — Breaks work into subtasks with dependencies
+8. **Validation** — Ensures all outputs are valid before proceeding

-While the agent is running, you can:
+**Phase 2: Implementation**

-```bash
-# Pause and optionally add instructions
-Ctrl+C (once)
-# You'll be prompted to add instructions for the agent
-# The agent will read these instructions when you resume
+With a validated spec, coding agents execute the plan:

-# Exit immediately without prompting
-Ctrl+C (twice)
-# Press Ctrl+C again during the prompt to exit
-```
+1. **Planner Agent** — Creates subtask-based implementation plan
+2. **Coder Agent** — Implements subtasks one-by-one with verification
+3. **QA Reviewer** — Validates all acceptance criteria
+4. **QA Fixer** — Fixes issues in a self-healing loop (up to 50 iterations)

-**Alternative (file-based):**
-```bash
-# Create PAUSE file to pause after current session
-touch auto-claude/specs/001-name/PAUSE
+Each session runs with a fresh context window. Progress is tracked via `implementation_plan.json` and Git commits.

-# Manually edit instructions file
-echo "Focus on fixing the login bug first" > auto-claude/specs/001-name/HUMAN_INPUT.md
-```
+**Phase 3: Merge**
+
+When you're ready to merge, AI handles any conflicts that arose while you were working:
+
+1. **Conflict Detection** — Identifies files modified in both main and the build
+2. **3-Tier Resolution** — Git auto-merge → Conflict-only AI → Full-file AI (fallback)
+3. **Parallel Merge** — Multiple files resolve simultaneously
+4. **Staged for Review** — Changes are staged but not committed, so you can review before finalizing
+
+### 🔒 Security Model
+
+Three-layer defense keeps your code safe:
+- **OS Sandbox** — Bash commands run in isolation
+- **Filesystem Restrictions** — Operations limited to project directory
+- **Command Allowlist** — Only approved commands based on your project's stack
+
+### 🧠 Memory Layer
+
+The Memory Layer is a **hybrid RAG system** combining graph nodes with semantic search to deliver the best possible context during AI coding. Agents remember insights from previous sessions, discovered codebase patterns persist and are reusable, and historical context helps agents make smarter decisions.
+
+**Architecture:**
+- **Backend**: FalkorDB (graph database) via Docker
+- **Library**: Graphiti for knowledge graph operations
+- **Providers**: OpenAI, Anthropic, Azure OpenAI, or Ollama (local/offline)
+
+| Setup | LLM | Embeddings | Notes |
+|-------|-----|------------|-------|
+| **OpenAI** | OpenAI | OpenAI | Simplest - single API key |
+| **Anthropic + Voyage** | Anthropic | Voyage AI | High quality |
+| **Ollama** | Ollama | Ollama | Fully offline |
+| **Azure** | Azure OpenAI | Azure OpenAI | Enterprise |

 ## Project Structure

 ```
 your-project/
-├── .worktrees/              # Created during build (git-ignored)
+├── .worktrees/               # Created during build (git-ignored)
 │   └── auto-claude/          # Isolated workspace for AI coding
-├── auto-claude/
-│   ├── run.py               # Build entry point
-│   ├── spec_runner.py       # Spec creation orchestrator (8-phase pipeline)
-│   ├── validate_spec.py     # Spec validation with JSON schemas
-│   ├── agent.py             # Session orchestration
-│   ├── planner.py           # Deterministic implementation planner
-│   ├── worktree.py          # Git worktree management
-│   ├── workspace.py         # Workspace selection UI
-│   ├── coordinator.py       # Parallel execution coordinator
-│   ├── qa_loop.py           # QA validation loop
-│   ├── client.py            # Claude SDK configuration
-│   ├── memory.py            # File-based session memory (primary storage)
-│   ├── graphiti_memory.py   # Graphiti knowledge graph integration (optional)
-│   ├── spec_contract.json   # Spec creation contract (required outputs)
-│   ├── prompts/
-│   │   ├── planner.md       # Session 1 - creates implementation plan
-│   │   ├── coder.md         # Sessions 2+ - implements chunks
-│   │   ├── spec_gatherer.md # Requirements gathering agent
-│   │   ├── spec_researcher.md # External integration research agent
-│   │   ├── spec_writer.md   # Spec document creation agent
-│   │   ├── spec_critic.md   # Self-critique agent (ultrathink)
-│   │   ├── qa_reviewer.md   # QA validation agent
-│   │   └── qa_fixer.md      # QA fix agent
-│   └── specs/
-│       └── 001-feature/     # Each spec in its own folder
-│           ├── spec.md
-│           ├── requirements.json     # User requirements (structured)
-│           ├── research.json         # External integration research
-│           ├── context.json          # Codebase context
-│           ├── critique_report.json  # Self-critique findings
-│           ├── implementation_plan.json
-│           ├── qa_report.md          # QA validation report
-│           └── QA_FIX_REQUEST.md     # Issues to fix (if rejected)
-└── [your project files]
+├── .auto-claude/             # Per-project data (specs, plans, QA reports)
+│   ├── specs/                # Task specifications
+│   ├── roadmap/              # Project roadmap
+│   └── ideation/             # Ideas and planning
+├── auto-claude/              # Python backend (framework code)
+│   ├── run.py                # Build entry point
+│   ├── spec_runner.py        # Spec creation orchestrator
+│   ├── prompts/              # Agent prompt templates
+│   └── ...
+├── auto-claude-ui/           # Electron desktop application
+│   └── ...
+└── docker-compose.yml        # FalkorDB for Memory Layer
 ```

-## Key Features
+## Environment Variables (CLI Only)

- **Domain Agnostic**: Works for any software project (web apps, APIs, CLIs, etc.)
- **Multi-Session**: Unlimited sessions, each with fresh context
- **Research-First Specs**: External integrations validated against documentation before implementation
- **Self-Critique**: Specs are critiqued using ultrathink to find issues before coding begins
- **Parallel Execution**: 2-3x speedup with multiple workers on independent phases
- **Isolated Worktrees**: Build in a separate workspace - your current work is never touched
- **Self-Verifying**: Agents test their work with browser automation before marking complete
- **QA Validation Loop**: Automated QA agent validates all acceptance criteria before sign-off
- **Self-Healing**: QA finds issues → Fixer agent resolves → QA re-validates (up to 50 iterations)
- **8-Phase Spec Pipeline**: Discovery → Requirements → Research → Context → Spec → Critique → Plan → Validate
- **Fix Bugs Immediately**: Agents fix discovered bugs in the same session, not later
- **Defense-in-Depth Security**: OS sandbox, filesystem restrictions, command allowlist
- **Secret Scanning**: Automatic pre-commit scanning blocks secrets with actionable fix instructions
- **Human Intervention**: Pause, add instructions, or stop at any time
- **Multiple Specs**: Track and run multiple specifications independently
- **Graphiti Memory** (Optional): Persistent knowledge graph for cross-session context retention
-
-## Graphiti Memory Integration V2 (Optional)
-
-Auto Claude includes an optional **Graphiti-based persistent memory layer** that enables context retention across coding sessions. This uses FalkorDB as a graph database to store codebase patterns, session insights, and cross-session learnings.
-
-### Why Use Graphiti Memory?
-
- **Cross-session context**: Agents remember insights from previous sessions
- **Pattern recognition**: Discovered codebase patterns persist and are reusable
- **Smarter agents**: Context retrieval helps agents make better decisions
- **Historical hints**: Spec creation, ideation, and roadmap phases receive relevant historical insights
-
-### Multi-Provider Support (V2)
-
-Graphiti Memory V2 supports multiple LLM and embedding providers:
-
-| LLM Providers | Embedding Providers |
-|---------------|---------------------|
-| OpenAI (default) | OpenAI (default) |
-| Anthropic | Voyage AI |
-| Azure OpenAI | Azure OpenAI |
-| Ollama (local) | Ollama (local) |
-
-**Provider Combinations:**
- **OpenAI + OpenAI**: Simplest setup, single API key
- **Anthropic + Voyage**: High-quality LLM with specialized embeddings
- **Ollama + Ollama**: Fully offline, no API keys needed
- **Azure OpenAI + Azure OpenAI**: Enterprise deployments
-
-### Setup
-
-**Step 1:** Install the Graphiti dependency
-
-```bash
-# Uncomment the graphiti line in requirements.txt, or install directly:
-pip install graphiti-core[falkordb]
-```
-
-**Step 2:** Start FalkorDB via Docker
-
-```bash
-docker-compose up -d falkordb
-```
-
-**Step 3:** Configure environment variables
-
-Add to your `.env` file (see `.env.example` for full documentation):
-
-```bash
-# Enable Graphiti integration
-GRAPHITI_ENABLED=true
-
-# Provider selection (defaults to openai)
-GRAPHITI_LLM_PROVIDER=openai
-GRAPHITI_EMBEDDER_PROVIDER=openai
-
-# Example 1: OpenAI (simplest)
-OPENAI_API_KEY=sk-your-openai-key-here
-
-# Example 2: Anthropic + Voyage (high quality)
-# GRAPHITI_LLM_PROVIDER=anthropic
-# GRAPHITI_EMBEDDER_PROVIDER=voyage
-# ANTHROPIC_API_KEY=sk-ant-xxx
-# VOYAGE_API_KEY=pa-xxx
-
-# Example 3: Ollama (fully offline)
-# GRAPHITI_LLM_PROVIDER=ollama
-# GRAPHITI_EMBEDDER_PROVIDER=ollama
-# OLLAMA_LLM_MODEL=deepseek-r1:7b
-# OLLAMA_EMBEDDING_MODEL=nomic-embed-text
-# OLLAMA_EMBEDDING_DIM=768
-```
-
-**Step 4:** Verify it's working
-
-```bash
-python auto-claude/run.py --list
-# Should show: "Graphiti memory: ENABLED"
-
-# Test the full integration
-python auto-claude/test_graphiti_memory.py
-```
-
-### When Disabled
-
-When `GRAPHITI_ENABLED` is not set (default), Auto Claude uses file-based memory only. This is the zero-dependency default that works out of the box.
-
-## Environment Variables
+> **Desktop UI users:** These are configured through the app settings — no manual setup needed.

 | Variable | Required | Description |
 |----------|----------|-------------|
 | `CLAUDE_CODE_OAUTH_TOKEN` | Yes | OAuth token from `claude setup-token` |
 | `AUTO_BUILD_MODEL` | No | Model override (default: claude-opus-4-5-20251101) |
-| `GRAPHITI_ENABLED` | No | Set to `true` to enable Graphiti memory |
-| `GRAPHITI_LLM_PROVIDER` | No | LLM provider: openai, anthropic, azure_openai, ollama |
-| `GRAPHITI_EMBEDDER_PROVIDER` | No | Embedder: openai, voyage, azure_openai, ollama |
+| `GRAPHITI_ENABLED` | Recommended | Set to `true` to enable Memory Layer |
+| `GRAPHITI_LLM_PROVIDER` | For Memory | LLM provider: openai, anthropic, azure_openai, ollama |
+| `GRAPHITI_EMBEDDER_PROVIDER` | For Memory | Embedder: openai, voyage, azure_openai, ollama |
 | `OPENAI_API_KEY` | For OpenAI | Required for OpenAI provider |
 | `ANTHROPIC_API_KEY` | For Anthropic | Required for Anthropic LLM |
 | `VOYAGE_API_KEY` | For Voyage | Required for Voyage embeddings |

-See `auto-claude/.env.example` for complete provider configuration options.
+See `auto-claude/.env.example` for complete configuration options.

-## Documentation
+## 💬 Community

-For parallel execution details:
- How parallelism works
- Performance analysis
- Best practices
- Troubleshooting
+Join our Discord to get help, share what you're building, and connect with other Auto Claude users:

-See [auto-claude/PARALLEL_EXECUTION.md](auto-claude/PARALLEL_EXECUTION.md)
+[![Discord](https://img.shields.io/badge/Discord-Join%20Community-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/maj9EWmY)
+
+## 🤝 Contributing
+
+We welcome contributions! Whether it's bug fixes, new features, or documentation improvements.
+
+See **[CONTRIBUTING.md](CONTRIBUTING.md)** for guidelines on how to get started.

 ## Acknowledgments

@@ -427,4 +286,15 @@ This framework was inspired by Anthropic's [Autonomous Coding Agent](https://git

 ## License

-MIT License
+**AGPL-3.0** - GNU Affero General Public License v3.0
+
+This software is licensed under AGPL-3.0, which means:
+
+- **Attribution Required**: You must give appropriate credit, provide a link to the license, and indicate if changes were made. When using Auto Claude, please credit the project.
+- **Open Source Required**: If you modify this software and distribute it or run it as a service, you must release your source code under AGPL-3.0.
+- **Network Use (Copyleft)**: If you run this software as a network service (e.g., SaaS), users interacting with it over a network must be able to receive the source code.
+- **No Closed-Source Usage**: You cannot use this software in proprietary/closed-source projects without open-sourcing your entire project under AGPL-3.0.
+
+**In simple terms**: You can use Auto Claude freely, but if you build on it, your code must also be open source under AGPL-3.0 and attribute this project. Closed-source commercial use requires a separate license.
+
+For commercial licensing inquiries (closed-source usage), please contact the maintainers.
@@ -0,0 +1,661 @@
+                    GNU AFFERO GENERAL PUBLIC LICENSE
+                       Version 3, 19 November 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server software.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+our General Public Licenses are intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  Developers that use our General Public Licenses protect your rights
+with two steps: (1) assert copyright on the software, and (2) offer
+you this License which gives you legal permission to copy, distribute
+and/or modify the software.
+
+  A secondary benefit of defending all users' freedom is that
+improvements made in alternate versions of the program, if they
+receive widespread use, become available for other developers to
+incorporate.  Many developers of free software are heartened and
+encouraged by the resulting cooperation.  However, in the case of
+software used on network servers, this result may fail to come about.
+The GNU General Public License permits making a modified version and
+letting the public access it on a server without ever releasing its
+source code to the public.
+
+  The GNU Affero General Public License is designed specifically to
+ensure that, in such cases, the modified source code becomes available
+to the community.  It requires the operator of a network server to
+provide the source code of the modified version running there to the
+users of that server.  Therefore, public use of a modified version, on
+a publicly accessible server, gives the public access to the source
+code of the modified version.
+
+  An older license, called the Affero General Public License and
+published by Affero, was designed to accomplish similar goals.  This is
+a different license, not a version of the Affero GPL, but Affero has
+released a new version of the Affero GPL which permits relicensing under
+this license.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU Affero General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Remote Network Interaction; Use with the GNU General Public License.
+
+  Notwithstanding any other provision of this License, if you modify the
+Program, your modified version must prominently offer all users
+interacting with it remotely through a computer network (if your version
+supports such interaction) an opportunity to receive the Corresponding
+Source of your version by providing access to the Corresponding Source
+from a network server at no charge, through some standard or customary
+means of facilitating copying of software.  This Corresponding Source
+shall include the Corresponding Source for any work covered by version 3
+of the GNU General Public License that is incorporated pursuant to the
+following paragraph.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the work with which it is combined will remain governed by version
+3 of the GNU General Public License.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU Affero General Public License from time to time.  Such new versions
+will be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU Affero General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU Affero General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU Affero General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If your software can interact with users remotely through a computer
+network, you should also make sure that it provides a way for users to
+get its source.  For example, if your program is a web application, its
+interface could display a "Source" link that leads users to an archive
+of the code.  There are many ways you could offer source, and different
+solutions will be better for different programs; see section 13 for the
+specific requirements.
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU AGPL, see
+<https://www.gnu.org/licenses/>.
@@ -0,0 +1 @@
+pnpm test
@@ -41,6 +41,22 @@ export default defineConfig({
        '@': resolve(__dirname, 'src/renderer'),
        '@shared': resolve(__dirname, 'src/shared')
      }
+    },
+    server: {
+      watch: {
+        // Ignore directories to prevent HMR conflicts during merge operations
+        // Using absolute paths and broader patterns
+        ignored: [
+          '**/node_modules/**',
+          '**/.git/**',
+          '**/.worktrees/**',
+          '**/.auto-claude/**',
+          '**/out/**',
+          // Ignore the parent autonomous-coding directory's worktrees
+          resolve(__dirname, '../.worktrees/**'),
+          resolve(__dirname, '../.auto-claude/**'),
+        ]
+      }
    }
  }
 });
@@ -32,25 +32,25 @@ export default tseslint.config(
      '@typescript-eslint/explicit-module-boundary-types': 'off',
      '@typescript-eslint/no-explicit-any': 'warn',
      '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
-      '@typescript-eslint/no-empty-object-type': 'off', // Allow empty interfaces for extensibility
-      '@typescript-eslint/no-unsafe-function-type': 'off', // Allow Function type in mocks
+      '@typescript-eslint/no-empty-object-type': 'off',
+      '@typescript-eslint/no-unsafe-function-type': 'off',

      // React
      ...react.configs.recommended.rules,
      'react/react-in-jsx-scope': 'off',
      'react/prop-types': 'off',
      'react/display-name': 'off',
+      'react/no-unescaped-entities': 'off',

-      // React Hooks
-      ...reactHooks.configs.recommended.rules,
+      // React Hooks - only classic rules, no compiler rules
      'react-hooks/rules-of-hooks': 'error',
      'react-hooks/exhaustive-deps': 'warn',
-      'react-hooks/set-state-in-effect': 'warn', // Downgrade to warning

      // General
      'no-console': ['warn', { allow: ['warn', 'error'] }],
      'prefer-const': 'warn',
-      'no-unused-expressions': 'warn'
+      'no-unused-expressions': 'warn',
+      '@typescript-eslint/no-require-imports': 'warn'
    }
  },
  {
@@ -59,6 +59,9 @@ export default tseslint.config(
      globals: {
        ...globals.node
      }
+    },
+    rules: {
+      '@typescript-eslint/no-require-imports': 'off'
    }
  },
  {
@@ -74,4 +77,3 @@ export default tseslint.config(
    ignores: ['out/**', 'dist/**', '.eslintrc.cjs', 'eslint.config.mjs', 'node_modules/**']
  }
 );
-
@@ -1,10 +1,10 @@
 {
  "name": "auto-claude-ui",
-  "version": "1.1.0",
+  "version": "2.3.0",
  "description": "Desktop UI for Auto Claude autonomous coding framework",
  "main": "./out/main/index.js",
  "author": "Auto Claude Team",
-  "license": "MIT",
+  "license": "AGPL-3.0",
  "scripts": {
    "postinstall": "electron-rebuild",
    "dev": "electron-vite dev",
@@ -23,6 +23,7 @@
    "test:coverage": "vitest run --coverage",
    "test:e2e": "npx playwright test --config=e2e/playwright.config.ts",
    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
    "typecheck": "tsc --noEmit"
  },
  "dependencies": {
@@ -44,19 +45,25 @@
    "@radix-ui/react-tabs": "^1.1.13",
    "@radix-ui/react-toast": "^1.2.15",
    "@radix-ui/react-tooltip": "^1.2.8",
+    "@tailwindcss/typography": "^0.5.19",
    "@tanstack/react-virtual": "^3.13.13",
    "@xterm/addon-fit": "^0.10.0",
+    "@xterm/addon-serialize": "^0.13.0",
    "@xterm/addon-web-links": "^0.11.0",
+    "@xterm/addon-webgl": "^0.18.0",
    "@xterm/xterm": "^5.5.0",
    "chokidar": "^5.0.0",
    "class-variance-authority": "^0.7.1",
    "clsx": "^2.1.1",
+    "ioredis": "^5.8.2",
    "lucide-react": "^0.560.0",
    "motion": "^12.23.26",
    "node-pty": "^1.0.0",
-    "react": "^19.2.1",
-    "react-dom": "^19.2.1",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "react-markdown": "^10.1.0",
    "react-resizable-panels": "^3.0.6",
+    "remark-gfm": "^4.0.1",
    "tailwind-merge": "^3.4.0",
    "uuid": "^13.0.0",
    "zustand": "^5.0.9"
@@ -68,6 +75,8 @@
    "@eslint/js": "^9.39.1",
    "@playwright/test": "^1.52.0",
    "@tailwindcss/postcss": "^4.1.17",
+    "@testing-library/react": "^16.1.0",
+    "@types/ioredis": "^4.28.10",
    "@types/node": "^25.0.0",
    "@types/react": "^19.2.7",
    "@types/react-dom": "^19.2.3",
@@ -81,6 +90,9 @@
    "eslint-plugin-react": "^7.37.5",
    "eslint-plugin-react-hooks": "^7.0.1",
    "globals": "^16.5.0",
+    "husky": "^9.1.7",
+    "jsdom": "^26.0.0",
+    "lint-staged": "^16.2.7",
    "postcss": "^8.5.6",
    "tailwindcss": "^4.1.17",
    "typescript": "^5.9.3",
@@ -132,5 +144,10 @@
      ],
      "category": "Development"
    }
+  },
+  "lint-staged": {
+    "*.{ts,tsx}": [
+      "eslint --fix"
+    ]
  }
 }
@@ -14,6 +14,7 @@ export const app = {
    };
    return paths[name] || '/tmp';
  }),
+  getAppPath: vi.fn(() => '/tmp/test-app'),
  getVersion: vi.fn(() => '0.1.0'),
  isPackaged: false,
  on: vi.fn(),
@@ -85,12 +85,12 @@ describe('IPC Bridge Integration', () => {
          id: string,
          settings: object
        ) => Promise<unknown>;
-        await updateProjectSettings('project-id', { parallelEnabled: true });
+        await updateProjectSettings('project-id', { model: 'sonnet' });

        expect(mockIpcRenderer.invoke).toHaveBeenCalledWith(
          'project:updateSettings',
          'project-id',
-          { parallelEnabled: true }
+          { model: 'sonnet' }
        );
      });
    });
@@ -115,15 +115,18 @@ describe('IPC Bridge Integration', () => {
        const createTask = electronAPI['createTask'] as (
          projectId: string,
          title: string,
-          desc: string
+          desc: string,
+          metadata?: unknown
        ) => Promise<unknown>;
        await createTask('project-id', 'Task Title', 'Task description');

+        // Fourth argument is optional metadata (undefined when not provided)
        expect(mockIpcRenderer.invoke).toHaveBeenCalledWith(
          'task:create',
          'project-id',
          'Task Title',
-          'Task description'
+          'Task description',
+          undefined
        );
      });

@@ -29,18 +29,30 @@ vi.mock('child_process', () => ({
  spawn: vi.fn(() => mockProcess)
 }));

+// Auto-claude source path (for getAutoBuildSourcePath to find)
+const AUTO_CLAUDE_SOURCE = path.join(TEST_DIR, 'auto-claude-source');
+
 // Setup test directories
 function setupTestDirs(): void {
  mkdirSync(TEST_PROJECT_PATH, { recursive: true });
-  mkdirSync(path.join(TEST_PROJECT_PATH, 'auto-claude'), { recursive: true });
-  // Create mock spec_runner.py
+
+  // Create auto-claude source directory that getAutoBuildSourcePath looks for
+  mkdirSync(AUTO_CLAUDE_SOURCE, { recursive: true });
+
+  // Create VERSION file (required by getAutoBuildSourcePath)
+  writeFileSync(path.join(AUTO_CLAUDE_SOURCE, 'VERSION'), '1.0.0');
+
+  // Create runners subdirectory (where spec_runner.py lives after restructure)
+  mkdirSync(path.join(AUTO_CLAUDE_SOURCE, 'runners'), { recursive: true });
+
+  // Create mock spec_runner.py in runners/ subdirectory
  writeFileSync(
-    path.join(TEST_PROJECT_PATH, 'auto-claude', 'spec_runner.py'),
+    path.join(AUTO_CLAUDE_SOURCE, 'runners', 'spec_runner.py'),
    '# Mock spec runner\nprint("Starting spec creation")'
  );
  // Create mock run.py
  writeFileSync(
-    path.join(TEST_PROJECT_PATH, 'auto-claude', 'run.py'),
+    path.join(AUTO_CLAUDE_SOURCE, 'run.py'),
    '# Mock run.py\nprint("Starting task execution")'
  );
 }
@@ -75,6 +87,7 @@ describe('Subprocess Spawn Integration', () => {
      const { AgentManager } = await import('../../main/agent');

      const manager = new AgentManager();
+      manager.configure(undefined, AUTO_CLAUDE_SOURCE);
      manager.startSpecCreation('task-1', TEST_PROJECT_PATH, 'Test task description');

      expect(spawn).toHaveBeenCalledWith(
@@ -85,7 +98,7 @@ describe('Subprocess Spawn Integration', () => {
          'Test task description'
        ]),
        expect.objectContaining({
-          cwd: TEST_PROJECT_PATH,
+          cwd: AUTO_CLAUDE_SOURCE,  // Process runs from auto-claude source directory
          env: expect.objectContaining({
            PYTHONUNBUFFERED: '1'
          })
@@ -98,13 +111,14 @@ describe('Subprocess Spawn Integration', () => {
      const { AgentManager } = await import('../../main/agent');

      const manager = new AgentManager();
+      manager.configure(undefined, AUTO_CLAUDE_SOURCE);
      manager.startTaskExecution('task-1', TEST_PROJECT_PATH, 'spec-001');

      expect(spawn).toHaveBeenCalledWith(
        'python3',
        expect.arrayContaining([expect.stringContaining('run.py'), '--spec', 'spec-001']),
        expect.objectContaining({
-          cwd: TEST_PROJECT_PATH
+          cwd: AUTO_CLAUDE_SOURCE  // Process runs from auto-claude source directory
        })
      );
    });
@@ -114,6 +128,7 @@ describe('Subprocess Spawn Integration', () => {
      const { AgentManager } = await import('../../main/agent');

      const manager = new AgentManager();
+      manager.configure(undefined, AUTO_CLAUDE_SOURCE);
      manager.startQAProcess('task-1', TEST_PROJECT_PATH, 'spec-001');

      expect(spawn).toHaveBeenCalledWith(
@@ -125,24 +140,27 @@ describe('Subprocess Spawn Integration', () => {
          '--qa'
        ]),
        expect.objectContaining({
-          cwd: TEST_PROJECT_PATH
+          cwd: AUTO_CLAUDE_SOURCE  // Process runs from auto-claude source directory
        })
      );
    });

-    it('should include parallel options when specified', async () => {
+    it('should accept parallel options without affecting spawn args', async () => {
+      // Note: --parallel was removed from run.py CLI - parallel execution is handled internally by the agent
      const { spawn } = await import('child_process');
      const { AgentManager } = await import('../../main/agent');

      const manager = new AgentManager();
+      manager.configure(undefined, AUTO_CLAUDE_SOURCE);
      manager.startTaskExecution('task-1', TEST_PROJECT_PATH, 'spec-001', {
        parallel: true,
        workers: 4
      });

+      // Should spawn normally - parallel options don't affect CLI args anymore
      expect(spawn).toHaveBeenCalledWith(
        'python3',
-        expect.arrayContaining(['--parallel', '4']),
+        expect.arrayContaining([expect.stringContaining('run.py'), '--spec', 'spec-001']),
        expect.any(Object)
      );
    });
@@ -151,6 +169,7 @@ describe('Subprocess Spawn Integration', () => {
      const { AgentManager } = await import('../../main/agent');

      const manager = new AgentManager();
+      manager.configure(undefined, AUTO_CLAUDE_SOURCE);
      const logHandler = vi.fn();
      manager.on('log', logHandler);

@@ -166,6 +185,7 @@ describe('Subprocess Spawn Integration', () => {
      const { AgentManager } = await import('../../main/agent');

      const manager = new AgentManager();
+      manager.configure(undefined, AUTO_CLAUDE_SOURCE);
      const logHandler = vi.fn();
      manager.on('log', logHandler);

@@ -181,6 +201,7 @@ describe('Subprocess Spawn Integration', () => {
      const { AgentManager } = await import('../../main/agent');

      const manager = new AgentManager();
+      manager.configure(undefined, AUTO_CLAUDE_SOURCE);
      const exitHandler = vi.fn();
      manager.on('exit', exitHandler);

@@ -189,13 +210,15 @@ describe('Subprocess Spawn Integration', () => {
      // Simulate process exit
      mockProcess.emit('exit', 0);

-      expect(exitHandler).toHaveBeenCalledWith('task-1', 0);
+      // Exit event includes taskId, exit code, and process type
+      expect(exitHandler).toHaveBeenCalledWith('task-1', 0, expect.any(String));
    });

    it('should emit error event when process errors', async () => {
      const { AgentManager } = await import('../../main/agent');

      const manager = new AgentManager();
+      manager.configure(undefined, AUTO_CLAUDE_SOURCE);
      const errorHandler = vi.fn();
      manager.on('error', errorHandler);

@@ -211,6 +234,7 @@ describe('Subprocess Spawn Integration', () => {
      const { AgentManager } = await import('../../main/agent');

      const manager = new AgentManager();
+      manager.configure(undefined, AUTO_CLAUDE_SOURCE);
      manager.startSpecCreation('task-1', TEST_PROJECT_PATH, 'Test');

      expect(manager.isRunning('task-1')).toBe(true);
@@ -235,6 +259,7 @@ describe('Subprocess Spawn Integration', () => {
      const { AgentManager } = await import('../../main/agent');

      const manager = new AgentManager();
+      manager.configure(undefined, AUTO_CLAUDE_SOURCE);
      expect(manager.getRunningTasks()).toHaveLength(0);

      manager.startSpecCreation('task-1', TEST_PROJECT_PATH, 'Test 1');
@@ -249,7 +274,7 @@ describe('Subprocess Spawn Integration', () => {
      const { AgentManager } = await import('../../main/agent');

      const manager = new AgentManager();
-      manager.configure('/custom/python3');
+      manager.configure('/custom/python3', AUTO_CLAUDE_SOURCE);

      manager.startSpecCreation('task-1', TEST_PROJECT_PATH, 'Test');

@@ -264,6 +289,7 @@ describe('Subprocess Spawn Integration', () => {
      const { AgentManager } = await import('../../main/agent');

      const manager = new AgentManager();
+      manager.configure(undefined, AUTO_CLAUDE_SOURCE);
      manager.startSpecCreation('task-1', TEST_PROJECT_PATH, 'Test 1');
      manager.startTaskExecution('task-2', TEST_PROJECT_PATH, 'spec-001');

@@ -276,6 +302,7 @@ describe('Subprocess Spawn Integration', () => {
      const { AgentManager } = await import('../../main/agent');

      const manager = new AgentManager();
+      manager.configure(undefined, AUTO_CLAUDE_SOURCE);
      manager.startSpecCreation('task-1', TEST_PROJECT_PATH, 'Test 1');

      // Start another process for same task
@@ -10,11 +10,25 @@ export const TEST_DATA_DIR = '/tmp/auto-claude-ui-tests';

 // Create fresh test directory before each test
 beforeEach(() => {
-  if (existsSync(TEST_DATA_DIR)) {
-    rmSync(TEST_DATA_DIR, { recursive: true, force: true });
+  // Use a unique subdirectory per test to avoid race conditions in parallel tests
+  const testId = `test-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  const testDir = path.join(TEST_DATA_DIR, testId);
+
+  try {
+    if (existsSync(TEST_DATA_DIR)) {
+      rmSync(TEST_DATA_DIR, { recursive: true, force: true });
+    }
+  } catch {
+    // Ignore errors if directory is in use by another parallel test
+    // Each test uses unique subdirectory anyway
+  }
+
+  try {
+    mkdirSync(TEST_DATA_DIR, { recursive: true });
+    mkdirSync(path.join(TEST_DATA_DIR, 'store'), { recursive: true });
+  } catch {
+    // Ignore errors if directory already exists from another parallel test
  }
-  mkdirSync(TEST_DATA_DIR, { recursive: true });
-  mkdirSync(path.join(TEST_DATA_DIR, 'store'), { recursive: true });
 });

 // Clean up test directory after each test
@@ -43,6 +43,7 @@ vi.mock('electron', () => {
        if (name === 'userData') return path.join(TEST_DIR, 'userData');
        return TEST_DIR;
      }),
+      getAppPath: vi.fn(() => TEST_DIR),
      getVersion: vi.fn(() => '0.1.0'),
      isPackaged: false
    },
@@ -252,7 +253,7 @@ describe('IPC Handlers', () => {
        'project:updateSettings',
        {},
        'nonexistent-id',
-        { parallelEnabled: true }
+        { model: 'sonnet' }
      );

      expect(result).toEqual({
@@ -274,7 +275,7 @@ describe('IPC Handlers', () => {
        'project:updateSettings',
        {},
        projectId,
-        { parallelEnabled: true, maxWorkers: 4 }
+        { model: 'sonnet', linearSync: true }
      );

      expect(result).toEqual({ success: true });
@@ -302,12 +303,15 @@ describe('IPC Handlers', () => {
      const { setupIpcHandlers } = await import('../ipc-handlers');
      setupIpcHandlers(mockAgentManager as never, mockTerminalManager as never, () => mockMainWindow as never, mockPythonEnvManager as never);

-      // Add a project first
+      // Create .auto-claude directory first (before adding project so it gets detected)
+      mkdirSync(path.join(TEST_PROJECT_PATH, '.auto-claude', 'specs'), { recursive: true });
+
+      // Add a project - it will detect .auto-claude
      const addResult = await ipcMain.invokeHandler('project:add', {}, TEST_PROJECT_PATH);
      const projectId = (addResult as { data: { id: string } }).data.id;

-      // Create a spec directory with implementation plan
-      const specDir = path.join(TEST_PROJECT_PATH, 'auto-claude', 'specs', '001-test-feature');
+      // Create a spec directory with implementation plan in .auto-claude/specs
+      const specDir = path.join(TEST_PROJECT_PATH, '.auto-claude', 'specs', '001-test-feature');
      mkdirSync(specDir, { recursive: true });
      writeFileSync(path.join(specDir, 'implementation_plan.json'), JSON.stringify({
        feature: 'Test Feature',
@@ -352,10 +356,13 @@ describe('IPC Handlers', () => {
      });
    });

-    it('should create task and start spec creation', async () => {
+    it('should create task in backlog status', async () => {
      const { setupIpcHandlers } = await import('../ipc-handlers');
      setupIpcHandlers(mockAgentManager as never, mockTerminalManager as never, () => mockMainWindow as never, mockPythonEnvManager as never);

+      // Create .auto-claude directory first (before adding project so it gets detected)
+      mkdirSync(path.join(TEST_PROJECT_PATH, '.auto-claude', 'specs'), { recursive: true });
+
      // Add a project first
      const addResult = await ipcMain.invokeHandler('project:add', {}, TEST_PROJECT_PATH);
      const projectId = (addResult as { data: { id: string } }).data.id;
@@ -369,7 +376,9 @@ describe('IPC Handlers', () => {
      );

      expect(result).toHaveProperty('success', true);
-      expect(mockAgentManager.startSpecCreation).toHaveBeenCalled();
+      // Task is created in backlog status, spec creation starts when task:start is called
+      const task = (result as { data: { status: string } }).data;
+      expect(task.status).toBe('backlog');
    });
  });

@@ -462,12 +471,13 @@ describe('IPC Handlers', () => {
      const { setupIpcHandlers } = await import('../ipc-handlers');
      setupIpcHandlers(mockAgentManager as never, mockTerminalManager as never, () => mockMainWindow as never, mockPythonEnvManager as never);

-      mockAgentManager.emit('exit', 'task-1', 0);
+      // Exit event with task-execution processType should result in human_review status
+      mockAgentManager.emit('exit', 'task-1', 0, 'task-execution');

      expect(mockMainWindow.webContents.send).toHaveBeenCalledWith(
        'task:statusChange',
        'task-1',
-        'ai_review'
+        'human_review'
      );
    });
  });
@@ -83,15 +83,15 @@ describe('ProjectStore', () => {
    });

    it('should detect auto-claude directory if present', async () => {
-      // Create auto-claude directory
-      mkdirSync(path.join(TEST_PROJECT_PATH, 'auto-claude'), { recursive: true });
+      // Create .auto-claude directory (the data directory, not source code)
+      mkdirSync(path.join(TEST_PROJECT_PATH, '.auto-claude'), { recursive: true });

      const { ProjectStore } = await import('../project-store');
      const store = new ProjectStore();

      const project = store.addProject(TEST_PROJECT_PATH);

-      expect(project.autoBuildPath).toBe('auto-claude');
+      expect(project.autoBuildPath).toBe('.auto-claude');
    });

    it('should set empty autoBuildPath if not present', async () => {
@@ -208,7 +208,7 @@ describe('ProjectStore', () => {
      const { ProjectStore } = await import('../project-store');
      const store = new ProjectStore();

-      const result = store.updateProjectSettings('nonexistent-id', { parallelEnabled: true });
+      const result = store.updateProjectSettings('nonexistent-id', { model: 'sonnet' });

      expect(result).toBeUndefined();
    });
@@ -219,13 +219,13 @@ describe('ProjectStore', () => {

      const project = store.addProject(TEST_PROJECT_PATH);
      const updated = store.updateProjectSettings(project.id, {
-        parallelEnabled: true,
-        maxWorkers: 4
+        model: 'sonnet',
+        linearSync: true
      });

      expect(updated).toBeDefined();
-      expect(updated?.settings.parallelEnabled).toBe(true);
-      expect(updated?.settings.maxWorkers).toBe(4);
+      expect(updated?.settings.model).toBe('sonnet');
+      expect(updated?.settings.linearSync).toBe(true);
    });

    it('should update updatedAt timestamp', async () => {
@@ -238,7 +238,7 @@ describe('ProjectStore', () => {
      // Small delay to ensure timestamp difference
      await new Promise((resolve) => setTimeout(resolve, 10));

-      const updated = store.updateProjectSettings(project.id, { parallelEnabled: true });
+      const updated = store.updateProjectSettings(project.id, { model: 'haiku' });

      expect(updated?.updatedAt.getTime()).toBeGreaterThan(originalUpdatedAt.getTime());
    });
@@ -248,12 +248,12 @@ describe('ProjectStore', () => {
      const store = new ProjectStore();

      const project = store.addProject(TEST_PROJECT_PATH);
-      store.updateProjectSettings(project.id, { maxWorkers: 8 });
+      store.updateProjectSettings(project.id, { model: 'sonnet' });

      // Read directly from file
      const storePath = path.join(USER_DATA_PATH, 'store', 'projects.json');
      const content = JSON.parse(readFileSync(storePath, 'utf-8'));
-      expect(content.projects[0].settings.maxWorkers).toBe(8);
+      expect(content.projects[0].settings.model).toBe('sonnet');
    });
  });

@@ -278,8 +278,8 @@ describe('ProjectStore', () => {
    });

    it('should read tasks from filesystem correctly', async () => {
-      // Create spec directory structure
-      const specsDir = path.join(TEST_PROJECT_PATH, 'auto-claude', 'specs', '001-test-feature');
+      // Create spec directory structure in .auto-claude (the data directory)
+      const specsDir = path.join(TEST_PROJECT_PATH, '.auto-claude', 'specs', '001-test-feature');
      mkdirSync(specsDir, { recursive: true });

      const plan = {
@@ -325,7 +325,7 @@ describe('ProjectStore', () => {
    });

    it('should determine status as backlog when no subtasks completed', async () => {
-      const specsDir = path.join(TEST_PROJECT_PATH, 'auto-claude', 'specs', '002-pending');
+      const specsDir = path.join(TEST_PROJECT_PATH, '.auto-claude', 'specs', '002-pending');
      mkdirSync(specsDir, { recursive: true });

      const plan = {
@@ -364,7 +364,7 @@ describe('ProjectStore', () => {
    });

    it('should determine status as ai_review when all subtasks completed', async () => {
-      const specsDir = path.join(TEST_PROJECT_PATH, 'auto-claude', 'specs', '003-complete');
+      const specsDir = path.join(TEST_PROJECT_PATH, '.auto-claude', 'specs', '003-complete');
      mkdirSync(specsDir, { recursive: true });

      const plan = {
@@ -403,7 +403,7 @@ describe('ProjectStore', () => {
    });

    it('should determine status as human_review when QA report rejected', async () => {
-      const specsDir = path.join(TEST_PROJECT_PATH, 'auto-claude', 'specs', '004-rejected');
+      const specsDir = path.join(TEST_PROJECT_PATH, '.auto-claude', 'specs', '004-rejected');
      mkdirSync(specsDir, { recursive: true });

      const plan = {
@@ -445,8 +445,9 @@ describe('ProjectStore', () => {
      expect(tasks[0].status).toBe('human_review');
    });

-    it('should determine status as done when QA report approved', async () => {
-      const specsDir = path.join(TEST_PROJECT_PATH, 'auto-claude', 'specs', '005-approved');
+    it('should determine status as human_review when QA report approved', async () => {
+      // QA approval moves task to human_review (user needs to review before marking done)
+      const specsDir = path.join(TEST_PROJECT_PATH, '.auto-claude', 'specs', '005-approved');
      mkdirSync(specsDir, { recursive: true });

      const plan = {
@@ -485,6 +486,47 @@ describe('ProjectStore', () => {
      const project = store.addProject(TEST_PROJECT_PATH);
      const tasks = store.getTasks(project.id);

+      expect(tasks[0].status).toBe('human_review');
+      expect(tasks[0].reviewReason).toBe('completed');
+    });
+
+    it('should determine status as done when plan status is explicitly done', async () => {
+      // User explicitly marking task as done via drag-and-drop sets status to done
+      const specsDir = path.join(TEST_PROJECT_PATH, '.auto-claude', 'specs', '006-done');
+      mkdirSync(specsDir, { recursive: true });
+
+      const plan = {
+        feature: 'Done Feature',
+        workflow_type: 'feature',
+        services_involved: [],
+        status: 'done', // Explicitly set by user
+        phases: [
+          {
+            phase: 1,
+            name: 'Phase 1',
+            type: 'implementation',
+            subtasks: [
+              { id: 'subtask-1', description: 'Subtask 1', status: 'completed' }
+            ]
+          }
+        ],
+        final_acceptance: [],
+        created_at: '2024-01-01T00:00:00Z',
+        updated_at: '2024-01-01T00:00:00Z',
+        spec_file: 'spec.md'
+      };
+
+      writeFileSync(
+        path.join(specsDir, 'implementation_plan.json'),
+        JSON.stringify(plan)
+      );
+
+      const { ProjectStore } = await import('../project-store');
+      const store = new ProjectStore();
+
+      const project = store.addProject(TEST_PROJECT_PATH);
+      const tasks = store.getTasks(project.id);
+
      expect(tasks[0].status).toBe('done');
    });
  });
@@ -501,8 +543,6 @@ describe('ProjectStore', () => {
            path: '/test/path',
            autoBuildPath: '',
            settings: {
-              parallelEnabled: false,
-              maxWorkers: 2,
              model: 'sonnet',
              memoryBackend: 'file',
              linearSync: false,
@@ -511,7 +551,9 @@ describe('ProjectStore', () => {
                onTaskFailed: true,
                onReviewNeeded: true,
                sound: false
-              }
+              },
+              graphitiMcpEnabled: true,
+              graphitiMcpUrl: 'http://localhost:8000/mcp/'
            },
            createdAt: '2024-01-01T00:00:00Z',
            updatedAt: '2024-01-01T00:00:00Z'
@@ -23,6 +23,16 @@ export class AgentManager extends EventEmitter {
  private events: AgentEvents;
  private processManager: AgentProcessManager;
  private queueManager: AgentQueueManager;
+  private taskExecutionContext: Map<string, {
+    projectPath: string;
+    specId: string;
+    options: TaskExecutionOptions;
+    isSpecCreation?: boolean;
+    taskDescription?: string;
+    specDir?: string;
+    metadata?: SpecCreationMetadata;
+    swapCount: number;
+  }> = new Map();

  constructor() {
    super();
@@ -32,6 +42,40 @@ export class AgentManager extends EventEmitter {
    this.events = new AgentEvents();
    this.processManager = new AgentProcessManager(this.state, this.events, this);
    this.queueManager = new AgentQueueManager(this.state, this.events, this.processManager, this);
+
+    // Listen for auto-swap restart events
+    this.on('auto-swap-restart-task', (taskId: string, newProfileId: string) => {
+      console.log('[AgentManager] Auto-swap restart:', taskId, newProfileId);
+      this.restartTask(taskId);
+    });
+
+    // Listen for task completion to clean up context (prevent memory leak)
+    this.on('exit', (taskId: string, code: number | null) => {
+      // Clean up context when:
+      // 1. Task completed successfully (code === 0), or
+      // 2. Task failed and won't be restarted (handled by auto-swap logic)
+
+      // Note: Auto-swap restart happens BEFORE this exit event is processed,
+      // so we need a small delay to allow restart to preserve context
+      setTimeout(() => {
+        const context = this.taskExecutionContext.get(taskId);
+        if (!context) return; // Already cleaned up or restarted
+
+        // If task completed successfully, always clean up
+        if (code === 0) {
+          this.taskExecutionContext.delete(taskId);
+          console.log('[AgentManager] Cleaned up context for completed task:', taskId);
+          return;
+        }
+
+        // If task failed and hit max retries, clean up
+        if (context.swapCount >= 2) {
+          this.taskExecutionContext.delete(taskId);
+          console.log('[AgentManager] Cleaned up context for max-retry task:', taskId);
+        }
+        // Otherwise keep context for potential restart
+      }, 1000); // Delay to allow restart logic to run first
+    });
  }

  /**
@@ -58,7 +102,7 @@ export class AgentManager extends EventEmitter {
      return;
    }

-    const specRunnerPath = path.join(autoBuildSource, 'spec_runner.py');
+    const specRunnerPath = path.join(autoBuildSource, 'runners', 'spec_runner.py');

    if (!existsSync(specRunnerPath)) {
      this.emit('error', taskId, `Spec runner not found at: ${specRunnerPath}`);
@@ -82,6 +126,9 @@ export class AgentManager extends EventEmitter {
      args.push('--auto-approve');
    }

+    // Store context for potential restart
+    this.storeTaskContext(taskId, projectPath, '', {}, true, taskDescription, specDir, metadata);
+
    // Note: This is spec-creation but it chains to task-execution via run.py
    this.processManager.spawnProcess(taskId, autoBuildSource, args, combinedEnv, 'task-execution');
  }
@@ -125,9 +172,17 @@ export class AgentManager extends EventEmitter {
    // Force: When user starts a task from the UI, that IS their approval
    args.push('--force');

+    // Pass base branch if specified (ensures worktrees are created from the correct branch)
+    if (options.baseBranch) {
+      args.push('--base-branch', options.baseBranch);
+    }
+
    // Note: --parallel was removed from run.py CLI - parallel execution is handled internally by the agent
    // The options.parallel and options.workers are kept for future use or logging purposes

+    // Store context for potential restart
+    this.storeTaskContext(taskId, projectPath, specId, options, false);
+
    console.log('[AgentManager] Spawning process with args:', args);
    this.processManager.spawnProcess(taskId, autoBuildSource, args, combinedEnv, 'task-execution');
  }
@@ -168,9 +223,10 @@ export class AgentManager extends EventEmitter {
  startRoadmapGeneration(
    projectId: string,
    projectPath: string,
-    refresh: boolean = false
+    refresh: boolean = false,
+    enableCompetitorAnalysis: boolean = false
  ): void {
-    this.queueManager.startRoadmapGeneration(projectId, projectPath, refresh);
+    this.queueManager.startRoadmapGeneration(projectId, projectPath, refresh, enableCompetitorAnalysis);
  }

  /**
@@ -226,4 +282,78 @@ export class AgentManager extends EventEmitter {
  getRunningTasks(): string[] {
    return this.state.getRunningTaskIds();
  }
+
+  /**
+   * Store task execution context for potential restarts
+   */
+  private storeTaskContext(
+    taskId: string,
+    projectPath: string,
+    specId: string,
+    options: TaskExecutionOptions,
+    isSpecCreation?: boolean,
+    taskDescription?: string,
+    specDir?: string,
+    metadata?: SpecCreationMetadata
+  ): void {
+    // Preserve swapCount if context already exists (for restarts)
+    const existingContext = this.taskExecutionContext.get(taskId);
+    const swapCount = existingContext?.swapCount ?? 0;
+
+    this.taskExecutionContext.set(taskId, {
+      projectPath,
+      specId,
+      options,
+      isSpecCreation,
+      taskDescription,
+      specDir,
+      metadata,
+      swapCount // Preserve existing count instead of resetting
+    });
+  }
+
+  /**
+   * Restart task after profile swap
+   */
+  restartTask(taskId: string): boolean {
+    const context = this.taskExecutionContext.get(taskId);
+    if (!context) {
+      console.error('[AgentManager] No context for task:', taskId);
+      return false;
+    }
+
+    // Prevent infinite swap loops
+    if (context.swapCount >= 2) {
+      console.error('[AgentManager] Max swap count reached for task:', taskId);
+      return false;
+    }
+
+    context.swapCount++;
+    console.log('[AgentManager] Restarting task:', taskId, 'swap count:', context.swapCount);
+
+    // Kill current process
+    this.killTask(taskId);
+
+    // Wait for cleanup, then restart
+    setTimeout(() => {
+      if (context.isSpecCreation) {
+        this.startSpecCreation(
+          taskId,
+          context.projectPath,
+          context.taskDescription!,
+          context.specDir,
+          context.metadata
+        );
+      } else {
+        this.startTaskExecution(
+          taskId,
+          context.projectPath,
+          context.specId,
+          context.options
+        );
+      }
+    }, 500);
+
+    return true;
+  }
 }
@@ -8,6 +8,7 @@ import { AgentEvents } from './agent-events';
 import { ProcessType, ExecutionProgressData } from './types';
 import { detectRateLimit, createSDKRateLimitInfo, getProfileEnv } from '../rate-limit-detector';
 import { projectStore } from '../project-store';
+import { getClaudeProfileManager } from '../claude-profile-manager';

 /**
 * Process spawning and lifecycle management
@@ -280,10 +281,43 @@ export class AgentProcessManager {
            suggestedProfile: rateLimitDetection.suggestedProfile?.name
          });

-          // Determine source type based on processType
-          const source = processType === 'spec-creation' ? 'task' : 'task';
+          // Check if auto-swap is enabled
+          const profileManager = getClaudeProfileManager();
+          const autoSwitchSettings = profileManager.getAutoSwitchSettings();

-          // Emit rate limit event
+          if (autoSwitchSettings.enabled && autoSwitchSettings.autoSwitchOnRateLimit) {
+            console.log('[spawnProcess] Reactive auto-swap enabled');
+
+            const currentProfileId = rateLimitDetection.profileId;
+            const bestProfile = profileManager.getBestAvailableProfile(currentProfileId);
+
+            if (bestProfile) {
+              console.log('[spawnProcess] Reactive swap to:', bestProfile.name);
+
+              // Switch active profile
+              profileManager.setActiveProfile(bestProfile.id);
+
+              // Emit swap info (for modal)
+              const source = processType === 'spec-creation' ? 'task' : 'task';
+              const rateLimitInfo = createSDKRateLimitInfo(source, rateLimitDetection, {
+                taskId
+              });
+              rateLimitInfo.wasAutoSwapped = true;
+              rateLimitInfo.swappedToProfile = {
+                id: bestProfile.id,
+                name: bestProfile.name
+              };
+              rateLimitInfo.swapReason = 'reactive';
+              this.emitter.emit('sdk-rate-limit', rateLimitInfo);
+
+              // Restart task
+              this.emitter.emit('auto-swap-restart-task', taskId, bestProfile.id);
+              return;
+            }
+          }
+
+          // Fall back to manual modal (no auto-swap or no alternative profile)
+          const source = processType === 'spec-creation' ? 'task' : 'task';
          const rateLimitInfo = createSDKRateLimitInfo(source, rateLimitDetection, {
            taskId
          });
@@ -35,7 +35,8 @@ export class AgentQueueManager {
  startRoadmapGeneration(
    projectId: string,
    projectPath: string,
-    refresh: boolean = false
+    refresh: boolean = false,
+    enableCompetitorAnalysis: boolean = false
  ): void {
    const autoBuildSource = this.processManager.getAutoBuildSourcePath();

@@ -57,6 +58,11 @@ export class AgentQueueManager {
      args.push('--refresh');
    }

+    // Add competitor analysis flag if enabled
+    if (enableCompetitorAnalysis) {
+      args.push('--competitor-analysis');
+    }
+
    // Use projectId as taskId for roadmap operations
    this.spawnRoadmapProcess(projectId, projectPath, args);
  }
@@ -40,6 +40,7 @@ export interface IdeationConfig {
 export interface TaskExecutionOptions {
  parallel?: boolean;
  workers?: number;
+  baseBranch?: string;
 }

 export interface SpecCreationMetadata {
@@ -17,595 +17,32 @@
 * - To release: Create a GitHub release with tag (e.g., v1.2.0)
 */

-import { existsSync, mkdirSync, writeFileSync, readFileSync, rmSync, readdirSync, statSync, copyFileSync } from 'fs';
-import path from 'path';
-import { app } from 'electron';
-import https from 'https';
-import { createWriteStream } from 'fs';
-import { exec } from 'child_process';
-import { promisify } from 'util';
-
-const execAsync = promisify(exec);
-
-/**
- * GitHub repository configuration
- */
-const GITHUB_CONFIG = {
-  owner: 'AndyMik90',
-  repo: 'Auto-Claude',
-  autoBuildPath: 'auto-claude' // Path within repo where auto-claude lives
-};
-
-/**
- * GitHub Release API response (partial)
- */
-interface GitHubRelease {
-  tag_name: string;
-  name: string;
-  body: string;
-  tarball_url: string;
-  published_at: string;
-  prerelease: boolean;
-  draft: boolean;
-}
-
-// Cache for the latest release info (used by download)
-let cachedLatestRelease: GitHubRelease | null = null;
-
-/**
- * Result of checking for updates
- */
-export interface AutoBuildUpdateCheck {
-  updateAvailable: boolean;
-  currentVersion: string;
-  latestVersion?: string;
-  releaseNotes?: string;
-  error?: string;
-}
-
-/**
- * Result of applying an update
- */
-export interface AutoBuildUpdateResult {
-  success: boolean;
-  version?: string;
-  error?: string;
-}
-
-/**
- * Progress callback for download
- */
-export type UpdateProgressCallback = (progress: {
-  stage: 'checking' | 'downloading' | 'extracting' | 'complete' | 'error';
-  percent?: number;
-  message: string;
-}) => void;
-
-/**
- * Get the path to the bundled auto-claude source
- */
-export function getBundledSourcePath(): string {
-  // In production, use app resources
-  // In development, use the repo's auto-claude folder
-  if (app.isPackaged) {
-    return path.join(process.resourcesPath, 'auto-claude');
-  }
-
-  // Development mode - look for auto-claude in various locations
-  const possiblePaths = [
-    path.join(app.getAppPath(), '..', 'auto-claude'),
-    path.join(app.getAppPath(), '..', '..', 'auto-claude'),
-    path.join(process.cwd(), 'auto-claude'),
-    path.join(process.cwd(), '..', 'auto-claude')
-  ];
-
-  for (const p of possiblePaths) {
-    if (existsSync(p)) {
-      return p;
-    }
-  }
-
-  // Fallback
-  return path.join(app.getAppPath(), '..', 'auto-claude');
-}
-
-/**
- * Get the path for storing downloaded updates
- */
-function getUpdateCachePath(): string {
-  return path.join(app.getPath('userData'), 'auto-claude-updates');
-}
-
-/**
- * Get the current app/framework version
- * 
- * Uses app.getVersion() (from package.json) as the single source of truth.
- * Both the Electron app and auto-claude framework share the same version.
- */
-export function getBundledVersion(): string {
-  return app.getVersion();
-}
-
-/**
- * Fetch JSON from a URL using https
- */
-function fetchJson<T>(url: string): Promise<T> {
-  return new Promise((resolve, reject) => {
-    const request = https.get(url, {
-      headers: {
-        'User-Agent': 'Auto-Claude-UI',
-        'Accept': 'application/vnd.github.v3+json'
-      }
-    }, (response) => {
-      // Handle redirects
-      if (response.statusCode === 301 || response.statusCode === 302) {
-        const redirectUrl = response.headers.location;
-        if (redirectUrl) {
-          fetchJson<T>(redirectUrl).then(resolve).catch(reject);
-          return;
-        }
-      }
-
-      if (response.statusCode !== 200) {
-        reject(new Error(`HTTP ${response.statusCode}`));
-        return;
-      }
-
-      let data = '';
-      response.on('data', chunk => data += chunk);
-      response.on('end', () => {
-        try {
-          resolve(JSON.parse(data) as T);
-        } catch (e) {
-          reject(new Error('Failed to parse JSON response'));
-        }
-      });
-      response.on('error', reject);
-    });
-
-    request.on('error', reject);
-    request.setTimeout(10000, () => {
-      request.destroy();
-      reject(new Error('Request timeout'));
-    });
-  });
-}
-
-/**
- * Parse version from GitHub release tag
- * Handles tags like "v1.2.0", "1.2.0", "v1.2.0-beta"
- */
-function parseVersionFromTag(tag: string): string {
-  // Remove leading 'v' if present
-  return tag.replace(/^v/, '');
-}
-
-/**
- * Check GitHub Releases for the latest version
- */
-export async function checkForUpdates(): Promise<AutoBuildUpdateCheck> {
-  const currentVersion = getBundledVersion();
-
-  try {
-    // Fetch latest release from GitHub Releases API
-    const releaseUrl = `https://api.github.com/repos/${GITHUB_CONFIG.owner}/${GITHUB_CONFIG.repo}/releases/latest`;
-    const release = await fetchJson<GitHubRelease>(releaseUrl);
-
-    // Cache for download function
-    cachedLatestRelease = release;
-
-    // Parse version from tag (e.g., "v1.2.0" -> "1.2.0")
-    const latestVersion = parseVersionFromTag(release.tag_name);
-
-    // Compare versions
-    const updateAvailable = compareVersions(latestVersion, currentVersion) > 0;
-
-    return {
-      updateAvailable,
-      currentVersion,
-      latestVersion,
-      releaseNotes: release.body || undefined
-    };
-  } catch (error) {
-    // Clear cache on error
-    cachedLatestRelease = null;
-    
-    return {
-      updateAvailable: false,
-      currentVersion,
-      error: error instanceof Error ? error.message : 'Failed to check for updates'
-    };
-  }
-}
-
-/**
- * Compare semantic versions
- * Returns: 1 if a > b, -1 if a < b, 0 if equal
- */
-function compareVersions(a: string, b: string): number {
-  const partsA = a.split('.').map(Number);
-  const partsB = b.split('.').map(Number);
-
-  for (let i = 0; i < Math.max(partsA.length, partsB.length); i++) {
-    const numA = partsA[i] || 0;
-    const numB = partsB[i] || 0;
-
-    if (numA > numB) return 1;
-    if (numA < numB) return -1;
-  }
-
-  return 0;
-}
-
-/**
- * Download a file with progress tracking
- */
-function downloadFile(
-  url: string,
-  destPath: string,
-  onProgress?: (percent: number) => void
-): Promise<void> {
-  return new Promise((resolve, reject) => {
-    const file = createWriteStream(destPath);
-
-    const request = https.get(url, {
-      headers: {
-        'User-Agent': 'Auto-Claude-UI',
-        'Accept': 'application/octet-stream'
-      }
-    }, (response) => {
-      // Handle redirects
-      if (response.statusCode === 301 || response.statusCode === 302) {
-        file.close();
-        const redirectUrl = response.headers.location;
-        if (redirectUrl) {
-          downloadFile(redirectUrl, destPath, onProgress).then(resolve).catch(reject);
-          return;
-        }
-      }
-
-      if (response.statusCode !== 200) {
-        file.close();
-        reject(new Error(`HTTP ${response.statusCode}`));
-        return;
-      }
-
-      const totalSize = parseInt(response.headers['content-length'] || '0', 10);
-      let downloadedSize = 0;
-
-      response.on('data', (chunk) => {
-        downloadedSize += chunk.length;
-        if (totalSize > 0 && onProgress) {
-          onProgress(Math.round((downloadedSize / totalSize) * 100));
-        }
-      });
-
-      response.pipe(file);
-
-      file.on('finish', () => {
-        file.close();
-        resolve();
-      });
-
-      file.on('error', (err) => {
-        file.close();
-        reject(err);
-      });
-    });
-
-    request.on('error', (err) => {
-      file.close();
-      reject(err);
-    });
-
-    request.setTimeout(60000, () => {
-      request.destroy();
-      reject(new Error('Download timeout'));
-    });
-  });
-}
-
-/**
- * Download and apply the latest auto-claude update from GitHub Releases
- *
- * Note: In production, this updates the bundled source in userData.
- * For packaged apps, we can't modify resourcesPath directly,
- * so we use a "source override" system.
- */
-export async function downloadAndApplyUpdate(
-  onProgress?: UpdateProgressCallback
-): Promise<AutoBuildUpdateResult> {
-  const cachePath = getUpdateCachePath();
-
-  try {
-    onProgress?.({
-      stage: 'checking',
-      message: 'Fetching release info...'
-    });
-
-    // Ensure cache directory exists
-    if (!existsSync(cachePath)) {
-      mkdirSync(cachePath, { recursive: true });
-    }
-
-    // Get release info (use cache or fetch fresh)
-    let release = cachedLatestRelease;
-    if (!release) {
-      const releaseUrl = `https://api.github.com/repos/${GITHUB_CONFIG.owner}/${GITHUB_CONFIG.repo}/releases/latest`;
-      release = await fetchJson<GitHubRelease>(releaseUrl);
-      cachedLatestRelease = release;
-    }
-
-    // Use the release tarball URL
-    const tarballUrl = release.tarball_url;
-    const releaseVersion = parseVersionFromTag(release.tag_name);
-
-    const tarballPath = path.join(cachePath, 'auto-claude-update.tar.gz');
-    const extractPath = path.join(cachePath, 'extracted');
-
-    // Clean up previous extraction
-    if (existsSync(extractPath)) {
-      rmSync(extractPath, { recursive: true, force: true });
-    }
-    mkdirSync(extractPath, { recursive: true });
-
-    onProgress?.({
-      stage: 'downloading',
-      percent: 0,
-      message: 'Downloading update...'
-    });
-
-    // Download the tarball
-    await downloadFile(tarballUrl, tarballPath, (percent) => {
-      onProgress?.({
-        stage: 'downloading',
-        percent,
-        message: `Downloading... ${percent}%`
-      });
-    });
-
-    onProgress?.({
-      stage: 'extracting',
-      message: 'Extracting update...'
-    });
-
-    // Extract the tarball
-    await extractTarball(tarballPath, extractPath);
-
-    // Find the auto-claude folder in extracted content
-    // GitHub tarballs have a root folder like "owner-repo-hash/"
-    const extractedDirs = readdirSync(extractPath);
-    if (extractedDirs.length === 0) {
-      throw new Error('Empty tarball');
-    }
-
-    const rootDir = path.join(extractPath, extractedDirs[0]);
-    const autoBuildSource = path.join(rootDir, GITHUB_CONFIG.autoBuildPath);
-
-    if (!existsSync(autoBuildSource)) {
-      throw new Error('auto-claude folder not found in download');
-    }
-
-    // Determine where to install the update
-    let targetPath: string;
-
-    if (app.isPackaged) {
-      // For packaged apps, store in userData as a source override
-      targetPath = path.join(app.getPath('userData'), 'auto-claude-source');
-    } else {
-      // In development, update the actual source
-      targetPath = getBundledSourcePath();
-    }
-
-    // Backup existing source (if in dev mode)
-    const backupPath = path.join(cachePath, 'backup');
-    if (!app.isPackaged && existsSync(targetPath)) {
-      if (existsSync(backupPath)) {
-        rmSync(backupPath, { recursive: true, force: true });
-      }
-      // Simple copy for backup
-      copyDirectoryRecursive(targetPath, backupPath);
-    }
-
-    // Copy new source to target
-    if (existsSync(targetPath)) {
-      // Clean target but preserve certain files
-      const preserveFiles = ['.env', 'specs'];
-      const preservedContent: Record<string, Buffer> = {};
-
-      for (const file of preserveFiles) {
-        const filePath = path.join(targetPath, file);
-        if (existsSync(filePath)) {
-          if (statSync(filePath).isDirectory()) {
-            // Skip directories for now - they'll be preserved by copyDirectoryRecursive
-          } else {
-            preservedContent[file] = readFileSync(filePath);
-          }
-        }
-      }
-
-      // Remove old files except preserved
-      const items = readdirSync(targetPath);
-      for (const item of items) {
-        if (!preserveFiles.includes(item)) {
-          rmSync(path.join(targetPath, item), { recursive: true, force: true });
-        }
-      }
-
-      // Copy new files
-      copyDirectoryRecursive(autoBuildSource, targetPath, true);
-
-      // Restore preserved files that might have been overwritten
-      for (const [file, content] of Object.entries(preservedContent)) {
-        writeFileSync(path.join(targetPath, file), content);
-      }
-    } else {
-      mkdirSync(targetPath, { recursive: true });
-      copyDirectoryRecursive(autoBuildSource, targetPath, false);
-    }
-
-    // Use the release version we already have
-    const newVersion = releaseVersion;
-
-    // Write update metadata
-    const metadataPath = path.join(targetPath, '.update-metadata.json');
-    writeFileSync(metadataPath, JSON.stringify({
-      version: newVersion,
-      updatedAt: new Date().toISOString(),
-      source: 'github-release',
-      releaseTag: release.tag_name,
-      releaseName: release.name
-    }, null, 2));
-
-    // Clear the cache after successful update
-    cachedLatestRelease = null;
-
-    // Cleanup
-    rmSync(tarballPath, { force: true });
-    rmSync(extractPath, { recursive: true, force: true });
-
-    onProgress?.({
-      stage: 'complete',
-      message: `Updated to version ${newVersion}`
-    });
-
-    return {
-      success: true,
-      version: newVersion
-    };
-  } catch (error) {
-    onProgress?.({
-      stage: 'error',
-      message: error instanceof Error ? error.message : 'Update failed'
-    });
-
-    return {
-      success: false,
-      error: error instanceof Error ? error.message : 'Unknown error'
-    };
-  }
-}
-
-/**
- * Extract a .tar.gz file
- * Uses system tar command on Unix or PowerShell on Windows
- */
-async function extractTarball(tarballPath: string, destPath: string): Promise<void> {
-  try {
-    if (process.platform === 'win32') {
-      // On Windows, try multiple approaches:
-      // 1. Modern Windows 10/11 has built-in tar
-      // 2. Fall back to PowerShell's Expand-Archive for .zip (but .tar.gz needs tar)
-      // 3. Use PowerShell to extract via .NET
-      try {
-        // First try native tar (available on Windows 10 1803+)
-        await execAsync(`tar -xzf "${tarballPath}" -C "${destPath}"`);
-      } catch {
-        // Fall back to PowerShell with .NET for gzip decompression
-        // This is more complex but works on older Windows versions
-        const psScript = `
-          $tarball = "${tarballPath.replace(/\\/g, '\\\\')}"
-          $dest = "${destPath.replace(/\\/g, '\\\\')}"
-          $tempTar = Join-Path $env:TEMP "auto-claude-update.tar"
-
-          # Decompress gzip
-          $gzipStream = [System.IO.File]::OpenRead($tarball)
-          $decompressedStream = New-Object System.IO.Compression.GZipStream($gzipStream, [System.IO.Compression.CompressionMode]::Decompress)
-          $tarStream = [System.IO.File]::Create($tempTar)
-          $decompressedStream.CopyTo($tarStream)
-          $tarStream.Close()
-          $decompressedStream.Close()
-          $gzipStream.Close()
-
-          # Extract tar using tar command (should work even if gzip didn't)
-          tar -xf $tempTar -C $dest
-          Remove-Item $tempTar -Force
-        `;
-        await execAsync(`powershell -NoProfile -Command "${psScript.replace(/"/g, '\\"').replace(/\n/g, ' ')}"`);
-      }
-    } else {
-      // Unix systems - use native tar
-      await execAsync(`tar -xzf "${tarballPath}" -C "${destPath}"`);
-    }
-  } catch (error) {
-    throw new Error(`Failed to extract tarball: ${error instanceof Error ? error.message : 'Unknown error'}`);
-  }
-}
-
-/**
- * Recursively copy directory
- */
-function copyDirectoryRecursive(
-  src: string,
-  dest: string,
-  preserveExisting: boolean = false
-): void {
-  if (!existsSync(dest)) {
-    mkdirSync(dest, { recursive: true });
-  }
-
-  const entries = readdirSync(src, { withFileTypes: true });
-
-  for (const entry of entries) {
-    const srcPath = path.join(src, entry.name);
-    const destPath = path.join(dest, entry.name);
-
-    // Skip certain files/directories
-    if (['__pycache__', '.DS_Store', '.git', 'specs', '.env'].includes(entry.name)) {
-      continue;
-    }
-
-    // In preserve mode, skip existing files
-    if (preserveExisting && existsSync(destPath)) {
-      if (entry.isDirectory()) {
-        copyDirectoryRecursive(srcPath, destPath, preserveExisting);
-      }
-      continue;
-    }
-
-    if (entry.isDirectory()) {
-      copyDirectoryRecursive(srcPath, destPath, preserveExisting);
-    } else {
-      copyFileSync(srcPath, destPath);
-    }
-  }
-}
-
-/**
- * Get the effective source path (considers override from updates)
- */
-export function getEffectiveSourcePath(): string {
-  if (app.isPackaged) {
-    // Check for user-updated source first
-    const overridePath = path.join(app.getPath('userData'), 'auto-claude-source');
-    if (existsSync(overridePath)) {
-      return overridePath;
-    }
-  }
-
-  return getBundledSourcePath();
-}
-
-/**
- * Check if there's a pending source update that requires restart
- */
-export function hasPendingSourceUpdate(): boolean {
-  if (!app.isPackaged) {
-    return false;
-  }
-
-  const overridePath = path.join(app.getPath('userData'), 'auto-claude-source');
-  const metadataPath = path.join(overridePath, '.update-metadata.json');
-
-  if (!existsSync(metadataPath)) {
-    return false;
-  }
-
-  try {
-    const metadata = JSON.parse(readFileSync(metadataPath, 'utf-8'));
-    const bundledVersion = getBundledVersion();
-    return compareVersions(metadata.version, bundledVersion) > 0;
-  } catch {
-    return false;
-  }
-}
+// Export types
+export type {
+  GitHubRelease,
+  AutoBuildUpdateCheck,
+  AutoBuildUpdateResult,
+  UpdateProgressCallback,
+  UpdateMetadata
+} from './updater/types';
+
+// Export version management
+export { getBundledVersion } from './updater/version-manager';
+
+// Export path resolution
+export {
+  getBundledSourcePath,
+  getEffectiveSourcePath
+} from './updater/path-resolver';
+
+// Export update checking
+export { checkForUpdates } from './updater/update-checker';
+
+// Export update installation
+export { downloadAndApplyUpdate } from './updater/update-installer';
+
+// Export update status
+export {
+  hasPendingSourceUpdate,
+  getUpdateMetadata
+} from './updater/update-status';
@@ -17,6 +17,7 @@ import type {
  GitTagInfo
 } from '../../shared/types';
 import { ChangelogGenerator } from './generator';
+import { VersionSuggester } from './version-suggester';
 import { parseExistingChangelog } from './parser';
 import {
  getBranches,
@@ -38,6 +39,7 @@ export class ChangelogService extends EventEmitter {
  private cachedEnv: Record<string, string> | null = null;
  private debugEnabled: boolean | null = null;
  private generator: ChangelogGenerator | null = null;
+  private versionSuggester: VersionSuggester | null = null;

  constructor() {
    super();
@@ -240,6 +242,32 @@ export class ChangelogService extends EventEmitter {
    return this.generator;
  }

+  /**
+   * Get or create the version suggester instance
+   */
+  private getVersionSuggester(): VersionSuggester {
+    if (!this.versionSuggester) {
+      const autoBuildSource = this.getAutoBuildSourcePath();
+      if (!autoBuildSource) {
+        throw new Error('Auto-build source path not found');
+      }
+
+      // Verify claude CLI is available
+      if (this.claudePath !== 'claude' && !existsSync(this.claudePath)) {
+        throw new Error(`Claude CLI not found. Please ensure Claude Code is installed. Looked for: ${this.claudePath}`);
+      }
+
+      this.versionSuggester = new VersionSuggester(
+        this.pythonPath,
+        this.claudePath,
+        autoBuildSource,
+        this.isDebugEnabled()
+      );
+    }
+
+    return this.versionSuggester;
+  }
+
  // ============================================
  // Task Management
  // ============================================
@@ -432,7 +460,7 @@ export class ChangelogService extends EventEmitter {
  }

  /**
-   * Suggest next version based on task types
+   * Suggest next version based on task types (rule-based)
   */
  suggestVersion(specs: TaskSpecContent[], currentVersion?: string): string {
    // Default starting version
@@ -445,7 +473,7 @@ export class ChangelogService extends EventEmitter {
      return '1.0.0';
    }

-    let [major, minor, patch] = parts;
+    const [major, minor, patch] = parts;

    // Analyze specs for version increment decision
    let hasBreakingChanges = false;
@@ -473,6 +501,46 @@ export class ChangelogService extends EventEmitter {
      return `${major}.${minor}.${patch + 1}`;
    }
  }
+
+  /**
+   * Suggest version using AI analysis of git commits
+   */
+  async suggestVersionFromCommits(
+    projectPath: string,
+    commits: import('../../shared/types').GitCommit[],
+    currentVersion?: string
+  ): Promise<{ version: string; reason: string }> {
+    try {
+      // Default starting version
+      if (!currentVersion) {
+        return { version: '1.0.0', reason: 'Initial version' };
+      }
+
+      const parts = currentVersion.split('.').map(Number);
+      if (parts.length !== 3 || parts.some(isNaN)) {
+        return { version: '1.0.0', reason: 'Invalid current version, resetting to 1.0.0' };
+      }
+
+      // Use AI to analyze commits and suggest version bump
+      const suggester = this.getVersionSuggester();
+      const suggestion = await suggester.suggestVersionBump(commits, currentVersion);
+
+      this.debug('AI version suggestion', suggestion);
+
+      return {
+        version: suggestion.version,
+        reason: suggestion.reason
+      };
+    } catch (error) {
+      this.debug('Error in AI version suggestion, falling back to patch bump', error);
+      // Fallback to patch bump if AI fails
+      const [major, minor, patch] = (currentVersion || '1.0.0').split('.').map(Number);
+      return {
+        version: `${major}.${minor}.${patch + 1}`,
+        reason: 'Patch version bump (AI analysis failed)'
+      };
+    }
+  }
 }

 // Export singleton instance
@@ -31,16 +31,25 @@ const FORMAT_TEMPLATES = {
 **Bug Fixes:**
 - [List fixes]`,

-  'github-release': (version: string) => `## What's New in v${version}
+  'github-release': (version: string, date: string) => `## ${version} - ${date}

 ### New Features
- **Feature Name**: Description
+
+- Feature description

 ### Improvements
- Description
+
+- Improvement description

 ### Bug Fixes
- Fixed [issue]`
+
+- Fix description
+
+---
+
+## What's Changed
+
+- type: description by @contributor in commit-hash`
 };

 /**
@@ -52,6 +61,74 @@ const AUDIENCE_INSTRUCTIONS = {
  'marketing': 'You are a marketing specialist writing release notes. Focus on outcomes and user impact with compelling language.'
 };

+/**
+ * Get emoji usage instructions based on level and format
+ */
+function getEmojiInstructions(emojiLevel?: string, format?: string): string {
+  if (!emojiLevel || emojiLevel === 'none') {
+    return '';
+  }
+
+  // GitHub Release format uses specific emoji style matching Gemini CLI pattern
+  if (format === 'github-release') {
+    const githubInstructions: Record<string, string> = {
+      'little': `Add emojis ONLY to section headings. Use these specific emoji-heading pairs:
+- "### ✨ New Features"
+- "### 🛠️ Improvements"
+- "### 🐛 Bug Fixes"
+- "### 📚 Documentation"
+- "### 🔧 Other Changes"
+Do NOT add emojis to individual line items.`,
+      'medium': `Add emojis to section headings AND to notable/important items only.
+Section headings MUST use these specific emoji-heading pairs:
+- "### ✨ New Features"
+- "### 🛠️ Improvements"
+- "### 🐛 Bug Fixes"
+- "### 📚 Documentation"
+- "### 🔧 Other Changes"
+Add emojis to 2-3 highlighted items per section that are particularly significant.`,
+      'high': `Add emojis to section headings AND every line item.
+Section headings MUST use these specific emoji-heading pairs:
+- "### ✨ New Features"
+- "### 🛠️ Improvements"
+- "### 🐛 Bug Fixes"
+- "### 📚 Documentation"
+- "### 🔧 Other Changes"
+Every line item should start with a contextual emoji.`
+    };
+    return githubInstructions[emojiLevel] || '';
+  }
+
+  // Default instructions for other formats
+  const instructions: Record<string, string> = {
+    'little': `Add emojis ONLY to section headings. Each heading should have one contextual emoji at the start.
+Examples:
+- "### ✨ New Features" or "### 🚀 New Features"
+- "### 🐛 Bug Fixes"
+- "### 🔧 Improvements" or "### ⚡ Improvements"
+- "### 📚 Documentation"
+Do NOT add emojis to individual line items.`,
+    'medium': `Add emojis to section headings AND to notable/important items only.
+Section headings should have one emoji (e.g., "### ✨ New Features", "### 🐛 Bug Fixes").
+Add emojis to 2-3 highlighted items per section that are particularly significant.
+Examples of highlighted items:
+- "- 🎉 **Major Feature**: Description"
+- "- 🔒 **Security Fix**: Description"
+Most regular line items should NOT have emojis.`,
+    'high': `Add emojis to section headings AND every line item for maximum visual appeal.
+Section headings: "### ✨ New Features", "### 🐛 Bug Fixes", "### ⚡ Improvements"
+Every line item should start with a contextual emoji:
+- "- ✨ Added new feature..."
+- "- 🐛 Fixed bug where..."
+- "- 🔧 Improved performance of..."
+- "- 📝 Updated documentation for..."
+- "- 🎨 Refined UI styling..."
+Use diverse, contextually appropriate emojis for each item.`
+  };
+
+  return instructions[emojiLevel] || '';
+}
+
 /**
 * Build changelog prompt from task specs
 */
@@ -61,6 +138,7 @@ export function buildChangelogPrompt(
 ): string {
  const audienceInstruction = AUDIENCE_INSTRUCTIONS[request.audience];
  const formatInstruction = FORMAT_TEMPLATES[request.format](request.version, request.date);
+  const emojiInstruction = getEmojiInstructions(request.emojiLevel, request.format);

  // Build CONCISE task summaries (key to avoiding timeout)
  const taskSummaries = specs.map(spec => {
@@ -82,10 +160,32 @@ export function buildChangelogPrompt(
    return parts.join('');
  }).join('\n');

+  // Format-specific instructions for tasks mode
+  let formatSpecificInstructions = '';
+  if (request.format === 'github-release') {
+    formatSpecificInstructions = `
+For GitHub Release format:
+
+RELEASE TITLE (CRITICAL):
+- First, analyze all completed tasks to identify the main theme or focus of this release
+- Create a concise, descriptive title (2-5 words) that captures what this release is about
+- Examples of good titles:
+  * "Improved Terminal Experience" (for terminal-related improvements)
+  * "Enhanced Security Features" (for security updates)
+  * "UI/UX Refinements" (for interface changes)
+  * "Agent Performance Boost" (for performance improvements)
+- The version header MUST be: "## ${request.version} - [Your Thematic Title]"
+- Focus on the USER BENEFIT or FUNCTIONAL AREA, not technical implementation details
+- The title should be what the release is "about" in layman's terms
+`;
+  }
+
  return `${audienceInstruction}

 Format:
 ${formatInstruction}
+${emojiInstruction ? `\nEmoji Usage:\n${emojiInstruction}` : ''}
+${formatSpecificInstructions}

 Completed tasks:
 ${taskSummaries}
@@ -104,19 +204,22 @@ export function buildGitPrompt(
 ): string {
  const audienceInstruction = AUDIENCE_INSTRUCTIONS[request.audience];
  const formatInstruction = FORMAT_TEMPLATES[request.format](request.version, request.date);
+  const emojiInstruction = getEmojiInstructions(request.emojiLevel, request.format);

  // Format commits for the prompt
-  // Group by conventional commit type if detected
+  // Include author info for github-release format
  const commitLines = commits.map(commit => {
    const hash = commit.hash;
    const subject = commit.subject;
+    const author = commit.author;
+
    // Detect conventional commit format: type(scope): message
    const conventionalMatch = subject.match(/^(\w+)(?:\(([^)]+)\))?:\s*(.+)$/);
    if (conventionalMatch) {
      const [, type, scope, message] = conventionalMatch;
-      return `- ${hash}: [${type}${scope ? `/${scope}` : ''}] ${message}`;
+      return `- ${hash} | ${type}${scope ? `(${scope})` : ''}: ${message} | by ${author}`;
    }
-    return `- ${hash}: ${subject}`;
+    return `- ${hash} | ${subject} | by ${author}`;
  }).join('\n');

  // Add context about branch/range if available
@@ -137,6 +240,43 @@ export function buildGitPrompt(
    }
  }

+  // Format-specific instructions
+  let formatSpecificInstructions = '';
+  if (request.format === 'github-release') {
+    formatSpecificInstructions = `
+For GitHub Release format, you MUST follow this structure:
+
+RELEASE TITLE (CRITICAL):
+- First, analyze all commits to identify the main theme or focus of this release
+- Create a concise, descriptive title (2-5 words) that captures what this release is about
+- Examples of good titles:
+  * "Improved Terminal Experience" (for terminal-related improvements)
+  * "Enhanced Security Features" (for security updates)
+  * "Performance Optimizations" (for speed improvements)
+  * "UI/UX Refinements" (for interface changes)
+  * "Agent System Overhaul" (for major architectural changes)
+  * "Build Pipeline Enhancements" (for CI/CD improvements)
+- The version header MUST be: "## ${request.version} - [Your Thematic Title]"
+- Focus on the USER BENEFIT or FUNCTIONAL AREA, not technical implementation details
+- The title should be what the release is "about" in layman's terms
+
+PART 1 - Categorized changes (summarized):
+- Use category sections: New Features, Improvements, Bug Fixes, Documentation, Other Changes
+- ONLY include sections that have actual changes - skip empty sections entirely
+- Add a blank line between each bullet point for cleaner formatting
+- Summarize and group related commits into clear, readable descriptions
+- Do NOT include commit hashes in this section
+
+PART 2 - "What's Changed" (raw commit list):
+- Add a horizontal rule (---) before this section
+- List each commit in format: "- type: description by @author in hash"
+- Example: "- fix: upgrade react to 19.2.3 by @douxc in abc1234"
+- Example: "- feat: add dark mode support by @contributor in def5678"
+- Include the commit type prefix (feat:, fix:, docs:, etc.)
+- Show the author name with @ prefix
+- Show the short commit hash at the end`;
+  }
+
  return `${audienceInstruction}

 ${sourceContext}
@@ -144,24 +284,24 @@ ${sourceContext}
 Generate a changelog from these git commits. Group related changes together and categorize them appropriately.

 Conventional commit types to recognize:
- feat/feature: New features → Added section
- fix/bugfix: Bug fixes → Fixed section
- docs: Documentation → Changed or separate Documentation section
- style: Styling/formatting → Changed section
- refactor: Code refactoring → Changed section
- perf: Performance → Changed or Performance section
+- feat/feature: New features → New Features section
+- fix/bugfix: Bug fixes → Bug Fixes section
+- docs: Documentation → Documentation section
+- style/refactor/perf: Improvements → Improvements section
+- chore/build/ci: Other changes → Other Changes section (usually omit unless significant)
 - test: Tests → (usually omit unless significant)
- chore: Maintenance → (usually omit unless significant)
+${formatSpecificInstructions}

 Format:
 ${formatInstruction}
+${emojiInstruction ? `\nEmoji Usage:\n${emojiInstruction}` : ''}

 Git commits (${commits.length} total):
 ${commitLines}

 ${request.customInstructions ? `Note: ${request.customInstructions}` : ''}

-CRITICAL: Output ONLY the raw changelog content. Do NOT include ANY introductory text, analysis, or explanation. Start directly with the changelog heading (## or #). No "Here's the changelog" or similar phrases. Intelligently group and summarize related commits - don't just list each commit individually.`;
+CRITICAL: Output ONLY the raw changelog content. Do NOT include ANY introductory text, analysis, or explanation. Start directly with the changelog heading (## or #). No "Here's the changelog" or similar phrases. Intelligently group and summarize related commits - don't just list each commit individually. Only include sections that have actual changes.`;
 }

 /**
@@ -4,6 +4,7 @@
 * Architecture:
 * - changelog-service.ts: Main service facade (orchestrates all operations)
 * - generator.ts: AI-powered changelog generation
+ * - version-suggester.ts: AI-powered version bump suggestions
 * - parser.ts: Changelog and spec parsing logic
 * - formatter.ts: Prompt building and formatting
 * - git-integration.ts: Git operations (branches, tags, commits)
@@ -12,6 +13,7 @@

 export { ChangelogService, changelogService } from './changelog-service';
 export { ChangelogGenerator } from './generator';
+export { VersionSuggester } from './version-suggester';
 export * from './parser';
 export * from './formatter';
 export * from './git-integration';
@@ -0,0 +1,245 @@
+import { spawn } from 'child_process';
+import * as path from 'path';
+import * as os from 'os';
+import type { GitCommit } from '../../shared/types';
+import { getProfileEnv } from '../rate-limit-detector';
+
+interface VersionSuggestion {
+  version: string;
+  reason: string;
+  bumpType: 'major' | 'minor' | 'patch';
+}
+
+/**
+ * AI-powered version bump suggester using Claude SDK with haiku model
+ * Analyzes commits to intelligently suggest semantic version bumps
+ */
+export class VersionSuggester {
+  private debugEnabled: boolean;
+
+  constructor(
+    private pythonPath: string,
+    private claudePath: string,
+    private autoBuildSourcePath: string,
+    debugEnabled: boolean
+  ) {
+    this.debugEnabled = debugEnabled;
+  }
+
+  private debug(...args: unknown[]): void {
+    if (this.debugEnabled) {
+      console.log('[VersionSuggester]', ...args);
+    }
+  }
+
+  /**
+   * Suggest version bump using AI analysis of commits
+   */
+  async suggestVersionBump(
+    commits: GitCommit[],
+    currentVersion: string
+  ): Promise<VersionSuggestion> {
+    this.debug('suggestVersionBump called', {
+      commitCount: commits.length,
+      currentVersion
+    });
+
+    // Build prompt for Claude to analyze commits
+    const prompt = this.buildPrompt(commits, currentVersion);
+    const script = this.createAnalysisScript(prompt);
+
+    // Build environment
+    const spawnEnv = this.buildSpawnEnvironment();
+
+    return new Promise((resolve, reject) => {
+      const childProcess = spawn(this.pythonPath, ['-c', script], {
+        cwd: this.autoBuildSourcePath,
+        env: spawnEnv
+      });
+
+      let output = '';
+      let errorOutput = '';
+
+      childProcess.stdout?.on('data', (data: Buffer) => {
+        output += data.toString();
+      });
+
+      childProcess.stderr?.on('data', (data: Buffer) => {
+        errorOutput += data.toString();
+      });
+
+      childProcess.on('exit', (code: number | null) => {
+        if (code === 0 && output.trim()) {
+          try {
+            const result = this.parseAIResponse(output.trim(), currentVersion);
+            this.debug('AI suggestion parsed', result);
+            resolve(result);
+          } catch (error) {
+            this.debug('Failed to parse AI response', error);
+            // Fallback to simple bump
+            resolve(this.fallbackSuggestion(currentVersion));
+          }
+        } else {
+          this.debug('AI analysis failed', { code, error: errorOutput });
+          // Fallback to simple bump
+          resolve(this.fallbackSuggestion(currentVersion));
+        }
+      });
+
+      childProcess.on('error', (err: Error) => {
+        this.debug('Process error', err);
+        resolve(this.fallbackSuggestion(currentVersion));
+      });
+    });
+  }
+
+  /**
+   * Build prompt for Claude to analyze commits and suggest version bump
+   */
+  private buildPrompt(commits: GitCommit[], currentVersion: string): string {
+    const commitSummary = commits
+      .map((c, i) => `${i + 1}. ${c.hash} - ${c.subject}`)
+      .join('\n');
+
+    return `You are a semantic versioning expert analyzing git commits to suggest the appropriate version bump.
+
+Current version: ${currentVersion}
+
+Analyze these ${commits.length} commits and determine the appropriate semantic version bump:
+
+${commitSummary}
+
+Consider:
+- MAJOR (X.0.0): Breaking changes, API changes, removed features, architectural changes
+- MINOR (0.X.0): New features, enhancements, additions that maintain backward compatibility
+- PATCH (0.0.X): Bug fixes, small tweaks, documentation updates, refactoring without new features
+
+Respond with ONLY a JSON object in this exact format (no markdown, no extra text):
+{
+  "bumpType": "major|minor|patch",
+  "reason": "Brief explanation of the decision"
+}`;
+  }
+
+  /**
+   * Create Python script to run Claude analysis
+   */
+  private createAnalysisScript(prompt: string): string {
+    // Escape the prompt for Python string literal
+    const escapedPrompt = prompt
+      .replace(/\\/g, '\\\\')
+      .replace(/"/g, '\\"')
+      .replace(/\n/g, '\\n');
+
+    return `
+import subprocess
+import sys
+
+# Use haiku model for fast, cost-effective analysis
+prompt = "${escapedPrompt}"
+
+try:
+    result = subprocess.run(
+        ["${this.claudePath}", "chat", "--model", "haiku", "--prompt", prompt],
+        capture_output=True,
+        text=True,
+        check=True
+    )
+    print(result.stdout)
+except subprocess.CalledProcessError as e:
+    print(f"Error: {e.stderr}", file=sys.stderr)
+    sys.exit(1)
+except Exception as e:
+    print(f"Error: {str(e)}", file=sys.stderr)
+    sys.exit(1)
+`;
+  }
+
+  /**
+   * Parse AI response to extract version suggestion
+   */
+  private parseAIResponse(output: string, currentVersion: string): VersionSuggestion {
+    // Extract JSON from output (Claude might wrap it in markdown or other text)
+    const jsonMatch = output.match(/\{[\s\S]*"bumpType"[\s\S]*"reason"[\s\S]*\}/);
+    if (!jsonMatch) {
+      throw new Error('No JSON found in AI response');
+    }
+
+    const parsed = JSON.parse(jsonMatch[0]);
+    const bumpType = parsed.bumpType as 'major' | 'minor' | 'patch';
+    const reason = parsed.reason || 'AI analysis of commits';
+
+    // Calculate new version
+    const [major, minor, patch] = currentVersion.split('.').map(Number);
+
+    let newVersion: string;
+    switch (bumpType) {
+      case 'major':
+        newVersion = `${major + 1}.0.0`;
+        break;
+      case 'minor':
+        newVersion = `${major}.${minor + 1}.0`;
+        break;
+      case 'patch':
+      default:
+        newVersion = `${major}.${minor}.${patch + 1}`;
+        break;
+    }
+
+    return {
+      version: newVersion,
+      reason,
+      bumpType
+    };
+  }
+
+  /**
+   * Fallback suggestion if AI analysis fails
+   */
+  private fallbackSuggestion(currentVersion: string): VersionSuggestion {
+    const [major, minor, patch] = currentVersion.split('.').map(Number);
+    return {
+      version: `${major}.${minor}.${patch + 1}`,
+      reason: 'Patch version bump (default)',
+      bumpType: 'patch'
+    };
+  }
+
+  /**
+   * Build spawn environment with proper PATH and auth settings
+   */
+  private buildSpawnEnvironment(): Record<string, string> {
+    const homeDir = os.homedir();
+    const isWindows = process.platform === 'win32';
+
+    // Build PATH with platform-appropriate separator and locations
+    const pathAdditions = isWindows
+      ? [
+          path.join(homeDir, 'AppData', 'Local', 'Programs', 'claude'),
+          path.join(homeDir, 'AppData', 'Roaming', 'npm'),
+          path.join(homeDir, '.local', 'bin'),
+          'C:\\Program Files\\Claude',
+          'C:\\Program Files (x86)\\Claude'
+        ]
+      : [
+          '/usr/local/bin',
+          '/opt/homebrew/bin',
+          path.join(homeDir, '.local', 'bin'),
+          path.join(homeDir, 'bin')
+        ];
+
+    // Get active Claude profile environment
+    const profileEnv = getProfileEnv();
+
+    const spawnEnv: Record<string, string> = {
+      ...process.env as Record<string, string>,
+      ...profileEnv,
+      ...(isWindows ? { USERPROFILE: homeDir } : { HOME: homeDir }),
+      USER: process.env.USER || process.env.USERNAME || 'user',
+      PATH: [process.env.PATH || '', ...pathAdditions].filter(Boolean).join(path.delimiter),
+      PYTHONUNBUFFERED: '1'
+    };
+
+    return spawnEnv;
+  }
+}
@@ -1,7 +1,19 @@
-import { app, safeStorage } from 'electron';
+/**
+ * Claude Profile Manager
+ * Main coordinator for multi-account profile management
+ *
+ * This class delegates to specialized modules:
+ * - token-encryption: OAuth token encryption/decryption
+ * - usage-parser: Usage data parsing and reset time calculations
+ * - rate-limit-manager: Rate limit event tracking
+ * - profile-storage: Disk persistence
+ * - profile-scorer: Profile availability scoring and auto-switch logic
+ * - profile-utils: Helper utilities
+ */
+
+import { app } from 'electron';
 import { join } from 'path';
-import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from 'fs';
-import { homedir } from 'os';
+import { existsSync, mkdirSync } from 'fs';
 import type {
  ClaudeProfile,
  ClaudeProfileSettings,
@@ -10,145 +22,33 @@ import type {
  ClaudeAutoSwitchSettings
 } from '../shared/types';

-const STORE_VERSION = 3;  // Bumped for encrypted token storage
-
-/**
- * Encrypt a token using the OS keychain (safeStorage API).
- * Returns base64-encoded encrypted data, or the raw token if encryption unavailable.
- */
-function encryptToken(token: string): string {
-  try {
-    if (safeStorage.isEncryptionAvailable()) {
-      const encrypted = safeStorage.encryptString(token);
-      // Prefix with 'enc:' to identify encrypted tokens
-      return 'enc:' + encrypted.toString('base64');
-    }
-  } catch (error) {
-    console.warn('[ClaudeProfileManager] Encryption not available, storing token as-is:', error);
-  }
-  return token;
-}
-
-/**
- * Decrypt a token. Handles both encrypted (enc:...) and legacy plain tokens.
- */
-function decryptToken(storedToken: string): string {
-  try {
-    if (storedToken.startsWith('enc:') && safeStorage.isEncryptionAvailable()) {
-      const encryptedData = Buffer.from(storedToken.slice(4), 'base64');
-      return safeStorage.decryptString(encryptedData);
-    }
-  } catch (error) {
-    console.error('[ClaudeProfileManager] Failed to decrypt token:', error);
-    return ''; // Return empty string on decryption failure
-  }
-  // Return as-is for legacy unencrypted tokens
-  return storedToken;
-}
-
-/**
- * Internal storage format for Claude profiles
- */
-interface ProfileStoreData {
-  version: number;
-  profiles: ClaudeProfile[];
-  activeProfileId: string;
-  autoSwitch?: ClaudeAutoSwitchSettings;
-}
-
-/**
- * Default Claude config directory
- */
-const DEFAULT_CLAUDE_CONFIG_DIR = join(homedir(), '.claude');
-
-/**
- * Default profiles directory for additional accounts
- */
-const CLAUDE_PROFILES_DIR = join(homedir(), '.claude-profiles');
-
-/**
- * Default auto-switch settings
- */
-const DEFAULT_AUTO_SWITCH_SETTINGS: ClaudeAutoSwitchSettings = {
-  enabled: false,
-  sessionThreshold: 85,  // Consider switching at 85% session usage
-  weeklyThreshold: 90,   // Consider switching at 90% weekly usage
-  autoSwitchOnRateLimit: false,  // Prompt user by default
-  usageCheckInterval: 0  // Disabled by default (in ms, e.g., 300000 = 5 min)
-};
-
-/**
- * Regex to parse /usage command output
- * Matches patterns like: "████▌ 9% used" and "Resets Nov 1, 10:59am (America/Sao_Paulo)"
- */
-const USAGE_PERCENT_PATTERN = /(\d+)%\s*used/i;
-const USAGE_RESET_PATTERN = /Resets?\s+(.+?)(?:\s*$|\n)/i;
-
-/**
- * Parse a rate limit reset time string and estimate when it resets
- * Examples: "Dec 17 at 6am (Europe/Oslo)", "11:59pm (America/Sao_Paulo)", "Nov 1, 10:59am"
- */
-function parseResetTime(resetTimeStr: string): Date {
-  const now = new Date();
-
-  // Try to parse various formats
-  // Format: "Dec 17 at 6am (Europe/Oslo)" or "Nov 1, 10:59am"
-  const dateMatch = resetTimeStr.match(/([A-Za-z]+)\s+(\d+)(?:,|\s+at)?\s*(\d+)?:?(\d+)?(am|pm)?/i);
-  if (dateMatch) {
-    const [, month, day, hour = '0', minute = '0', ampm = ''] = dateMatch;
-    const monthMap: Record<string, number> = {
-      'jan': 0, 'feb': 1, 'mar': 2, 'apr': 3, 'may': 4, 'jun': 5,
-      'jul': 6, 'aug': 7, 'sep': 8, 'oct': 9, 'nov': 10, 'dec': 11
-    };
-    const monthNum = monthMap[month.toLowerCase()] ?? now.getMonth();
-    let hourNum = parseInt(hour, 10);
-    if (ampm.toLowerCase() === 'pm' && hourNum < 12) hourNum += 12;
-    if (ampm.toLowerCase() === 'am' && hourNum === 12) hourNum = 0;
-
-    const resetDate = new Date(now.getFullYear(), monthNum, parseInt(day, 10), hourNum, parseInt(minute, 10));
-    // If the date is in the past, assume next year
-    if (resetDate < now) {
-      resetDate.setFullYear(resetDate.getFullYear() + 1);
-    }
-    return resetDate;
-  }
-
-  // Format: "11:59pm" (today or tomorrow)
-  const timeOnlyMatch = resetTimeStr.match(/(\d+):?(\d+)?\s*(am|pm)/i);
-  if (timeOnlyMatch) {
-    const [, hour, minute = '0', ampm] = timeOnlyMatch;
-    let hourNum = parseInt(hour, 10);
-    if (ampm.toLowerCase() === 'pm' && hourNum < 12) hourNum += 12;
-    if (ampm.toLowerCase() === 'am' && hourNum === 12) hourNum = 0;
-
-    const resetDate = new Date(now.getFullYear(), now.getMonth(), now.getDate(), hourNum, parseInt(minute, 10));
-    // If the time is in the past, assume tomorrow
-    if (resetDate < now) {
-      resetDate.setDate(resetDate.getDate() + 1);
-    }
-    return resetDate;
-  }
-
-  // Fallback: assume 5 hours from now (session reset) or 7 days (weekly)
-  const isWeekly = resetTimeStr.toLowerCase().includes('week') ||
-    /[a-z]{3}\s+\d+/i.test(resetTimeStr);  // Has a date like "Dec 17"
-  if (isWeekly) {
-    return new Date(now.getTime() + 7 * 24 * 60 * 60 * 1000);
-  }
-  return new Date(now.getTime() + 5 * 60 * 60 * 1000);
-}
-
-/**
- * Determine if a rate limit is session-based or weekly based on reset time
- */
-function classifyRateLimitType(resetTimeStr: string): 'session' | 'weekly' {
-  // Weekly limits mention specific dates like "Dec 17" or "Nov 1"
-  // Session limits are typically just times like "11:59pm"
-  const hasDate = /[A-Za-z]{3}\s+\d+/i.test(resetTimeStr);
-  const hasWeeklyIndicator = resetTimeStr.toLowerCase().includes('week');
-
-  return (hasDate || hasWeeklyIndicator) ? 'weekly' : 'session';
-}
+// Module imports
+import { encryptToken, decryptToken } from './claude-profile/token-encryption';
+import { parseUsageOutput } from './claude-profile/usage-parser';
+import {
+  recordRateLimitEvent as recordRateLimitEventImpl,
+  isProfileRateLimited as isProfileRateLimitedImpl,
+  clearRateLimitEvents as clearRateLimitEventsImpl
+} from './claude-profile/rate-limit-manager';
+import {
+  loadProfileStore,
+  saveProfileStore,
+  ProfileStoreData,
+  DEFAULT_AUTO_SWITCH_SETTINGS
+} from './claude-profile/profile-storage';
+import {
+  getBestAvailableProfile,
+  shouldProactivelySwitch as shouldProactivelySwitchImpl,
+  getProfilesSortedByAvailability as getProfilesSortedByAvailabilityImpl
+} from './claude-profile/profile-scorer';
+import {
+  DEFAULT_CLAUDE_CONFIG_DIR,
+  generateProfileId as generateProfileIdImpl,
+  createProfileDirectory as createProfileDirectoryImpl,
+  isProfileAuthenticated as isProfileAuthenticatedImpl,
+  hasValidToken,
+  expandHomePath
+} from './claude-profile/profile-utils';

 /**
 * Manages Claude Code profiles for multi-account support.
@@ -176,39 +76,9 @@ export class ClaudeProfileManager {
   * Load profiles from disk
   */
  private load(): ProfileStoreData {
-    try {
-      if (existsSync(this.storePath)) {
-        const content = readFileSync(this.storePath, 'utf-8');
-        const data = JSON.parse(content);
-
-        // Handle version migration
-        if (data.version === 1) {
-          // Migrate v1 to v2: add usage and rateLimitEvents fields
-          data.version = STORE_VERSION;
-          data.autoSwitch = DEFAULT_AUTO_SWITCH_SETTINGS;
-        }
-
-        if (data.version === STORE_VERSION) {
-          // Parse dates
-          data.profiles = data.profiles.map((p: ClaudeProfile) => ({
-            ...p,
-            createdAt: new Date(p.createdAt),
-            lastUsedAt: p.lastUsedAt ? new Date(p.lastUsedAt) : undefined,
-            usage: p.usage ? {
-              ...p.usage,
-              lastUpdated: new Date(p.usage.lastUpdated)
-            } : undefined,
-            rateLimitEvents: p.rateLimitEvents?.map(e => ({
-              ...e,
-              hitAt: new Date(e.hitAt),
-              resetAt: new Date(e.resetAt)
-            }))
-          }));
-          return data;
-        }
-      }
-    } catch (error) {
-      console.error('[ClaudeProfileManager] Error loading profiles:', error);
+    const loadedData = loadProfileStore(this.storePath);
+    if (loadedData) {
+      return loadedData;
    }

    // Return default with a single "Default" profile
@@ -229,7 +99,7 @@ export class ClaudeProfileManager {
    };

    return {
-      version: STORE_VERSION,
+      version: 3,
      profiles: [defaultProfile],
      activeProfileId: 'default',
      autoSwitch: DEFAULT_AUTO_SWITCH_SETTINGS
@@ -240,11 +110,7 @@ export class ClaudeProfileManager {
   * Save profiles to disk
   */
  private save(): void {
-    try {
-      writeFileSync(this.storePath, JSON.stringify(this.data, null, 2), 'utf-8');
-    } catch (error) {
-      console.error('[ClaudeProfileManager] Error saving profiles:', error);
-    }
+    saveProfileStore(this.storePath, this.data);
  }

  /**
@@ -305,9 +171,8 @@ export class ClaudeProfileManager {
   */
  saveProfile(profile: ClaudeProfile): ClaudeProfile {
    // Expand ~ in configDir path
-    if (profile.configDir && profile.configDir.startsWith('~')) {
-      const home = homedir();
-      profile.configDir = profile.configDir.replace(/^~/, home);
+    if (profile.configDir) {
+      profile.configDir = expandHomePath(profile.configDir);
    }

    const index = this.data.profiles.findIndex(p => p.id === profile.id);
@@ -445,12 +310,12 @@ export class ClaudeProfileManager {
    if (email) {
      profile.email = email;
    }
-    
+
    // Clear any rate limit events since this might be a new account
    profile.rateLimitEvents = [];
-    
+
    this.save();
-    
+
    const isEncrypted = profile.oauthToken.startsWith('enc:');
    console.log('[ClaudeProfileManager] Set OAuth token for profile:', profile.name, {
      email: email || '(not captured)',
@@ -466,21 +331,10 @@ export class ClaudeProfileManager {
   */
  hasValidToken(profileId: string): boolean {
    const profile = this.getProfile(profileId);
-    if (!profile?.oauthToken) {
+    if (!profile) {
      return false;
    }
-    
-    // Check if token is expired (1 year validity)
-    if (profile.tokenCreatedAt) {
-      const oneYearAgo = new Date();
-      oneYearAgo.setFullYear(oneYearAgo.getFullYear() - 1);
-      if (new Date(profile.tokenCreatedAt) < oneYearAgo) {
-        console.log('[ClaudeProfileManager] Token expired for profile:', profile.name);
-        return false;
-      }
-    }
-    
-    return true;
+    return hasValidToken(profile);
  }

  /**
@@ -518,41 +372,7 @@ export class ClaudeProfileManager {
      return null;
    }

-    // Parse the /usage output
-    // Expected format sections:
-    // "Current session ████▌ 9% used Resets 11:59pm"
-    // "Current week (all models) 79% used Resets Nov 1, 10:59am"
-    // "Current week (Opus) 0% used"
-
-    const sections = usageOutput.split(/Current\s+/i).filter(Boolean);
-    const usage: ClaudeUsageData = {
-      sessionUsagePercent: 0,
-      sessionResetTime: '',
-      weeklyUsagePercent: 0,
-      weeklyResetTime: '',
-      lastUpdated: new Date()
-    };
-
-    for (const section of sections) {
-      const percentMatch = section.match(USAGE_PERCENT_PATTERN);
-      const resetMatch = section.match(USAGE_RESET_PATTERN);
-
-      if (percentMatch) {
-        const percent = parseInt(percentMatch[1], 10);
-        const resetTime = resetMatch?.[1]?.trim() || '';
-
-        if (/session/i.test(section)) {
-          usage.sessionUsagePercent = percent;
-          usage.sessionResetTime = resetTime;
-        } else if (/week.*all\s*model/i.test(section)) {
-          usage.weeklyUsagePercent = percent;
-          usage.weeklyResetTime = resetTime;
-        } else if (/week.*opus/i.test(section)) {
-          usage.opusUsagePercent = percent;
-        }
-      }
-    }
-
+    const usage = parseUsageOutput(usageOutput);
    profile.usage = usage;
    this.save();

@@ -569,19 +389,7 @@ export class ClaudeProfileManager {
      throw new Error('Profile not found');
    }

-    const event: ClaudeRateLimitEvent = {
-      type: classifyRateLimitType(resetTimeStr),
-      hitAt: new Date(),
-      resetAt: parseResetTime(resetTimeStr),
-      resetTimeString: resetTimeStr
-    };
-
-    // Keep last 10 events
-    profile.rateLimitEvents = [
-      event,
-      ...(profile.rateLimitEvents || []).slice(0, 9)
-    ];
-
+    const event = recordRateLimitEventImpl(profile, resetTimeStr);
    this.save();

    console.log('[ClaudeProfileManager] Recorded rate limit event for', profile.name, ':', event);
@@ -593,23 +401,10 @@ export class ClaudeProfileManager {
   */
  isProfileRateLimited(profileId: string): { limited: boolean; type?: 'session' | 'weekly'; resetAt?: Date } {
    const profile = this.getProfile(profileId);
-    if (!profile || !profile.rateLimitEvents?.length) {
+    if (!profile) {
      return { limited: false };
    }
-
-    const now = new Date();
-    // Check the most recent event
-    const latestEvent = profile.rateLimitEvents[0];
-
-    if (latestEvent.resetAt > now) {
-      return {
-        limited: true,
-        type: latestEvent.type,
-        resetAt: latestEvent.resetAt
-      };
-    }
-
-    return { limited: false };
+    return isProfileRateLimitedImpl(profile);
  }

  /**
@@ -617,157 +412,35 @@ export class ClaudeProfileManager {
   * Returns null if no good alternative is available
   */
  getBestAvailableProfile(excludeProfileId?: string): ClaudeProfile | null {
-    const now = new Date();
    const settings = this.getAutoSwitchSettings();
-
-    // Get all profiles except the excluded one
-    const candidates = this.data.profiles.filter(p => p.id !== excludeProfileId);
-
-    if (candidates.length === 0) {
-      return null;
-    }
-
-    // Score each profile based on:
-    // 1. Not rate-limited (highest priority)
-    // 2. Lower weekly usage (more important than session)
-    // 3. Lower session usage
-    // 4. More recently authenticated
-
-    const scoredProfiles = candidates.map(profile => {
-      let score = 100;  // Base score
-
-      // Check rate limit status
-      const rateLimitStatus = this.isProfileRateLimited(profile.id);
-      if (rateLimitStatus.limited) {
-        // Severely penalize rate-limited profiles
-        if (rateLimitStatus.type === 'weekly') {
-          score -= 1000;  // Weekly limit is worse
-        } else {
-          score -= 500;   // Session limit will reset sooner
-        }
-
-        // But add back some score based on how soon it resets
-        if (rateLimitStatus.resetAt) {
-          const hoursUntilReset = (rateLimitStatus.resetAt.getTime() - now.getTime()) / (1000 * 60 * 60);
-          score += Math.max(0, 50 - hoursUntilReset);  // Closer reset = higher score
-        }
-      }
-
-      // Factor in current usage (if known)
-      if (profile.usage) {
-        // Weekly usage is more important
-        score -= profile.usage.weeklyUsagePercent * 0.5;
-        // Session usage is less important (resets more frequently)
-        score -= profile.usage.sessionUsagePercent * 0.2;
-
-        // Penalize if above thresholds
-        if (profile.usage.weeklyUsagePercent >= settings.weeklyThreshold) {
-          score -= 200;
-        }
-        if (profile.usage.sessionUsagePercent >= settings.sessionThreshold) {
-          score -= 100;
-        }
-      }
-
-      // Check if authenticated
-      if (!this.isProfileAuthenticated(profile)) {
-        score -= 500;  // Severely penalize unauthenticated profiles
-      }
-
-      return { profile, score };
-    });
-
-    // Sort by score (highest first)
-    scoredProfiles.sort((a, b) => b.score - a.score);
-
-    // Return the best candidate if it has a positive score
-    const best = scoredProfiles[0];
-    if (best && best.score > 0) {
-      console.log('[ClaudeProfileManager] Best available profile:', best.profile.name, 'score:', best.score);
-      return best.profile;
-    }
-
-    // All profiles are rate-limited or have issues
-    console.log('[ClaudeProfileManager] No good profile available, all are rate-limited or have issues');
-    return null;
+    return getBestAvailableProfile(this.data.profiles, settings, excludeProfileId);
  }

  /**
   * Determine if we should proactively switch profiles based on current usage
   */
  shouldProactivelySwitch(profileId: string): { shouldSwitch: boolean; reason?: string; suggestedProfile?: ClaudeProfile } {
-    const settings = this.getAutoSwitchSettings();
-    if (!settings.enabled) {
-      return { shouldSwitch: false };
-    }
-
    const profile = this.getProfile(profileId);
-    if (!profile?.usage) {
+    if (!profile) {
      return { shouldSwitch: false };
    }

-    const usage = profile.usage;
-
-    // Check if we're approaching limits
-    if (usage.weeklyUsagePercent >= settings.weeklyThreshold) {
-      const bestProfile = this.getBestAvailableProfile(profileId);
-      if (bestProfile) {
-        return {
-          shouldSwitch: true,
-          reason: `Weekly usage at ${usage.weeklyUsagePercent}% (threshold: ${settings.weeklyThreshold}%)`,
-          suggestedProfile: bestProfile
-        };
-      }
-    }
-
-    if (usage.sessionUsagePercent >= settings.sessionThreshold) {
-      const bestProfile = this.getBestAvailableProfile(profileId);
-      if (bestProfile) {
-        return {
-          shouldSwitch: true,
-          reason: `Session usage at ${usage.sessionUsagePercent}% (threshold: ${settings.sessionThreshold}%)`,
-          suggestedProfile: bestProfile
-        };
-      }
-    }
-
-    return { shouldSwitch: false };
+    const settings = this.getAutoSwitchSettings();
+    return shouldProactivelySwitchImpl(profile, this.data.profiles, settings);
  }

  /**
   * Generate a unique ID for a new profile
   */
  generateProfileId(name: string): string {
-    const baseId = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
-    let id = baseId;
-    let counter = 1;
-
-    while (this.data.profiles.some(p => p.id === id)) {
-      id = `${baseId}-${counter}`;
-      counter++;
-    }
-
-    return id;
+    return generateProfileIdImpl(name, this.data.profiles);
  }

  /**
   * Create a new profile directory and initialize it
   */
  async createProfileDirectory(profileName: string): Promise<string> {
-    // Ensure profiles directory exists
-    if (!existsSync(CLAUDE_PROFILES_DIR)) {
-      mkdirSync(CLAUDE_PROFILES_DIR, { recursive: true });
-    }
-
-    // Create directory for this profile
-    const sanitizedName = profileName.toLowerCase().replace(/[^a-z0-9]+/g, '-');
-    const profileDir = join(CLAUDE_PROFILES_DIR, sanitizedName);
-
-    if (!existsSync(profileDir)) {
-      mkdirSync(profileDir, { recursive: true });
-    }
-
-    return profileDir;
+    return createProfileDirectoryImpl(profileName);
  }

  /**
@@ -775,48 +448,7 @@ export class ClaudeProfileManager {
   * (checks if the config directory has credential files)
   */
  isProfileAuthenticated(profile: ClaudeProfile): boolean {
-    const configDir = profile.configDir;
-    if (!configDir || !existsSync(configDir)) {
-      return false;
-    }
-
-    // Claude stores auth in .claude/credentials or similar files
-    // Check for common auth indicators
-    const possibleAuthFiles = [
-      join(configDir, 'credentials'),
-      join(configDir, 'credentials.json'),
-      join(configDir, '.credentials'),
-      join(configDir, 'settings.json'),  // Often contains auth tokens
-    ];
-
-    for (const authFile of possibleAuthFiles) {
-      if (existsSync(authFile)) {
-        try {
-          const content = readFileSync(authFile, 'utf-8');
-          // Check if file has actual content (not just empty or placeholder)
-          if (content.length > 10) {
-            return true;
-          }
-        } catch {
-          // Ignore read errors
-        }
-      }
-    }
-
-    // Also check if there are any session files (indicates authenticated usage)
-    const projectsDir = join(configDir, 'projects');
-    if (existsSync(projectsDir)) {
-      try {
-        const projects = readdirSync(projectsDir);
-        if (projects.length > 0) {
-          return true;
-        }
-      } catch {
-        // Ignore read errors
-      }
-    }
-
-    return false;
+    return isProfileAuthenticatedImpl(profile);
  }

  /**
@@ -849,7 +481,7 @@ export class ClaudeProfileManager {
  clearRateLimitEvents(profileId: string): void {
    const profile = this.getProfile(profileId);
    if (profile) {
-      profile.rateLimitEvents = [];
+      clearRateLimitEventsImpl(profile);
      this.save();
    }
  }
@@ -858,34 +490,7 @@ export class ClaudeProfileManager {
   * Get profiles sorted by availability (best first)
   */
  getProfilesSortedByAvailability(): ClaudeProfile[] {
-    const now = new Date();
-
-    return [...this.data.profiles].sort((a, b) => {
-      // Not rate-limited profiles first
-      const aLimited = this.isProfileRateLimited(a.id);
-      const bLimited = this.isProfileRateLimited(b.id);
-
-      if (aLimited.limited !== bLimited.limited) {
-        return aLimited.limited ? 1 : -1;
-      }
-
-      // If both limited, sort by reset time
-      if (aLimited.limited && bLimited.limited && aLimited.resetAt && bLimited.resetAt) {
-        return aLimited.resetAt.getTime() - bLimited.resetAt.getTime();
-      }
-
-      // Sort by lower weekly usage
-      const aWeekly = a.usage?.weeklyUsagePercent ?? 0;
-      const bWeekly = b.usage?.weeklyUsagePercent ?? 0;
-      if (aWeekly !== bWeekly) {
-        return aWeekly - bWeekly;
-      }
-
-      // Sort by lower session usage
-      const aSession = a.usage?.sessionUsagePercent ?? 0;
-      const bSession = b.usage?.sessionUsagePercent ?? 0;
-      return aSession - bSession;
-    });
+    return getProfilesSortedByAvailabilityImpl(this.data.profiles);
  }
 }

@@ -0,0 +1,148 @@
+# Claude Profile Module
+
+This directory contains the refactored Claude profile management system, broken down into logical, maintainable modules.
+
+## Architecture
+
+The profile management system is organized using separation of concerns, with each module handling a specific responsibility:
+
+```
+claude-profile/
+├── index.ts                 # Central export point
+├── types.ts                 # Type definitions
+├── token-encryption.ts      # OAuth token encryption/decryption
+├── usage-parser.ts          # Usage data parsing and reset time calculations
+├── rate-limit-manager.ts    # Rate limit event tracking
+├── profile-storage.ts       # Disk persistence
+├── profile-scorer.ts        # Profile availability scoring and auto-switch logic
+└── profile-utils.ts         # Helper utilities
+```
+
+## Modules
+
+### 1. **token-encryption.ts**
+Handles OAuth token encryption and decryption using the OS keychain (Electron's safeStorage API).
+
+**Key Functions:**
+- `encryptToken(token: string): string` - Encrypts a token using OS keychain
+- `decryptToken(storedToken: string): string` - Decrypts a token, handles legacy plain tokens
+- `isTokenEncrypted(storedToken: string): boolean` - Checks if token is encrypted
+
+### 2. **usage-parser.ts**
+Parses Claude `/usage` command output and calculates reset times.
+
+**Key Functions:**
+- `parseUsageOutput(usageOutput: string): ClaudeUsageData` - Parses full usage output
+- `parseResetTime(resetTimeStr: string): Date` - Converts reset time strings to Date objects
+- `classifyRateLimitType(resetTimeStr: string): 'session' | 'weekly'` - Determines rate limit type
+
+### 3. **rate-limit-manager.ts**
+Manages rate limit events and status tracking.
+
+**Key Functions:**
+- `recordRateLimitEvent(profile, resetTimeStr): ClaudeRateLimitEvent` - Records a rate limit hit
+- `isProfileRateLimited(profile): {limited, type?, resetAt?}` - Checks current rate limit status
+- `clearRateLimitEvents(profile): void` - Clears rate limit history
+
+### 4. **profile-storage.ts**
+Handles persistence of profile data to disk with version migration.
+
+**Key Functions:**
+- `loadProfileStore(storePath: string): ProfileStoreData | null` - Loads profiles from disk
+- `saveProfileStore(storePath: string, data: ProfileStoreData): void` - Saves profiles to disk
+
+**Constants:**
+- `STORE_VERSION` - Current storage format version
+- `DEFAULT_AUTO_SWITCH_SETTINGS` - Default auto-switch configuration
+
+### 5. **profile-scorer.ts**
+Implements intelligent profile scoring and auto-switch logic.
+
+**Key Functions:**
+- `getBestAvailableProfile(profiles, settings, excludeProfileId?): ClaudeProfile | null` - Finds best profile based on usage/limits
+- `shouldProactivelySwitch(profile, allProfiles, settings): {shouldSwitch, reason?, suggestedProfile?}` - Determines if proactive switch is needed
+- `getProfilesSortedByAvailability(profiles): ClaudeProfile[]` - Sorts profiles by availability
+
+**Scoring Criteria:**
+1. Not rate-limited (highest priority)
+2. Lower weekly usage (more important than session)
+3. Lower session usage
+4. Authenticated profiles
+
+### 6. **profile-utils.ts**
+Helper utilities for profile operations.
+
+**Key Functions:**
+- `generateProfileId(name, existingProfiles): string` - Generates unique profile IDs
+- `createProfileDirectory(profileName): Promise<string>` - Creates profile directory
+- `isProfileAuthenticated(profile): boolean` - Checks if profile has valid auth
+- `hasValidToken(profile): boolean` - Validates OAuth token (1 year expiry)
+- `expandHomePath(path): string` - Expands ~ in paths
+
+**Constants:**
+- `DEFAULT_CLAUDE_CONFIG_DIR` - Default Claude config location (~/.claude)
+- `CLAUDE_PROFILES_DIR` - Additional profiles directory (~/.claude-profiles)
+
+### 7. **types.ts**
+Re-exports shared types for convenience and future extensibility.
+
+### 8. **index.ts**
+Central export point providing a clean public API for all profile functionality.
+
+## Main Manager
+
+The `claude-profile-manager.ts` (parent directory) serves as the high-level coordinator that:
+- Delegates to specialized modules
+- Manages the overall profile lifecycle
+- Coordinates between different subsystems
+- Provides the singleton instance
+
+**Original size:** 903 lines
+**Refactored size:** 509 lines (44% reduction)
+**Total with modules:** 1197 lines (organized and maintainable)
+
+## Usage
+
+### Using the Main Manager
+```typescript
+import { getClaudeProfileManager } from './claude-profile-manager';
+
+const manager = getClaudeProfileManager();
+const profile = manager.getActiveProfile();
+const usage = manager.updateProfileUsage(profileId, usageOutput);
+```
+
+### Using Individual Modules (Advanced)
+```typescript
+import { parseUsageOutput, isProfileRateLimited } from './claude-profile';
+
+const usage = parseUsageOutput(output);
+const status = isProfileRateLimited(profile);
+```
+
+## Benefits of Refactoring
+
+1. **Separation of Concerns** - Each module has a single, well-defined responsibility
+2. **Testability** - Modules can be unit tested independently
+3. **Maintainability** - Easier to understand and modify specific functionality
+4. **Reusability** - Modules can be imported individually when needed
+5. **Readability** - Smaller files are easier to navigate and understand
+6. **Type Safety** - Clear module boundaries with explicit TypeScript types
+
+## Backward Compatibility
+
+All existing imports continue to work without modification:
+```typescript
+import { getClaudeProfileManager } from './claude-profile-manager';
+```
+
+The public API of `ClaudeProfileManager` remains unchanged, ensuring zero breaking changes for existing code.
+
+## Future Enhancements
+
+Potential areas for future improvement:
+- Add comprehensive unit tests for each module
+- Implement profile import/export functionality
+- Add profile usage analytics and reporting
+- Enhance auto-switch algorithms with machine learning
+- Add profile backup and restore capabilities
@@ -0,0 +1,56 @@
+/**
+ * Claude Profile Module
+ * Central export point for all profile management functionality
+ */
+
+// Core types
+export type {
+  ClaudeProfile,
+  ClaudeProfileSettings,
+  ClaudeUsageData,
+  ClaudeRateLimitEvent,
+  ClaudeAutoSwitchSettings
+} from './types';
+
+// Token encryption utilities
+export { encryptToken, decryptToken, isTokenEncrypted } from './token-encryption';
+
+// Usage parsing utilities
+export { parseUsageOutput, parseResetTime, classifyRateLimitType } from './usage-parser';
+
+// Rate limit management
+export {
+  recordRateLimitEvent,
+  isProfileRateLimited,
+  clearRateLimitEvents
+} from './rate-limit-manager';
+
+// Storage utilities
+export {
+  loadProfileStore,
+  saveProfileStore,
+  DEFAULT_AUTO_SWITCH_SETTINGS,
+  STORE_VERSION
+} from './profile-storage';
+export type { ProfileStoreData } from './profile-storage';
+
+// Profile scoring and auto-switch
+export {
+  getBestAvailableProfile,
+  shouldProactivelySwitch,
+  getProfilesSortedByAvailability
+} from './profile-scorer';
+
+// Profile utilities
+export {
+  DEFAULT_CLAUDE_CONFIG_DIR,
+  CLAUDE_PROFILES_DIR,
+  generateProfileId,
+  createProfileDirectory,
+  isProfileAuthenticated,
+  hasValidToken,
+  expandHomePath
+} from './profile-utils';
+
+// Usage monitoring (proactive account switching)
+export { UsageMonitor, getUsageMonitor } from './usage-monitor';
@@ -0,0 +1,174 @@
+/**
+ * Profile Scorer Module
+ * Handles profile availability scoring and auto-switch logic
+ */
+
+import type { ClaudeProfile, ClaudeAutoSwitchSettings } from '../../shared/types';
+import { isProfileRateLimited } from './rate-limit-manager';
+import { isProfileAuthenticated } from './profile-utils';
+
+interface ScoredProfile {
+  profile: ClaudeProfile;
+  score: number;
+}
+
+/**
+ * Get the best profile to switch to based on usage and rate limit status
+ * Returns null if no good alternative is available
+ */
+export function getBestAvailableProfile(
+  profiles: ClaudeProfile[],
+  settings: ClaudeAutoSwitchSettings,
+  excludeProfileId?: string
+): ClaudeProfile | null {
+  const now = new Date();
+
+  // Get all profiles except the excluded one
+  const candidates = profiles.filter(p => p.id !== excludeProfileId);
+
+  if (candidates.length === 0) {
+    return null;
+  }
+
+  // Score each profile based on:
+  // 1. Not rate-limited (highest priority)
+  // 2. Lower weekly usage (more important than session)
+  // 3. Lower session usage
+  // 4. More recently authenticated
+
+  const scoredProfiles: ScoredProfile[] = candidates.map(profile => {
+    let score = 100;  // Base score
+
+    // Check rate limit status
+    const rateLimitStatus = isProfileRateLimited(profile);
+    if (rateLimitStatus.limited) {
+      // Severely penalize rate-limited profiles
+      if (rateLimitStatus.type === 'weekly') {
+        score -= 1000;  // Weekly limit is worse
+      } else {
+        score -= 500;   // Session limit will reset sooner
+      }
+
+      // But add back some score based on how soon it resets
+      if (rateLimitStatus.resetAt) {
+        const hoursUntilReset = (rateLimitStatus.resetAt.getTime() - now.getTime()) / (1000 * 60 * 60);
+        score += Math.max(0, 50 - hoursUntilReset);  // Closer reset = higher score
+      }
+    }
+
+    // Factor in current usage (if known)
+    if (profile.usage) {
+      // Weekly usage is more important
+      score -= profile.usage.weeklyUsagePercent * 0.5;
+      // Session usage is less important (resets more frequently)
+      score -= profile.usage.sessionUsagePercent * 0.2;
+
+      // Penalize if above thresholds
+      if (profile.usage.weeklyUsagePercent >= settings.weeklyThreshold) {
+        score -= 200;
+      }
+      if (profile.usage.sessionUsagePercent >= settings.sessionThreshold) {
+        score -= 100;
+      }
+    }
+
+    // Check if authenticated
+    if (!isProfileAuthenticated(profile)) {
+      score -= 500;  // Severely penalize unauthenticated profiles
+    }
+
+    return { profile, score };
+  });
+
+  // Sort by score (highest first)
+  scoredProfiles.sort((a, b) => b.score - a.score);
+
+  // Return the best candidate if it has a positive score
+  const best = scoredProfiles[0];
+  if (best && best.score > 0) {
+    console.log('[ProfileScorer] Best available profile:', best.profile.name, 'score:', best.score);
+    return best.profile;
+  }
+
+  // All profiles are rate-limited or have issues
+  console.log('[ProfileScorer] No good profile available, all are rate-limited or have issues');
+  return null;
+}
+
+/**
+ * Determine if we should proactively switch profiles based on current usage
+ */
+export function shouldProactivelySwitch(
+  profile: ClaudeProfile,
+  allProfiles: ClaudeProfile[],
+  settings: ClaudeAutoSwitchSettings
+): { shouldSwitch: boolean; reason?: string; suggestedProfile?: ClaudeProfile } {
+  if (!settings.enabled) {
+    return { shouldSwitch: false };
+  }
+
+  if (!profile?.usage) {
+    return { shouldSwitch: false };
+  }
+
+  const usage = profile.usage;
+
+  // Check if we're approaching limits
+  if (usage.weeklyUsagePercent >= settings.weeklyThreshold) {
+    const bestProfile = getBestAvailableProfile(allProfiles, settings, profile.id);
+    if (bestProfile) {
+      return {
+        shouldSwitch: true,
+        reason: `Weekly usage at ${usage.weeklyUsagePercent}% (threshold: ${settings.weeklyThreshold}%)`,
+        suggestedProfile: bestProfile
+      };
+    }
+  }
+
+  if (usage.sessionUsagePercent >= settings.sessionThreshold) {
+    const bestProfile = getBestAvailableProfile(allProfiles, settings, profile.id);
+    if (bestProfile) {
+      return {
+        shouldSwitch: true,
+        reason: `Session usage at ${usage.sessionUsagePercent}% (threshold: ${settings.sessionThreshold}%)`,
+        suggestedProfile: bestProfile
+      };
+    }
+  }
+
+  return { shouldSwitch: false };
+}
+
+/**
+ * Get profiles sorted by availability (best first)
+ */
+export function getProfilesSortedByAvailability(profiles: ClaudeProfile[]): ClaudeProfile[] {
+  const now = new Date();
+
+  return [...profiles].sort((a, b) => {
+    // Not rate-limited profiles first
+    const aLimited = isProfileRateLimited(a);
+    const bLimited = isProfileRateLimited(b);
+
+    if (aLimited.limited !== bLimited.limited) {
+      return aLimited.limited ? 1 : -1;
+    }
+
+    // If both limited, sort by reset time
+    if (aLimited.limited && bLimited.limited && aLimited.resetAt && bLimited.resetAt) {
+      return aLimited.resetAt.getTime() - bLimited.resetAt.getTime();
+    }
+
+    // Sort by lower weekly usage
+    const aWeekly = a.usage?.weeklyUsagePercent ?? 0;
+    const bWeekly = b.usage?.weeklyUsagePercent ?? 0;
+    if (aWeekly !== bWeekly) {
+      return aWeekly - bWeekly;
+    }
+
+    // Sort by lower session usage
+    const aSession = a.usage?.sessionUsagePercent ?? 0;
+    const bSession = b.usage?.sessionUsagePercent ?? 0;
+    return aSession - bSession;
+  });
+}
@@ -0,0 +1,84 @@
+/**
+ * Profile Storage Module
+ * Handles persistence of profile data to disk
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import type { ClaudeProfile, ClaudeAutoSwitchSettings } from '../../shared/types';
+
+export const STORE_VERSION = 3;  // Bumped for encrypted token storage
+
+/**
+ * Default auto-switch settings
+ */
+export const DEFAULT_AUTO_SWITCH_SETTINGS: ClaudeAutoSwitchSettings = {
+  enabled: false,
+  proactiveSwapEnabled: false,  // Proactive monitoring disabled by default
+  sessionThreshold: 95,  // Consider switching at 95% session usage
+  weeklyThreshold: 99,   // Consider switching at 99% weekly usage
+  autoSwitchOnRateLimit: false,  // Prompt user by default
+  usageCheckInterval: 30000  // Check every 30s when enabled (0 = disabled)
+};
+
+/**
+ * Internal storage format for Claude profiles
+ */
+export interface ProfileStoreData {
+  version: number;
+  profiles: ClaudeProfile[];
+  activeProfileId: string;
+  autoSwitch?: ClaudeAutoSwitchSettings;
+}
+
+/**
+ * Load profiles from disk
+ */
+export function loadProfileStore(storePath: string): ProfileStoreData | null {
+  try {
+    if (existsSync(storePath)) {
+      const content = readFileSync(storePath, 'utf-8');
+      const data = JSON.parse(content);
+
+      // Handle version migration
+      if (data.version === 1) {
+        // Migrate v1 to v2: add usage and rateLimitEvents fields
+        data.version = STORE_VERSION;
+        data.autoSwitch = DEFAULT_AUTO_SWITCH_SETTINGS;
+      }
+
+      if (data.version === STORE_VERSION) {
+        // Parse dates
+        data.profiles = data.profiles.map((p: ClaudeProfile) => ({
+          ...p,
+          createdAt: new Date(p.createdAt),
+          lastUsedAt: p.lastUsedAt ? new Date(p.lastUsedAt) : undefined,
+          usage: p.usage ? {
+            ...p.usage,
+            lastUpdated: new Date(p.usage.lastUpdated)
+          } : undefined,
+          rateLimitEvents: p.rateLimitEvents?.map(e => ({
+            ...e,
+            hitAt: new Date(e.hitAt),
+            resetAt: new Date(e.resetAt)
+          }))
+        }));
+        return data;
+      }
+    }
+  } catch (error) {
+    console.error('[ProfileStorage] Error loading profiles:', error);
+  }
+
+  return null;
+}
+
+/**
+ * Save profiles to disk
+ */
+export function saveProfileStore(storePath: string, data: ProfileStoreData): void {
+  try {
+    writeFileSync(storePath, JSON.stringify(data, null, 2), 'utf-8');
+  } catch (error) {
+    console.error('[ProfileStorage] Error saving profiles:', error);
+  }
+}
@@ -0,0 +1,137 @@
+/**
+ * Profile Utilities Module
+ * Helper functions for profile operations
+ */
+
+import { homedir } from 'os';
+import { join } from 'path';
+import { existsSync, readFileSync, readdirSync, mkdirSync } from 'fs';
+import type { ClaudeProfile } from '../../shared/types';
+
+/**
+ * Default Claude config directory
+ */
+export const DEFAULT_CLAUDE_CONFIG_DIR = join(homedir(), '.claude');
+
+/**
+ * Default profiles directory for additional accounts
+ */
+export const CLAUDE_PROFILES_DIR = join(homedir(), '.claude-profiles');
+
+/**
+ * Generate a unique ID for a new profile
+ */
+export function generateProfileId(name: string, existingProfiles: ClaudeProfile[]): string {
+  const baseId = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+  let id = baseId;
+  let counter = 1;
+
+  while (existingProfiles.some(p => p.id === id)) {
+    id = `${baseId}-${counter}`;
+    counter++;
+  }
+
+  return id;
+}
+
+/**
+ * Create a new profile directory and initialize it
+ */
+export async function createProfileDirectory(profileName: string): Promise<string> {
+  // Ensure profiles directory exists
+  if (!existsSync(CLAUDE_PROFILES_DIR)) {
+    mkdirSync(CLAUDE_PROFILES_DIR, { recursive: true });
+  }
+
+  // Create directory for this profile
+  const sanitizedName = profileName.toLowerCase().replace(/[^a-z0-9]+/g, '-');
+  const profileDir = join(CLAUDE_PROFILES_DIR, sanitizedName);
+
+  if (!existsSync(profileDir)) {
+    mkdirSync(profileDir, { recursive: true });
+  }
+
+  return profileDir;
+}
+
+/**
+ * Check if a profile has valid authentication
+ * (checks if the config directory has credential files)
+ */
+export function isProfileAuthenticated(profile: ClaudeProfile): boolean {
+  const configDir = profile.configDir;
+  if (!configDir || !existsSync(configDir)) {
+    return false;
+  }
+
+  // Claude stores auth in .claude/credentials or similar files
+  // Check for common auth indicators
+  const possibleAuthFiles = [
+    join(configDir, 'credentials'),
+    join(configDir, 'credentials.json'),
+    join(configDir, '.credentials'),
+    join(configDir, 'settings.json'),  // Often contains auth tokens
+  ];
+
+  for (const authFile of possibleAuthFiles) {
+    if (existsSync(authFile)) {
+      try {
+        const content = readFileSync(authFile, 'utf-8');
+        // Check if file has actual content (not just empty or placeholder)
+        if (content.length > 10) {
+          return true;
+        }
+      } catch {
+        // Ignore read errors
+      }
+    }
+  }
+
+  // Also check if there are any session files (indicates authenticated usage)
+  const projectsDir = join(configDir, 'projects');
+  if (existsSync(projectsDir)) {
+    try {
+      const projects = readdirSync(projectsDir);
+      if (projects.length > 0) {
+        return true;
+      }
+    } catch {
+      // Ignore read errors
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Check if a profile has a valid OAuth token.
+ * Token is valid for 1 year from creation.
+ */
+export function hasValidToken(profile: ClaudeProfile): boolean {
+  if (!profile?.oauthToken) {
+    return false;
+  }
+
+  // Check if token is expired (1 year validity)
+  if (profile.tokenCreatedAt) {
+    const oneYearAgo = new Date();
+    oneYearAgo.setFullYear(oneYearAgo.getFullYear() - 1);
+    if (new Date(profile.tokenCreatedAt) < oneYearAgo) {
+      console.log('[ProfileUtils] Token expired for profile:', profile.name);
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Expand ~ in path to home directory
+ */
+export function expandHomePath(path: string): string {
+  if (path && path.startsWith('~')) {
+    const home = homedir();
+    return path.replace(/^~/, home);
+  }
+  return path;
+}
@@ -0,0 +1,62 @@
+/**
+ * Rate Limit Manager Module
+ * Handles rate limit event recording and status checking
+ */
+
+import type { ClaudeProfile, ClaudeRateLimitEvent } from '../../shared/types';
+import { parseResetTime, classifyRateLimitType } from './usage-parser';
+
+/**
+ * Record a rate limit event for a profile
+ */
+export function recordRateLimitEvent(
+  profile: ClaudeProfile,
+  resetTimeStr: string
+): ClaudeRateLimitEvent {
+  const event: ClaudeRateLimitEvent = {
+    type: classifyRateLimitType(resetTimeStr),
+    hitAt: new Date(),
+    resetAt: parseResetTime(resetTimeStr),
+    resetTimeString: resetTimeStr
+  };
+
+  // Keep last 10 events
+  profile.rateLimitEvents = [
+    event,
+    ...(profile.rateLimitEvents || []).slice(0, 9)
+  ];
+
+  return event;
+}
+
+/**
+ * Check if a profile is currently rate-limited
+ */
+export function isProfileRateLimited(
+  profile: ClaudeProfile
+): { limited: boolean; type?: 'session' | 'weekly'; resetAt?: Date } {
+  if (!profile || !profile.rateLimitEvents?.length) {
+    return { limited: false };
+  }
+
+  const now = new Date();
+  // Check the most recent event
+  const latestEvent = profile.rateLimitEvents[0];
+
+  if (latestEvent.resetAt > now) {
+    return {
+      limited: true,
+      type: latestEvent.type,
+      resetAt: latestEvent.resetAt
+    };
+  }
+
+  return { limited: false };
+}
+
+/**
+ * Clear rate limit events for a profile (e.g., when they've reset)
+ */
+export function clearRateLimitEvents(profile: ClaudeProfile): void {
+  profile.rateLimitEvents = [];
+}
@@ -0,0 +1,47 @@
+/**
+ * Token Encryption Module
+ * Handles OAuth token encryption/decryption using OS keychain
+ */
+
+import { safeStorage } from 'electron';
+
+/**
+ * Encrypt a token using the OS keychain (safeStorage API).
+ * Returns base64-encoded encrypted data, or the raw token if encryption unavailable.
+ */
+export function encryptToken(token: string): string {
+  try {
+    if (safeStorage.isEncryptionAvailable()) {
+      const encrypted = safeStorage.encryptString(token);
+      // Prefix with 'enc:' to identify encrypted tokens
+      return 'enc:' + encrypted.toString('base64');
+    }
+  } catch (error) {
+    console.warn('[TokenEncryption] Encryption not available, storing token as-is:', error);
+  }
+  return token;
+}
+
+/**
+ * Decrypt a token. Handles both encrypted (enc:...) and legacy plain tokens.
+ */
+export function decryptToken(storedToken: string): string {
+  try {
+    if (storedToken.startsWith('enc:') && safeStorage.isEncryptionAvailable()) {
+      const encryptedData = Buffer.from(storedToken.slice(4), 'base64');
+      return safeStorage.decryptString(encryptedData);
+    }
+  } catch (error) {
+    console.error('[TokenEncryption] Failed to decrypt token:', error);
+    return ''; // Return empty string on decryption failure
+  }
+  // Return as-is for legacy unencrypted tokens
+  return storedToken;
+}
+
+/**
+ * Check if a token is encrypted
+ */
+export function isTokenEncrypted(storedToken: string): boolean {
+  return storedToken.startsWith('enc:');
+}
@@ -0,0 +1,14 @@
+/**
+ * Profile Module Types
+ * Re-exports and additional types for profile management
+ */
+
+export type {
+  ClaudeProfile,
+  ClaudeProfileSettings,
+  ClaudeUsageData,
+  ClaudeRateLimitEvent,
+  ClaudeAutoSwitchSettings
+} from '../../shared/types';
+
+export type { ProfileStoreData } from './profile-storage';
@@ -0,0 +1,318 @@
+/**
+ * Usage Monitor - Proactive usage monitoring and account switching
+ *
+ * Monitors Claude account usage at configured intervals and automatically
+ * switches to alternative accounts before hitting rate limits.
+ *
+ * Uses hybrid approach:
+ * 1. Primary: Direct OAuth API (https://api.anthropic.com/api/oauth/usage)
+ * 2. Fallback: CLI /usage command parsing
+ */
+
+import { EventEmitter } from 'events';
+import { getClaudeProfileManager } from '../claude-profile-manager';
+import { ClaudeUsageSnapshot } from '../../shared/types/agent';
+
+export class UsageMonitor extends EventEmitter {
+  private static instance: UsageMonitor;
+  private intervalId: NodeJS.Timeout | null = null;
+  private currentUsage: ClaudeUsageSnapshot | null = null;
+  private isChecking = false;
+  private useApiMethod = true; // Try API first, fall back to CLI if it fails
+
+  private constructor() {
+    super();
+    console.log('[UsageMonitor] Initialized');
+  }
+
+  static getInstance(): UsageMonitor {
+    if (!UsageMonitor.instance) {
+      UsageMonitor.instance = new UsageMonitor();
+    }
+    return UsageMonitor.instance;
+  }
+
+  /**
+   * Start monitoring usage at configured interval
+   */
+  start(): void {
+    const profileManager = getClaudeProfileManager();
+    const settings = profileManager.getAutoSwitchSettings();
+
+    if (!settings.enabled || !settings.proactiveSwapEnabled) {
+      console.log('[UsageMonitor] Proactive monitoring disabled');
+      return;
+    }
+
+    if (this.intervalId) {
+      console.log('[UsageMonitor] Already running');
+      return;
+    }
+
+    const interval = settings.usageCheckInterval || 30000;
+    console.log('[UsageMonitor] Starting with interval:', interval, 'ms');
+
+    // Check immediately
+    this.checkUsageAndSwap();
+
+    // Then check periodically
+    this.intervalId = setInterval(() => {
+      this.checkUsageAndSwap();
+    }, interval);
+  }
+
+  /**
+   * Stop monitoring
+   */
+  stop(): void {
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+      console.log('[UsageMonitor] Stopped');
+    }
+  }
+
+  /**
+   * Get current usage snapshot (for UI indicator)
+   */
+  getCurrentUsage(): ClaudeUsageSnapshot | null {
+    return this.currentUsage;
+  }
+
+  /**
+   * Check usage and trigger swap if thresholds exceeded
+   */
+  private async checkUsageAndSwap(): Promise<void> {
+    if (this.isChecking) {
+      return; // Prevent concurrent checks
+    }
+
+    this.isChecking = true;
+
+    try {
+      const profileManager = getClaudeProfileManager();
+      const activeProfile = profileManager.getActiveProfile();
+
+      if (!activeProfile) {
+        console.log('[UsageMonitor] No active profile');
+        return;
+      }
+
+      // Fetch current usage (hybrid approach)
+      const usage = await this.fetchUsage(activeProfile.id, activeProfile.oauthToken);
+      if (!usage) {
+        console.log('[UsageMonitor] Failed to fetch usage');
+        return;
+      }
+
+      this.currentUsage = usage;
+
+      // Emit usage update for UI
+      this.emit('usage-updated', usage);
+
+      // Check thresholds
+      const settings = profileManager.getAutoSwitchSettings();
+      const sessionExceeded = usage.sessionPercent >= settings.sessionThreshold;
+      const weeklyExceeded = usage.weeklyPercent >= settings.weeklyThreshold;
+
+      if (sessionExceeded || weeklyExceeded) {
+        console.log('[UsageMonitor] Threshold exceeded:', {
+          sessionPercent: usage.sessionPercent,
+          sessionThreshold: settings.sessionThreshold,
+          weeklyPercent: usage.weeklyPercent,
+          weeklyThreshold: settings.weeklyThreshold
+        });
+
+        // Attempt proactive swap
+        await this.performProactiveSwap(
+          activeProfile.id,
+          sessionExceeded ? 'session' : 'weekly'
+        );
+      }
+    } catch (error) {
+      console.error('[UsageMonitor] Check failed:', error);
+    } finally {
+      this.isChecking = false;
+    }
+  }
+
+  /**
+   * Fetch usage - HYBRID APPROACH
+   * Tries API first, falls back to CLI if API fails
+   */
+  private async fetchUsage(
+    profileId: string,
+    oauthToken?: string
+  ): Promise<ClaudeUsageSnapshot | null> {
+    const profileManager = getClaudeProfileManager();
+    const profile = profileManager.getProfile(profileId);
+    if (!profile) {
+      return null;
+    }
+
+    // Attempt 1: Direct API call (preferred)
+    if (this.useApiMethod && oauthToken) {
+      const apiUsage = await this.fetchUsageViaAPI(oauthToken, profileId, profile.name);
+      if (apiUsage) {
+        console.log('[UsageMonitor] Successfully fetched via API');
+        return apiUsage;
+      }
+
+      // API failed - switch to CLI method for future calls
+      console.log('[UsageMonitor] API method failed, falling back to CLI');
+      this.useApiMethod = false;
+    }
+
+    // Attempt 2: CLI /usage command (fallback)
+    return await this.fetchUsageViaCLI(profileId, profile.name);
+  }
+
+  /**
+   * Fetch usage via OAuth API endpoint
+   * Endpoint: https://api.anthropic.com/api/oauth/usage
+   */
+  private async fetchUsageViaAPI(
+    oauthToken: string,
+    profileId: string,
+    profileName: string
+  ): Promise<ClaudeUsageSnapshot | null> {
+    try {
+      const response = await fetch('https://api.anthropic.com/api/oauth/usage', {
+        method: 'GET',
+        headers: {
+          'Authorization': `Bearer ${oauthToken}`,
+          'Content-Type': 'application/json',
+          'anthropic-version': '2023-06-01'
+        }
+      });
+
+      if (!response.ok) {
+        console.error('[UsageMonitor] API error:', response.status, response.statusText);
+        return null;
+      }
+
+      const data: any = await response.json();
+
+      // Expected response format:
+      // {
+      //   "five_hour_utilization": 0.72,  // 0.0-1.0
+      //   "seven_day_utilization": 0.45,  // 0.0-1.0
+      //   "five_hour_reset_at": "2025-01-17T15:00:00Z",
+      //   "seven_day_reset_at": "2025-01-20T12:00:00Z"
+      // }
+
+      return {
+        sessionPercent: Math.round((data.five_hour_utilization || 0) * 100),
+        weeklyPercent: Math.round((data.seven_day_utilization || 0) * 100),
+        sessionResetTime: this.formatResetTime(data.five_hour_reset_at),
+        weeklyResetTime: this.formatResetTime(data.seven_day_reset_at),
+        profileId,
+        profileName,
+        fetchedAt: new Date(),
+        limitType: (data.seven_day_utilization || 0) > (data.five_hour_utilization || 0)
+          ? 'weekly'
+          : 'session'
+      };
+    } catch (error) {
+      console.error('[UsageMonitor] API fetch failed:', error);
+      return null;
+    }
+  }
+
+  /**
+   * Fetch usage via CLI /usage command (fallback)
+   * Note: This is a fallback method. The API method is preferred.
+   * CLI-based fetching would require spawning a Claude process and parsing output,
+   * which is complex. For now, we rely on the API method.
+   */
+  private async fetchUsageViaCLI(
+    _profileId: string,
+    _profileName: string
+  ): Promise<ClaudeUsageSnapshot | null> {
+    // CLI-based usage fetching is not implemented yet.
+    // The API method should handle most cases. If we need CLI fallback,
+    // we would need to spawn a Claude process with /usage command and parse the output.
+    console.log('[UsageMonitor] CLI fallback not implemented, API method should be used');
+    return null;
+  }
+
+  /**
+   * Format ISO timestamp to human-readable reset time
+   */
+  private formatResetTime(isoTimestamp?: string): string {
+    if (!isoTimestamp) return 'Unknown';
+
+    try {
+      const date = new Date(isoTimestamp);
+      const now = new Date();
+      const diffMs = date.getTime() - now.getTime();
+      const diffHours = Math.floor(diffMs / (1000 * 60 * 60));
+      const diffMins = Math.floor((diffMs % (1000 * 60 * 60)) / (1000 * 60));
+
+      if (diffHours < 24) {
+        return `${diffHours}h ${diffMins}m`;
+      }
+
+      const diffDays = Math.floor(diffHours / 24);
+      const remainingHours = diffHours % 24;
+      return `${diffDays}d ${remainingHours}h`;
+    } catch (error) {
+      return isoTimestamp;
+    }
+  }
+
+  /**
+   * Perform proactive profile swap
+   */
+  private async performProactiveSwap(
+    currentProfileId: string,
+    limitType: 'session' | 'weekly'
+  ): Promise<void> {
+    const profileManager = getClaudeProfileManager();
+    const bestProfile = profileManager.getBestAvailableProfile(currentProfileId);
+
+    if (!bestProfile) {
+      console.log('[UsageMonitor] No alternative profile for proactive swap');
+      this.emit('proactive-swap-failed', {
+        reason: 'no_alternative',
+        currentProfile: currentProfileId
+      });
+      return;
+    }
+
+    console.log('[UsageMonitor] Proactive swap:', {
+      from: currentProfileId,
+      to: bestProfile.id,
+      reason: limitType
+    });
+
+    // Switch profile
+    profileManager.setActiveProfile(bestProfile.id);
+
+    // Emit swap event
+    this.emit('proactive-swap-completed', {
+      fromProfile: { id: currentProfileId, name: profileManager.getProfile(currentProfileId)?.name },
+      toProfile: { id: bestProfile.id, name: bestProfile.name },
+      limitType,
+      timestamp: new Date()
+    });
+
+    // Notify UI
+    this.emit('show-swap-notification', {
+      fromProfile: profileManager.getProfile(currentProfileId)?.name,
+      toProfile: bestProfile.name,
+      reason: 'proactive',
+      limitType
+    });
+
+    // Note: Don't immediately check new profile - let normal interval handle it
+    // This prevents cascading swaps if multiple profiles are near limits
+  }
+}
+
+/**
+ * Get the singleton UsageMonitor instance
+ */
+export function getUsageMonitor(): UsageMonitor {
+  return UsageMonitor.getInstance();
+}
@@ -0,0 +1,119 @@
+/**
+ * Usage Parser Module
+ * Handles parsing of Claude /usage command output and reset time calculations
+ */
+
+import type { ClaudeUsageData } from '../../shared/types';
+
+/**
+ * Regex to parse /usage command output
+ * Matches patterns like: "████▌ 9% used" and "Resets Nov 1, 10:59am (America/Sao_Paulo)"
+ */
+const USAGE_PERCENT_PATTERN = /(\d+)%\s*used/i;
+const USAGE_RESET_PATTERN = /Resets?\s+(.+?)(?:\s*$|\n)/i;
+
+/**
+ * Parse a rate limit reset time string and estimate when it resets
+ * Examples: "Dec 17 at 6am (Europe/Oslo)", "11:59pm (America/Sao_Paulo)", "Nov 1, 10:59am"
+ */
+export function parseResetTime(resetTimeStr: string): Date {
+  const now = new Date();
+
+  // Try to parse various formats
+  // Format: "Dec 17 at 6am (Europe/Oslo)" or "Nov 1, 10:59am"
+  const dateMatch = resetTimeStr.match(/([A-Za-z]+)\s+(\d+)(?:,|\s+at)?\s*(\d+)?:?(\d+)?(am|pm)?/i);
+  if (dateMatch) {
+    const [, month, day, hour = '0', minute = '0', ampm = ''] = dateMatch;
+    const monthMap: Record<string, number> = {
+      'jan': 0, 'feb': 1, 'mar': 2, 'apr': 3, 'may': 4, 'jun': 5,
+      'jul': 6, 'aug': 7, 'sep': 8, 'oct': 9, 'nov': 10, 'dec': 11
+    };
+    const monthNum = monthMap[month.toLowerCase()] ?? now.getMonth();
+    let hourNum = parseInt(hour, 10);
+    if (ampm.toLowerCase() === 'pm' && hourNum < 12) hourNum += 12;
+    if (ampm.toLowerCase() === 'am' && hourNum === 12) hourNum = 0;
+
+    const resetDate = new Date(now.getFullYear(), monthNum, parseInt(day, 10), hourNum, parseInt(minute, 10));
+    // If the date is in the past, assume next year
+    if (resetDate < now) {
+      resetDate.setFullYear(resetDate.getFullYear() + 1);
+    }
+    return resetDate;
+  }
+
+  // Format: "11:59pm" (today or tomorrow)
+  const timeOnlyMatch = resetTimeStr.match(/(\d+):?(\d+)?\s*(am|pm)/i);
+  if (timeOnlyMatch) {
+    const [, hour, minute = '0', ampm] = timeOnlyMatch;
+    let hourNum = parseInt(hour, 10);
+    if (ampm.toLowerCase() === 'pm' && hourNum < 12) hourNum += 12;
+    if (ampm.toLowerCase() === 'am' && hourNum === 12) hourNum = 0;
+
+    const resetDate = new Date(now.getFullYear(), now.getMonth(), now.getDate(), hourNum, parseInt(minute, 10));
+    // If the time is in the past, assume tomorrow
+    if (resetDate < now) {
+      resetDate.setDate(resetDate.getDate() + 1);
+    }
+    return resetDate;
+  }
+
+  // Fallback: assume 5 hours from now (session reset) or 7 days (weekly)
+  const isWeekly = resetTimeStr.toLowerCase().includes('week') ||
+    /[a-z]{3}\s+\d+/i.test(resetTimeStr);  // Has a date like "Dec 17"
+  if (isWeekly) {
+    return new Date(now.getTime() + 7 * 24 * 60 * 60 * 1000);
+  }
+  return new Date(now.getTime() + 5 * 60 * 60 * 1000);
+}
+
+/**
+ * Determine if a rate limit is session-based or weekly based on reset time
+ */
+export function classifyRateLimitType(resetTimeStr: string): 'session' | 'weekly' {
+  // Weekly limits mention specific dates like "Dec 17" or "Nov 1"
+  // Session limits are typically just times like "11:59pm"
+  const hasDate = /[A-Za-z]{3}\s+\d+/i.test(resetTimeStr);
+  const hasWeeklyIndicator = resetTimeStr.toLowerCase().includes('week');
+
+  return (hasDate || hasWeeklyIndicator) ? 'weekly' : 'session';
+}
+
+/**
+ * Parse Claude /usage command output into structured data
+ * Expected format sections:
+ * "Current session ████▌ 9% used Resets 11:59pm"
+ * "Current week (all models) 79% used Resets Nov 1, 10:59am"
+ * "Current week (Opus) 0% used"
+ */
+export function parseUsageOutput(usageOutput: string): ClaudeUsageData {
+  const sections = usageOutput.split(/Current\s+/i).filter(Boolean);
+  const usage: ClaudeUsageData = {
+    sessionUsagePercent: 0,
+    sessionResetTime: '',
+    weeklyUsagePercent: 0,
+    weeklyResetTime: '',
+    lastUpdated: new Date()
+  };
+
+  for (const section of sections) {
+    const percentMatch = section.match(USAGE_PERCENT_PATTERN);
+    const resetMatch = section.match(USAGE_RESET_PATTERN);
+
+    if (percentMatch) {
+      const percent = parseInt(percentMatch[1], 10);
+      const resetTime = resetMatch?.[1]?.trim() || '';
+
+      if (/session/i.test(section)) {
+        usage.sessionUsagePercent = percent;
+        usage.sessionResetTime = resetTime;
+      } else if (/week.*all\s*model/i.test(section)) {
+        usage.weeklyUsagePercent = percent;
+        usage.weeklyResetTime = resetTime;
+      } else if (/week.*opus/i.test(section)) {
+        usage.opusUsagePercent = percent;
+      }
+    }
+  }
+
+  return usage;
+}
@@ -0,0 +1,586 @@
+/**
+ * Docker & FalkorDB Service
+ *
+ * Provides automatic detection and management of Docker and FalkorDB
+ * for non-technical users. This eliminates the need for manual
+ * "docker --version" verification steps.
+ */
+
+import { exec, spawn } from 'child_process';
+import { promisify } from 'util';
+
+const execAsync = promisify(exec);
+
+// FalkorDB container configuration
+const FALKORDB_CONTAINER_NAME = 'auto-claude-falkordb';
+const FALKORDB_IMAGE = 'falkordb/falkordb:latest';
+const FALKORDB_DEFAULT_PORT = 6380;
+
+export interface DockerStatus {
+  installed: boolean;
+  running: boolean;
+  version?: string;
+  error?: string;
+}
+
+export interface FalkorDBStatus {
+  containerExists: boolean;
+  containerRunning: boolean;
+  containerName: string;
+  port: number;
+  healthy: boolean;
+  error?: string;
+}
+
+export interface InfrastructureStatus {
+  docker: DockerStatus;
+  falkordb: FalkorDBStatus;
+  ready: boolean; // True if both Docker is running and FalkorDB is healthy
+}
+
+/**
+ * Check if Docker is installed and running
+ */
+export async function checkDockerStatus(): Promise<DockerStatus> {
+  try {
+    // Check if Docker CLI is available
+    const { stdout: versionOutput } = await execAsync('docker --version', {
+      timeout: 5000,
+    });
+
+    const version = versionOutput.trim();
+
+    // Check if Docker daemon is running by trying to ping it
+    try {
+      await execAsync('docker info', { timeout: 10000 });
+      return {
+        installed: true,
+        running: true,
+        version,
+      };
+    } catch {
+      return {
+        installed: true,
+        running: false,
+        version,
+        error: 'Docker is installed but not running. Please start Docker Desktop.',
+      };
+    }
+  } catch (error) {
+    const errorMsg = error instanceof Error ? error.message : String(error);
+
+    // Check if it's a "command not found" type error
+    if (
+      errorMsg.includes('not found') ||
+      errorMsg.includes('ENOENT') ||
+      errorMsg.includes('not recognized')
+    ) {
+      return {
+        installed: false,
+        running: false,
+        error: 'Docker is not installed. Please install Docker Desktop.',
+      };
+    }
+
+    return {
+      installed: false,
+      running: false,
+      error: `Docker check failed: ${errorMsg}`,
+    };
+  }
+}
+
+/**
+ * Get the actual port mapping for the FalkorDB container from Docker
+ */
+async function getContainerPortMapping(): Promise<number | null> {
+  try {
+    // Get the port mapping from Docker - format: "0.0.0.0:6380->6379/tcp"
+    const { stdout } = await execAsync(
+      `docker port ${FALKORDB_CONTAINER_NAME} 6379`,
+      { timeout: 5000 }
+    );
+
+    const portMatch = stdout.trim().match(/:(\d+)/);
+    if (portMatch) {
+      return parseInt(portMatch[1], 10);
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check FalkorDB container status
+ */
+export async function checkFalkorDBStatus(port: number = FALKORDB_DEFAULT_PORT): Promise<FalkorDBStatus> {
+  const status: FalkorDBStatus = {
+    containerExists: false,
+    containerRunning: false,
+    containerName: FALKORDB_CONTAINER_NAME,
+    port,
+    healthy: false,
+  };
+
+  try {
+    // Check if container exists and get its status
+    const { stdout } = await execAsync(
+      `docker ps -a --filter "name=${FALKORDB_CONTAINER_NAME}" --format "{{.Status}}"`,
+      { timeout: 5000 }
+    );
+
+    const containerStatus = stdout.trim();
+
+    if (containerStatus) {
+      status.containerExists = true;
+      status.containerRunning = containerStatus.toLowerCase().startsWith('up');
+
+      if (status.containerRunning) {
+        // Get the actual port mapping from Docker
+        const actualPort = await getContainerPortMapping();
+        if (actualPort) {
+          status.port = actualPort;
+        }
+
+        // Check if FalkorDB is responding
+        status.healthy = await checkFalkorDBHealth(status.port);
+      }
+    }
+
+    return status;
+  } catch (error) {
+    status.error = error instanceof Error ? error.message : String(error);
+    return status;
+  }
+}
+
+/**
+ * Check if FalkorDB is responding to connections
+ */
+async function checkFalkorDBHealth(port: number): Promise<boolean> {
+  try {
+    // Try to ping FalkorDB using redis-cli (FalkorDB uses Redis protocol)
+    // Since we may not have redis-cli, we'll check if the port is listening
+    await execAsync(`docker exec ${FALKORDB_CONTAINER_NAME} redis-cli PING`, {
+      timeout: 5000,
+    });
+    return true;
+  } catch {
+    // Fallback: just check if container is running (less accurate)
+    return false;
+  }
+}
+
+/**
+ * Get combined infrastructure status
+ */
+export async function getInfrastructureStatus(
+  falkordbPort: number = FALKORDB_DEFAULT_PORT
+): Promise<InfrastructureStatus> {
+  const [docker, falkordb] = await Promise.all([
+    checkDockerStatus(),
+    checkFalkorDBStatus(falkordbPort),
+  ]);
+
+  return {
+    docker,
+    falkordb,
+    ready: docker.running && falkordb.containerRunning && falkordb.healthy,
+  };
+}
+
+/**
+ * Start FalkorDB container
+ * Creates a new container if it doesn't exist, or starts the existing one
+ */
+export async function startFalkorDB(
+  port: number = FALKORDB_DEFAULT_PORT
+): Promise<{ success: boolean; error?: string }> {
+  try {
+    // First, check Docker status
+    const dockerStatus = await checkDockerStatus();
+    if (!dockerStatus.running) {
+      return {
+        success: false,
+        error: dockerStatus.error || 'Docker is not running',
+      };
+    }
+
+    // Check if container already exists
+    const falkordbStatus = await checkFalkorDBStatus(port);
+
+    if (falkordbStatus.containerExists) {
+      if (falkordbStatus.containerRunning) {
+        // Already running
+        return { success: true };
+      }
+
+      // Start existing container
+      await execAsync(`docker start ${FALKORDB_CONTAINER_NAME}`, { timeout: 30000 });
+    } else {
+      // Create and start new container
+      await execAsync(
+        `docker run -d --name ${FALKORDB_CONTAINER_NAME} -p ${port}:6379 ${FALKORDB_IMAGE}`,
+        { timeout: 60000 }
+      );
+    }
+
+    // Wait for FalkorDB to be ready (up to 30 seconds)
+    const ready = await waitForFalkorDB(port, 30000);
+
+    if (!ready) {
+      return {
+        success: false,
+        error: 'FalkorDB container started but is not responding. Please check Docker logs.',
+      };
+    }
+
+    return { success: true };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+/**
+ * Stop FalkorDB container
+ */
+export async function stopFalkorDB(): Promise<{ success: boolean; error?: string }> {
+  try {
+    await execAsync(`docker stop ${FALKORDB_CONTAINER_NAME}`, { timeout: 30000 });
+    return { success: true };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+/**
+ * Wait for FalkorDB to be ready
+ */
+async function waitForFalkorDB(port: number, timeoutMs: number): Promise<boolean> {
+  const startTime = Date.now();
+  const checkInterval = 1000; // Check every second
+
+  while (Date.now() - startTime < timeoutMs) {
+    const status = await checkFalkorDBStatus(port);
+    if (status.containerRunning && status.healthy) {
+      return true;
+    }
+    // If container is running but not healthy yet, wait
+    if (status.containerRunning) {
+      await new Promise((resolve) => setTimeout(resolve, checkInterval));
+    } else {
+      // Container stopped unexpectedly
+      return false;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Open Docker Desktop application (macOS/Windows)
+ */
+export async function openDockerDesktop(): Promise<{ success: boolean; error?: string }> {
+  try {
+    if (process.platform === 'darwin') {
+      // macOS
+      await execAsync('open -a Docker', { timeout: 5000 });
+    } else if (process.platform === 'win32') {
+      // Windows
+      spawn('cmd', ['/c', 'start', '', 'Docker Desktop'], {
+        detached: true,
+        stdio: 'ignore',
+      });
+    } else {
+      // Linux - Docker doesn't have a GUI, suggest starting daemon
+      return {
+        success: false,
+        error: 'On Linux, start Docker with: sudo systemctl start docker',
+      };
+    }
+
+    return { success: true };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+/**
+ * Get download URL for Docker Desktop
+ */
+export function getDockerDownloadUrl(): string {
+  if (process.platform === 'darwin') {
+    return 'https://www.docker.com/products/docker-desktop/';
+  } else if (process.platform === 'win32') {
+    return 'https://www.docker.com/products/docker-desktop/';
+  }
+  return 'https://docs.docker.com/engine/install/';
+}
+
+// ============================================
+// Graphiti Validation Functions
+// ============================================
+
+export interface GraphitiValidationResult {
+  success: boolean;
+  message: string;
+  details?: {
+    provider?: string;
+    model?: string;
+    latencyMs?: number;
+  };
+}
+
+/**
+ * Validate FalkorDB connection by attempting to connect and ping
+ * @param uri - FalkorDB URI (e.g., "bolt://localhost:6380" or "redis://localhost:6380")
+ */
+export async function validateFalkorDBConnection(
+  uri: string
+): Promise<GraphitiValidationResult> {
+  try {
+    // Parse the URI to extract host and port
+    let host = 'localhost';
+    let port = FALKORDB_DEFAULT_PORT;
+
+    // Support both bolt:// and redis:// protocols
+    const uriMatch = uri.match(/^(?:bolt|redis):\/\/([^:]+):(\d+)/);
+    if (uriMatch) {
+      host = uriMatch[1];
+      port = parseInt(uriMatch[2], 10);
+    } else {
+      // Try simple host:port format
+      const simpleMatch = uri.match(/^([^:]+):(\d+)/);
+      if (simpleMatch) {
+        host = simpleMatch[1];
+        port = parseInt(simpleMatch[2], 10);
+      }
+    }
+
+    const startTime = Date.now();
+
+    // First, check the actual FalkorDB container status to get the correct port
+    const falkorStatus = await checkFalkorDBStatus(port);
+
+    // If container exists but user specified wrong port, try to detect the actual port
+    if (!falkorStatus.containerRunning) {
+      // Check if container is running on default port
+      const defaultStatus = await checkFalkorDBStatus(FALKORDB_DEFAULT_PORT);
+      if (defaultStatus.containerRunning && defaultStatus.healthy) {
+        return {
+          success: false,
+          message: `FalkorDB is running on port ${FALKORDB_DEFAULT_PORT}, but you specified port ${port}. Please update the URI to bolt://localhost:${FALKORDB_DEFAULT_PORT}`,
+        };
+      }
+
+      return {
+        success: false,
+        message: `FalkorDB container is not running. Please start FalkorDB first using Docker.`,
+      };
+    }
+
+    // Try to ping FalkorDB using redis-cli in Docker container
+    try {
+      const { stdout } = await execAsync(
+        `docker exec ${FALKORDB_CONTAINER_NAME} redis-cli PING`,
+        { timeout: 10000 }
+      );
+
+      if (stdout.trim().toUpperCase() === 'PONG') {
+        const latencyMs = Date.now() - startTime;
+        return {
+          success: true,
+          message: `Connected to FalkorDB at ${host}:${port}`,
+          details: { latencyMs },
+        };
+      }
+    } catch {
+      // redis-cli failed, try port check as fallback
+    }
+
+    // Fallback: check if the port is open using nc or direct connection
+    try {
+      // Check if we can connect to the mapped port from the host
+      await execAsync(`nc -z -w 5 ${host} ${port}`, { timeout: 10000 });
+      const latencyMs = Date.now() - startTime;
+      return {
+        success: true,
+        message: `FalkorDB port ${port} is reachable at ${host}`,
+        details: { latencyMs },
+      };
+    } catch {
+      // Port check failed, but container is running - might be a different port mapping
+      if (falkorStatus.containerRunning) {
+        return {
+          success: false,
+          message: `FalkorDB container is running but port ${port} is not reachable. The container may be mapped to a different port.`,
+        };
+      }
+
+      return {
+        success: false,
+        message: `Cannot connect to FalkorDB at ${host}:${port}. Make sure FalkorDB is running.`,
+      };
+    }
+  } catch (error) {
+    return {
+      success: false,
+      message: error instanceof Error ? error.message : 'Unknown error occurred',
+    };
+  }
+}
+
+/**
+ * Validate OpenAI API key by attempting to list models
+ * @param apiKey - OpenAI API key
+ */
+export async function validateOpenAIApiKey(
+  apiKey: string
+): Promise<GraphitiValidationResult> {
+  if (!apiKey || !apiKey.trim()) {
+    return {
+      success: false,
+      message: 'API key is required',
+    };
+  }
+
+  // Basic format validation
+  const trimmedKey = apiKey.trim();
+  if (!trimmedKey.startsWith('sk-') && !trimmedKey.startsWith('sess-')) {
+    return {
+      success: false,
+      message: 'Invalid API key format. OpenAI API keys should start with "sk-"',
+    };
+  }
+
+  try {
+    const startTime = Date.now();
+
+    // Use native https module to avoid additional dependencies
+    const result = await new Promise<GraphitiValidationResult>((resolve) => {
+      const https = require('https');
+
+      const options = {
+        hostname: 'api.openai.com',
+        port: 443,
+        path: '/v1/models',
+        method: 'GET',
+        headers: {
+          Authorization: `Bearer ${trimmedKey}`,
+          'Content-Type': 'application/json',
+        },
+        timeout: 15000,
+      };
+
+      const req = https.request(options, (res: any) => {
+        let data = '';
+
+        res.on('data', (chunk: any) => {
+          data += chunk;
+        });
+
+        res.on('end', () => {
+          const latencyMs = Date.now() - startTime;
+
+          if (res.statusCode === 200) {
+            resolve({
+              success: true,
+              message: 'OpenAI API key is valid',
+              details: {
+                provider: 'openai',
+                latencyMs,
+              },
+            });
+          } else if (res.statusCode === 401) {
+            resolve({
+              success: false,
+              message: 'Invalid API key. Please check your OpenAI API key.',
+            });
+          } else if (res.statusCode === 429) {
+            // Rate limited but key is valid
+            resolve({
+              success: true,
+              message: 'OpenAI API key is valid (rate limited, please wait)',
+              details: {
+                provider: 'openai',
+                latencyMs,
+              },
+            });
+          } else {
+            try {
+              const errorData = JSON.parse(data);
+              resolve({
+                success: false,
+                message: errorData.error?.message || `API error: ${res.statusCode}`,
+              });
+            } catch {
+              resolve({
+                success: false,
+                message: `API error: ${res.statusCode}`,
+              });
+            }
+          }
+        });
+      });
+
+      req.on('error', (error: any) => {
+        resolve({
+          success: false,
+          message: `Connection error: ${error.message}`,
+        });
+      });
+
+      req.on('timeout', () => {
+        req.destroy();
+        resolve({
+          success: false,
+          message: 'Connection timeout. Please check your network connection.',
+        });
+      });
+
+      req.end();
+    });
+
+    return result;
+  } catch (error) {
+    return {
+      success: false,
+      message: error instanceof Error ? error.message : 'Unknown error occurred',
+    };
+  }
+}
+
+/**
+ * Test the full Graphiti connection (FalkorDB + OpenAI)
+ * @param falkorDbUri - FalkorDB URI
+ * @param openAiApiKey - OpenAI API key
+ */
+export async function testGraphitiConnection(
+  falkorDbUri: string,
+  openAiApiKey: string
+): Promise<{
+  falkordb: GraphitiValidationResult;
+  openai: GraphitiValidationResult;
+  ready: boolean;
+}> {
+  const [falkordb, openai] = await Promise.all([
+    validateFalkorDBConnection(falkorDbUri),
+    validateOpenAIApiKey(openAiApiKey),
+  ]);
+
+  return {
+    falkordb,
+    openai,
+    ready: falkordb.success && openai.success,
+  };
+}
@@ -0,0 +1,365 @@
+/**
+ * FalkorDB Service
+ *
+ * Queries the FalkorDB graph database for memories stored by Graphiti.
+ * Uses ioredis to communicate with FalkorDB via Redis protocol.
+ */
+
+import Redis from 'ioredis';
+import type { MemoryEpisode } from '../shared/types';
+
+interface FalkorDBConfig {
+  host: string;
+  port: number;
+  password?: string;
+}
+
+interface EpisodicNode {
+  uuid: string;
+  name: string;
+  created_at: string;
+  content?: string;
+  source_description?: string;
+}
+
+interface EntityNode {
+  uuid: string;
+  name: string;
+  summary?: string;
+}
+
+/**
+ * Parse FalkorDB GRAPH.QUERY results into structured data
+ */
+function parseGraphResult(result: unknown[]): Record<string, unknown>[] {
+  if (!Array.isArray(result) || result.length < 2) {
+    return [];
+  }
+
+  // Result format: [headers, [row1, row2, ...], stats]
+  const headers = result[0] as string[];
+  const rows = result[1] as unknown[][];
+
+  if (!Array.isArray(headers) || !Array.isArray(rows)) {
+    return [];
+  }
+
+  return rows.map(row => {
+    const obj: Record<string, unknown> = {};
+    headers.forEach((header, idx) => {
+      obj[header] = row[idx];
+    });
+    return obj;
+  });
+}
+
+/**
+ * FalkorDB Service for querying graph memories
+ */
+export class FalkorDBService {
+  private config: FalkorDBConfig;
+  private redis: Redis | null = null;
+
+  constructor(config: FalkorDBConfig) {
+    this.config = config;
+  }
+
+  /**
+   * Get a Redis connection (lazy initialization)
+   */
+  private async getConnection(): Promise<Redis> {
+    if (this.redis) {
+      return this.redis;
+    }
+
+    this.redis = new Redis({
+      host: this.config.host,
+      port: this.config.port,
+      password: this.config.password,
+      lazyConnect: true,
+      connectTimeout: 5000,
+      maxRetriesPerRequest: 1,
+    });
+
+    await this.redis.connect();
+    return this.redis;
+  }
+
+  /**
+   * Close the Redis connection
+   */
+  async close(): Promise<void> {
+    if (this.redis) {
+      await this.redis.quit();
+      this.redis = null;
+    }
+  }
+
+  /**
+   * List all available graphs in the database
+   */
+  async listGraphs(): Promise<string[]> {
+    try {
+      const redis = await this.getConnection();
+      const result = await redis.call('GRAPH.LIST') as string[];
+      return result || [];
+    } catch (error) {
+      console.error('Failed to list graphs:', error);
+      return [];
+    }
+  }
+
+  /**
+   * Query episodic memories from a specific graph
+   */
+  async getEpisodicMemories(graphName: string, limit: number = 20): Promise<MemoryEpisode[]> {
+    try {
+      const redis = await this.getConnection();
+
+      // Query episodic nodes with their details
+      const query = `
+        MATCH (e:Episodic)
+        RETURN e.uuid as uuid, e.name as name, e.created_at as created_at,
+               e.content as content, e.source_description as description
+        ORDER BY e.created_at DESC
+        LIMIT ${limit}
+      `;
+
+      const result = await redis.call('GRAPH.QUERY', graphName, query) as unknown[];
+      const episodes = parseGraphResult(result) as unknown as EpisodicNode[];
+
+      return episodes.map(ep => ({
+        id: ep.uuid || ep.name,
+        type: this.inferEpisodeType(ep.name, ep.content),
+        timestamp: ep.created_at || new Date().toISOString(),
+        content: ep.content || ep.source_description || ep.name,
+        session_number: this.extractSessionNumber(ep.name),
+      }));
+    } catch (error) {
+      console.error(`Failed to get episodic memories from ${graphName}:`, error);
+      return [];
+    }
+  }
+
+  /**
+   * Query entity memories (patterns, gotchas, etc.) from a graph
+   */
+  async getEntityMemories(graphName: string, limit: number = 20): Promise<MemoryEpisode[]> {
+    try {
+      const redis = await this.getConnection();
+
+      // Query entity nodes
+      const query = `
+        MATCH (e:Entity)
+        RETURN e.uuid as uuid, e.name as name, e.summary as summary, e.created_at as created_at
+        ORDER BY e.created_at DESC
+        LIMIT ${limit}
+      `;
+
+      const result = await redis.call('GRAPH.QUERY', graphName, query) as unknown[];
+      const entities = parseGraphResult(result) as unknown as EntityNode[];
+
+      return entities
+        .filter(ent => ent.summary) // Only include entities with summaries
+        .map(ent => ({
+          id: ent.uuid || ent.name,
+          type: this.inferEntityType(ent.name),
+          timestamp: new Date().toISOString(),
+          content: ent.summary || ent.name,
+        }));
+    } catch (error) {
+      console.error(`Failed to get entity memories from ${graphName}:`, error);
+      return [];
+    }
+  }
+
+  /**
+   * Get all memories from all spec-related graphs
+   */
+  async getAllMemories(limit: number = 20): Promise<MemoryEpisode[]> {
+    const graphs = await this.listGraphs();
+    const memories: MemoryEpisode[] = [];
+
+    // Filter to spec-related graphs (exclude auto_build_memory and project_ prefixed)
+    const specGraphs = graphs.filter(g =>
+      !g.startsWith('project_') &&
+      g !== 'auto_build_memory' &&
+      g !== 'default_db'
+    );
+
+    for (const graph of specGraphs) {
+      const episodic = await this.getEpisodicMemories(graph, Math.ceil(limit / specGraphs.length));
+      memories.push(...episodic.map(m => ({ ...m, id: `${graph}:${m.id}` })));
+    }
+
+    // Sort by timestamp descending
+    memories.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
+
+    return memories.slice(0, limit);
+  }
+
+  /**
+   * Search memories across all graphs
+   */
+  async searchMemories(query: string, limit: number = 20): Promise<MemoryEpisode[]> {
+    const graphs = await this.listGraphs();
+    const results: MemoryEpisode[] = [];
+    const queryLower = query.toLowerCase();
+
+    // Filter to spec-related graphs
+    const specGraphs = graphs.filter(g =>
+      !g.startsWith('project_') &&
+      g !== 'auto_build_memory' &&
+      g !== 'default_db'
+    );
+
+    for (const graph of specGraphs) {
+      try {
+        const redis = await this.getConnection();
+
+        // Search in episodic nodes
+        const episodicQuery = `
+          MATCH (e:Episodic)
+          WHERE toLower(e.name) CONTAINS '${queryLower}' OR toLower(e.content) CONTAINS '${queryLower}'
+          RETURN e.uuid as uuid, e.name as name, e.created_at as created_at,
+                 e.content as content, e.source_description as description
+          LIMIT ${Math.ceil(limit / specGraphs.length)}
+        `;
+
+        const episodicResult = await redis.call('GRAPH.QUERY', graph, episodicQuery) as unknown[];
+        const episodes = parseGraphResult(episodicResult) as unknown as EpisodicNode[];
+
+        results.push(...episodes.map(ep => ({
+          id: `${graph}:${ep.uuid || ep.name}`,
+          type: this.inferEpisodeType(ep.name, ep.content),
+          timestamp: ep.created_at || new Date().toISOString(),
+          content: ep.content || ep.source_description || ep.name,
+          session_number: this.extractSessionNumber(ep.name),
+          score: 1.0,
+        })));
+
+        // Search in entity nodes
+        const entityQuery = `
+          MATCH (e:Entity)
+          WHERE toLower(e.name) CONTAINS '${queryLower}' OR toLower(e.summary) CONTAINS '${queryLower}'
+          RETURN e.uuid as uuid, e.name as name, e.summary as summary
+          LIMIT ${Math.ceil(limit / specGraphs.length)}
+        `;
+
+        const entityResult = await redis.call('GRAPH.QUERY', graph, entityQuery) as unknown[];
+        const entities = parseGraphResult(entityResult) as unknown as EntityNode[];
+
+        results.push(...entities
+          .filter(ent => ent.summary)
+          .map(ent => ({
+            id: `${graph}:${ent.uuid || ent.name}`,
+            type: this.inferEntityType(ent.name),
+            timestamp: new Date().toISOString(),
+            content: ent.summary || ent.name,
+            score: 1.0,
+          })));
+      } catch (error) {
+        console.error(`Failed to search memories in ${graph}:`, error);
+      }
+    }
+
+    return results.slice(0, limit);
+  }
+
+  /**
+   * Test connection to FalkorDB
+   */
+  async testConnection(): Promise<{ success: boolean; message: string }> {
+    try {
+      const redis = await this.getConnection();
+      await redis.ping();
+      const graphs = await this.listGraphs();
+      return {
+        success: true,
+        message: `Connected to FalkorDB with ${graphs.length} graphs`,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        message: error instanceof Error ? error.message : 'Connection failed',
+      };
+    }
+  }
+
+  /**
+   * Infer the episode type from its name
+   */
+  private inferEpisodeType(name: string, content?: string): MemoryEpisode['type'] {
+    const nameLower = (name || '').toLowerCase();
+    const contentLower = (content || '').toLowerCase();
+
+    if (nameLower.includes('session_') || contentLower.includes('"type": "session_insight"')) {
+      return 'session_insight';
+    }
+    if (nameLower.includes('pattern') || contentLower.includes('"type": "pattern"')) {
+      return 'pattern';
+    }
+    if (nameLower.includes('gotcha') || contentLower.includes('"type": "gotcha"')) {
+      return 'gotcha';
+    }
+    if (nameLower.includes('codebase') || contentLower.includes('"type": "codebase_discovery"')) {
+      return 'codebase_discovery';
+    }
+    return 'session_insight';
+  }
+
+  /**
+   * Infer the entity type from its name
+   */
+  private inferEntityType(name: string): MemoryEpisode['type'] {
+    const nameLower = (name || '').toLowerCase();
+
+    if (nameLower.includes('pattern')) {
+      return 'pattern';
+    }
+    if (nameLower.includes('gotcha')) {
+      return 'gotcha';
+    }
+    if (nameLower.includes('file_insight') || nameLower.includes('codebase')) {
+      return 'codebase_discovery';
+    }
+    return 'session_insight';
+  }
+
+  /**
+   * Extract session number from episode name
+   */
+  private extractSessionNumber(name: string): number | undefined {
+    const match = name.match(/session_(\d+)/i);
+    return match ? parseInt(match[1], 10) : undefined;
+  }
+}
+
+// Singleton instance for reuse
+let serviceInstance: FalkorDBService | null = null;
+
+/**
+ * Get or create a FalkorDB service instance
+ */
+export function getFalkorDBService(config: FalkorDBConfig): FalkorDBService {
+  if (!serviceInstance ||
+      serviceInstance['config'].host !== config.host ||
+      serviceInstance['config'].port !== config.port) {
+    // Close existing connection if config changed
+    if (serviceInstance) {
+      serviceInstance.close().catch(() => {});
+    }
+    serviceInstance = new FalkorDBService(config);
+  }
+  return serviceInstance;
+}
+
+/**
+ * Close the singleton service instance
+ */
+export async function closeFalkorDBService(): Promise<void> {
+  if (serviceInstance) {
+    await serviceInstance.close();
+    serviceInstance = null;
+  }
+}
@@ -5,6 +5,8 @@ import { setupIpcHandlers } from './ipc-setup';
 import { AgentManager } from './agent';
 import { TerminalManager } from './terminal-manager';
 import { pythonEnvManager } from './python-env-manager';
+import { getUsageMonitor } from './claude-profile/usage-monitor';
+import { initializeUsageMonitorForwarding } from './ipc-handlers/terminal-handlers';

 // Get icon path based on platform
 function getIconPath(): string {
@@ -49,7 +51,8 @@ function createWindow(): void {
      preload: join(__dirname, '../preload/index.js'),
      sandbox: false,
      contextIsolation: true,
-      nodeIntegration: false
+      nodeIntegration: false,
+      backgroundThrottling: false // Prevent terminal lag when window loses focus
    }
  });

@@ -125,6 +128,17 @@ app.whenReady().then(() => {
  // Create window
  createWindow();

+  // Initialize usage monitoring after window is created
+  if (mainWindow) {
+    // Setup event forwarding from usage monitor to renderer
+    initializeUsageMonitorForwarding(mainWindow);
+
+    // Start the usage monitor
+    const usageMonitor = getUsageMonitor();
+    usageMonitor.start();
+    console.log('[main] Usage monitor initialized and started');
+  }
+
  // macOS: re-create window when dock icon is clicked
  app.on('activate', () => {
    if (BrowserWindow.getAllWindows().length === 0) {
@@ -142,6 +156,11 @@ app.on('window-all-closed', () => {

 // Cleanup before quit
 app.on('before-quit', async () => {
+  // Stop usage monitor
+  const usageMonitor = getUsageMonitor();
+  usageMonitor.stop();
+  console.log('[main] Usage monitor stopped');
+
  // Kill all running agent processes
  if (agentManager) {
    await agentManager.killAll();
@@ -1,9 +1,4 @@
 import { EventEmitter } from 'events';
-import path from 'path';
-import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, unlinkSync } from 'fs';
-import { spawn, ChildProcess } from 'child_process';
-import { app } from 'electron';
-import { detectRateLimit, createSDKRateLimitInfo, getProfileEnv } from './rate-limit-detector';
 import type {
  InsightsSession,
  InsightsSessionSummary,
@@ -12,448 +7,133 @@ import type {
  InsightsStreamChunk,
  InsightsToolUsage
 } from '../shared/types';
-
-const INSIGHTS_DIR = '.auto-claude/insights';
-const SESSIONS_DIR = 'sessions';
-const CURRENT_SESSION_FILE = 'current_session.json';
+import { InsightsConfig } from './insights/config';
+import { InsightsPaths } from './insights/paths';
+import { SessionStorage } from './insights/session-storage';
+import { SessionManager } from './insights/session-manager';
+import { InsightsExecutor } from './insights/insights-executor';

 /**
 * Service for AI-powered codebase insights chat
+ *
+ * This service coordinates between multiple specialized modules:
+ * - InsightsConfig: Manages configuration and environment
+ * - InsightsPaths: Provides consistent path resolution
+ * - SessionStorage: Handles filesystem persistence
+ * - SessionManager: Manages session lifecycle and cache
+ * - InsightsExecutor: Executes Python insights runner
 */
 export class InsightsService extends EventEmitter {
-  private pythonPath: string = 'python3';
-  private autoBuildSourcePath: string = '';
-  private activeSessions: Map<string, ChildProcess> = new Map();
-  private sessions: Map<string, InsightsSession> = new Map();
+  private config: InsightsConfig;
+  private paths: InsightsPaths;
+  private storage: SessionStorage;
+  private sessionManager: SessionManager;
+  private executor: InsightsExecutor;

  constructor() {
    super();
+
+    // Initialize modules
+    this.config = new InsightsConfig();
+    this.paths = new InsightsPaths();
+    this.storage = new SessionStorage(this.paths);
+    this.sessionManager = new SessionManager(this.storage, this.paths);
+    this.executor = new InsightsExecutor(this.config);
+
+    // Forward executor events
+    this.executor.on('status', (projectId, status) => {
+      this.emit('status', projectId, status);
+    });
+    this.executor.on('stream-chunk', (projectId, chunk) => {
+      this.emit('stream-chunk', projectId, chunk);
+    });
+    this.executor.on('error', (projectId, error) => {
+      this.emit('error', projectId, error);
+    });
+    this.executor.on('sdk-rate-limit', (info) => {
+      this.emit('sdk-rate-limit', info);
+    });
  }

  /**
   * Configure paths for Python and auto-claude source
   */
  configure(pythonPath?: string, autoBuildSourcePath?: string): void {
-    if (pythonPath) {
-      this.pythonPath = pythonPath;
-    }
-    if (autoBuildSourcePath) {
-      this.autoBuildSourcePath = autoBuildSourcePath;
-    }
+    this.config.configure(pythonPath, autoBuildSourcePath);
  }

  /**
-   * Get the auto-claude source path (detects automatically if not configured)
-   */
-  private getAutoBuildSourcePath(): string | null {
-    if (this.autoBuildSourcePath && existsSync(this.autoBuildSourcePath)) {
-      return this.autoBuildSourcePath;
-    }
-
-    const possiblePaths = [
-      path.resolve(__dirname, '..', '..', '..', 'auto-claude'),
-      path.resolve(app.getAppPath(), '..', 'auto-claude'),
-      path.resolve(process.cwd(), 'auto-claude')
-    ];
-
-    for (const p of possiblePaths) {
-      if (existsSync(p) && existsSync(path.join(p, 'VERSION'))) {
-        return p;
-      }
-    }
-    return null;
-  }
-
-  /**
-   * Load environment variables from auto-claude .env file
-   */
-  private loadAutoBuildEnv(): Record<string, string> {
-    const autoBuildSource = this.getAutoBuildSourcePath();
-    if (!autoBuildSource) return {};
-
-    const envPath = path.join(autoBuildSource, '.env');
-    if (!existsSync(envPath)) return {};
-
-    try {
-      const envContent = readFileSync(envPath, 'utf-8');
-      const envVars: Record<string, string> = {};
-
-      // Handle both Unix (\n) and Windows (\r\n) line endings
-      for (const line of envContent.split(/\r?\n/)) {
-        const trimmed = line.trim();
-        if (!trimmed || trimmed.startsWith('#')) continue;
-
-        const eqIndex = trimmed.indexOf('=');
-        if (eqIndex > 0) {
-          const key = trimmed.substring(0, eqIndex).trim();
-          let value = trimmed.substring(eqIndex + 1).trim();
-
-          if ((value.startsWith('"') && value.endsWith('"')) ||
-              (value.startsWith("'") && value.endsWith("'"))) {
-            value = value.slice(1, -1);
-          }
-
-          envVars[key] = value;
-        }
-      }
-
-      return envVars;
-    } catch {
-      return {};
-    }
-  }
-
-  /**
-   * Get insights directory path for a project
-   */
-  private getInsightsDir(projectPath: string): string {
-    return path.join(projectPath, INSIGHTS_DIR);
-  }
-
-  /**
-   * Get sessions directory path for a project
-   */
-  private getSessionsDir(projectPath: string): string {
-    return path.join(this.getInsightsDir(projectPath), SESSIONS_DIR);
-  }
-
-  /**
-   * Get session file path for a specific session
-   */
-  private getSessionPath(projectPath: string, sessionId: string): string {
-    return path.join(this.getSessionsDir(projectPath), `${sessionId}.json`);
-  }
-
-  /**
-   * Get current session pointer file path
-   */
-  private getCurrentSessionPath(projectPath: string): string {
-    return path.join(this.getInsightsDir(projectPath), CURRENT_SESSION_FILE);
-  }
-
-  /**
-   * Generate a title from the first user message
-   */
-  private generateTitle(message: string): string {
-    // Truncate to first 50 characters and clean up
-    const title = message.trim().replace(/\n/g, ' ').slice(0, 50);
-    return title.length < message.trim().length ? `${title}...` : title;
-  }
-
-  /**
-   * Migrate old session format to new multi-session format
-   */
-  private migrateOldSession(projectPath: string): void {
-    const oldSessionPath = path.join(this.getInsightsDir(projectPath), 'session.json');
-    if (!existsSync(oldSessionPath)) return;
-
-    try {
-      const content = readFileSync(oldSessionPath, 'utf-8');
-      const oldSession = JSON.parse(content) as InsightsSession;
-
-      // Only migrate if it has messages
-      if (oldSession.messages && oldSession.messages.length > 0) {
-        // Ensure sessions directory exists
-        const sessionsDir = this.getSessionsDir(projectPath);
-        if (!existsSync(sessionsDir)) {
-          mkdirSync(sessionsDir, { recursive: true });
-        }
-
-        // Generate title from first user message
-        const firstUserMessage = oldSession.messages.find(m => m.role === 'user');
-        const title = firstUserMessage
-          ? this.generateTitle(firstUserMessage.content)
-          : 'Imported Conversation';
-
-        // Create new session with title
-        const newSession: InsightsSession = {
-          ...oldSession,
-          title
-        };
-
-        // Save as new session file
-        const sessionPath = this.getSessionPath(projectPath, oldSession.id);
-        writeFileSync(sessionPath, JSON.stringify(newSession, null, 2));
-
-        // Set as current session
-        this.saveCurrentSessionId(projectPath, oldSession.id);
-      }
-
-      // Remove old session file
-      unlinkSync(oldSessionPath);
-    } catch {
-      // Ignore migration errors
-    }
-  }
-
-  /**
-   * Get current session ID for a project
-   */
-  private getCurrentSessionId(projectPath: string): string | null {
-    // Migrate old format if needed
-    this.migrateOldSession(projectPath);
-
-    const currentPath = this.getCurrentSessionPath(projectPath);
-    if (!existsSync(currentPath)) return null;
-
-    try {
-      const content = readFileSync(currentPath, 'utf-8');
-      const data = JSON.parse(content);
-      return data.currentSessionId || null;
-    } catch {
-      return null;
-    }
-  }
-
-  /**
-   * Save current session ID pointer
-   */
-  private saveCurrentSessionId(projectPath: string, sessionId: string): void {
-    const insightsDir = this.getInsightsDir(projectPath);
-    if (!existsSync(insightsDir)) {
-      mkdirSync(insightsDir, { recursive: true });
-    }
-
-    const currentPath = this.getCurrentSessionPath(projectPath);
-    writeFileSync(currentPath, JSON.stringify({ currentSessionId: sessionId }, null, 2));
-  }
-
-  /**
-   * Load a specific session from disk
-   */
-  private loadSessionById(projectPath: string, sessionId: string): InsightsSession | null {
-    const sessionPath = this.getSessionPath(projectPath, sessionId);
-    if (!existsSync(sessionPath)) return null;
-
-    try {
-      const content = readFileSync(sessionPath, 'utf-8');
-      const session = JSON.parse(content) as InsightsSession;
-      // Convert date strings back to Date objects
-      session.createdAt = new Date(session.createdAt);
-      session.updatedAt = new Date(session.updatedAt);
-      session.messages = session.messages.map(m => ({
-        ...m,
-        timestamp: new Date(m.timestamp),
-        // Convert toolsUsed timestamps if present
-        toolsUsed: m.toolsUsed?.map(t => ({
-          ...t,
-          timestamp: new Date(t.timestamp)
-        }))
-      }));
-      return session;
-    } catch {
-      return null;
-    }
-  }
-
-  /**
-   * Load current session from disk
+   * Load current session from disk or cache
   */
  loadSession(projectId: string, projectPath: string): InsightsSession | null {
-    // Check in-memory cache first
-    if (this.sessions.has(projectId)) {
-      return this.sessions.get(projectId)!;
-    }
-
-    const currentSessionId = this.getCurrentSessionId(projectPath);
-    if (!currentSessionId) return null;
-
-    const session = this.loadSessionById(projectPath, currentSessionId);
-    if (session) {
-      this.sessions.set(projectId, session);
-    }
-    return session;
+    return this.sessionManager.loadSession(projectId, projectPath);
  }

  /**
   * List all sessions for a project
   */
  listSessions(projectPath: string): InsightsSessionSummary[] {
-    // Migrate old format if needed
-    this.migrateOldSession(projectPath);
-
-    const sessionsDir = this.getSessionsDir(projectPath);
-    if (!existsSync(sessionsDir)) return [];
-
-    try {
-      const files = readdirSync(sessionsDir).filter(f => f.endsWith('.json'));
-      const sessions: InsightsSessionSummary[] = [];
-
-      for (const file of files) {
-        try {
-          const content = readFileSync(path.join(sessionsDir, file), 'utf-8');
-          const session = JSON.parse(content) as InsightsSession;
-
-          // Generate title if not present
-          let title = session.title;
-          if (!title && session.messages.length > 0) {
-            const firstUserMessage = session.messages.find(m => m.role === 'user');
-            title = firstUserMessage
-              ? this.generateTitle(firstUserMessage.content)
-              : 'Untitled Conversation';
-          }
-
-          sessions.push({
-            id: session.id,
-            projectId: session.projectId,
-            title: title || 'New Conversation',
-            messageCount: session.messages.length,
-            createdAt: new Date(session.createdAt),
-            updatedAt: new Date(session.updatedAt)
-          });
-        } catch {
-          // Skip invalid session files
-        }
-      }
-
-      // Sort by updatedAt descending (most recent first)
-      return sessions.sort((a, b) =>
-        new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime()
-      );
-    } catch {
-      return [];
-    }
+    return this.sessionManager.listSessions(projectPath);
  }

  /**
   * Create a new session
   */
  createNewSession(projectId: string, projectPath: string): InsightsSession {
-    const sessionId = `session-${Date.now()}`;
-    const session: InsightsSession = {
-      id: sessionId,
-      projectId,
-      title: 'New Conversation',
-      messages: [],
-      createdAt: new Date(),
-      updatedAt: new Date()
-    };
-
-    // Ensure sessions directory exists
-    const sessionsDir = this.getSessionsDir(projectPath);
-    if (!existsSync(sessionsDir)) {
-      mkdirSync(sessionsDir, { recursive: true });
-    }
-
-    // Save new session
-    this.saveSession(projectPath, session);
-    this.saveCurrentSessionId(projectPath, sessionId);
-    this.sessions.set(projectId, session);
-
-    return session;
+    return this.sessionManager.createNewSession(projectId, projectPath);
  }

  /**
   * Switch to a different session
   */
  switchSession(projectId: string, projectPath: string, sessionId: string): InsightsSession | null {
-    const session = this.loadSessionById(projectPath, sessionId);
-    if (session) {
-      this.saveCurrentSessionId(projectPath, sessionId);
-      this.sessions.set(projectId, session);
-    }
-    return session;
+    return this.sessionManager.switchSession(projectId, projectPath, sessionId);
  }

  /**
   * Delete a session
   */
  deleteSession(projectId: string, projectPath: string, sessionId: string): boolean {
-    const sessionPath = this.getSessionPath(projectPath, sessionId);
-    if (!existsSync(sessionPath)) return false;
-
-    try {
-      unlinkSync(sessionPath);
-
-      // If this was the current session, clear the cache
-      const currentSession = this.sessions.get(projectId);
-      if (currentSession?.id === sessionId) {
-        this.sessions.delete(projectId);
-
-        // Find another session to switch to, or create new
-        const remaining = this.listSessions(projectPath);
-        if (remaining.length > 0) {
-          this.switchSession(projectId, projectPath, remaining[0].id);
-        } else {
-          // Clear current session pointer
-          const currentPath = this.getCurrentSessionPath(projectPath);
-          if (existsSync(currentPath)) {
-            unlinkSync(currentPath);
-          }
-        }
-      }
-
-      return true;
-    } catch {
-      return false;
-    }
+    return this.sessionManager.deleteSession(projectId, projectPath, sessionId);
  }

  /**
   * Rename a session
   */
  renameSession(projectPath: string, sessionId: string, newTitle: string): boolean {
-    const session = this.loadSessionById(projectPath, sessionId);
-    if (!session) return false;
-
-    session.title = newTitle;
-    session.updatedAt = new Date();
-    this.saveSession(projectPath, session);
-    return true;
-  }
-
-  /**
-   * Save session to disk
-   */
-  private saveSession(projectPath: string, session: InsightsSession): void {
-    const sessionsDir = this.getSessionsDir(projectPath);
-    if (!existsSync(sessionsDir)) {
-      mkdirSync(sessionsDir, { recursive: true });
-    }
-
-    const sessionPath = this.getSessionPath(projectPath, session.id);
-    writeFileSync(sessionPath, JSON.stringify(session, null, 2));
-    this.sessions.set(session.projectId, session);
+    return this.sessionManager.renameSession(projectPath, sessionId, newTitle);
  }

  /**
   * Clear current session (delete messages but keep the session)
   */
  clearSession(projectId: string, projectPath: string): void {
-    const currentSession = this.sessions.get(projectId);
-    if (!currentSession) return;
-
-    // Create a fresh session with new ID
-    const newSession = this.createNewSession(projectId, projectPath);
-    this.sessions.set(projectId, newSession);
+    this.sessionManager.clearSession(projectId, projectPath);
  }

  /**
   * Send a message and get AI response
   */
  async sendMessage(projectId: string, projectPath: string, message: string): Promise<void> {
-    // Cancel any existing session for this project
-    if (this.activeSessions.has(projectId)) {
-      const existingProcess = this.activeSessions.get(projectId);
-      existingProcess?.kill();
-      this.activeSessions.delete(projectId);
-    }
+    // Cancel any existing session
+    this.executor.cancelSession(projectId);

-    const autoBuildSource = this.getAutoBuildSourcePath();
+    // Validate auto-claude source
+    const autoBuildSource = this.config.getAutoBuildSourcePath();
    if (!autoBuildSource) {
      this.emit('error', projectId, 'Auto Claude source not found');
      return;
    }

    // Load or create session
-    let session = this.loadSession(projectId, projectPath);
+    let session = this.sessionManager.loadSession(projectId, projectPath);
    if (!session) {
-      session = this.createNewSession(projectId, projectPath);
+      session = this.sessionManager.createNewSession(projectId, projectPath);
    }

    // Auto-generate title from first user message if still default
    if (session.messages.length === 0 && session.title === 'New Conversation') {
-      session.title = this.generateTitle(message);
+      session.title = this.storage.generateTitle(message);
    }

    // Add user message
@@ -465,16 +145,7 @@ export class InsightsService extends EventEmitter {
    };
    session.messages.push(userMessage);
    session.updatedAt = new Date();
-    this.saveSession(projectPath, session);
-
-    // Emit thinking status
-    this.emit('status', projectId, {
-      phase: 'thinking',
-      message: 'Processing your message...'
-    } as InsightsChatStatus);
-
-    // Load environment
-    const envVars = this.loadAutoBuildEnv();
+    this.sessionManager.saveSession(projectPath, session);

    // Build conversation history for context
    const conversationHistory = session.messages.map(m => ({
@@ -482,177 +153,33 @@ export class InsightsService extends EventEmitter {
      content: m.content
    }));

-    // Create the insights runner script path
-    const runnerPath = path.join(autoBuildSource, 'insights_runner.py');
+    try {
+      // Execute insights query
+      const result = await this.executor.execute(
+        projectId,
+        projectPath,
+        message,
+        conversationHistory
+      );

-    // Check if runner exists
-    if (!existsSync(runnerPath)) {
-      this.emit('error', projectId, 'insights_runner.py not found in auto-claude directory');
-      return;
+      // Add assistant message to session
+      const assistantMessage: InsightsChatMessage = {
+        id: `msg-${Date.now()}`,
+        role: 'assistant',
+        content: result.fullResponse,
+        timestamp: new Date(),
+        suggestedTask: result.suggestedTask,
+        toolsUsed: result.toolsUsed.length > 0 ? result.toolsUsed : undefined
+      };
+
+      session.messages.push(assistantMessage);
+      session.updatedAt = new Date();
+      this.sessionManager.saveSession(projectPath, session);
+    } catch (error) {
+      // Error already emitted by executor
+      console.error('[InsightsService] Error executing insights:', error);
    }
-
-    // Get active Claude profile environment (CLAUDE_CONFIG_DIR if not default)
-    const profileEnv = getProfileEnv();
-
-    // Spawn Python process
-    const proc = spawn(this.pythonPath, [
-      runnerPath,
-      '--project-dir', projectPath,
-      '--message', message,
-      '--history', JSON.stringify(conversationHistory)
-    ], {
-      cwd: autoBuildSource,
-      env: {
-        ...process.env,
-        ...envVars,
-        ...profileEnv, // Include active Claude profile config
-        PYTHONUNBUFFERED: '1'
-      }
-    });
-
-    this.activeSessions.set(projectId, proc);
-
-    let fullResponse = '';
-    let suggestedTask: InsightsChatMessage['suggestedTask'] | undefined;
-    const toolsUsed: InsightsToolUsage[] = [];
-    // Collect output for rate limit detection
-    let allInsightsOutput = '';
-
-    proc.stdout?.on('data', (data: Buffer) => {
-      const text = data.toString();
-      // Collect output for rate limit detection (keep last 10KB)
-      allInsightsOutput = (allInsightsOutput + text).slice(-10000);
-
-      // Check for special markers
-      const lines = text.split('\n');
-      for (const line of lines) {
-        if (line.startsWith('__TASK_SUGGESTION__:')) {
-          try {
-            const taskJson = line.substring('__TASK_SUGGESTION__:'.length);
-            suggestedTask = JSON.parse(taskJson);
-            this.emit('stream-chunk', projectId, {
-              type: 'task_suggestion',
-              suggestedTask
-            } as InsightsStreamChunk);
-          } catch {
-            // Not valid JSON, treat as normal text
-            fullResponse += line + '\n';
-            this.emit('stream-chunk', projectId, {
-              type: 'text',
-              content: line + '\n'
-            } as InsightsStreamChunk);
-          }
-        } else if (line.startsWith('__TOOL_START__:')) {
-          // Tool execution started
-          try {
-            const toolJson = line.substring('__TOOL_START__:'.length);
-            const toolData = JSON.parse(toolJson);
-            // Accumulate tool usage for persistence
-            toolsUsed.push({
-              name: toolData.name,
-              input: toolData.input,
-              timestamp: new Date()
-            });
-            this.emit('stream-chunk', projectId, {
-              type: 'tool_start',
-              tool: {
-                name: toolData.name,
-                input: toolData.input
-              }
-            } as InsightsStreamChunk);
-          } catch {
-            // Ignore parse errors for tool markers
-          }
-        } else if (line.startsWith('__TOOL_END__:')) {
-          // Tool execution finished
-          try {
-            const toolJson = line.substring('__TOOL_END__:'.length);
-            const toolData = JSON.parse(toolJson);
-            this.emit('stream-chunk', projectId, {
-              type: 'tool_end',
-              tool: {
-                name: toolData.name
-              }
-            } as InsightsStreamChunk);
-          } catch {
-            // Ignore parse errors for tool markers
-          }
-        } else if (line.trim()) {
-          fullResponse += line + '\n';
-          this.emit('stream-chunk', projectId, {
-            type: 'text',
-            content: line + '\n'
-          } as InsightsStreamChunk);
-        }
-      }
-    });
-
-    proc.stderr?.on('data', (data: Buffer) => {
-      const text = data.toString();
-      // Collect stderr for rate limit detection too
-      allInsightsOutput = (allInsightsOutput + text).slice(-10000);
-      console.error('[Insights]', text);
-    });
-
-    proc.on('close', (code) => {
-      this.activeSessions.delete(projectId);
-
-      // Check for rate limit if process failed
-      if (code !== 0) {
-        const rateLimitDetection = detectRateLimit(allInsightsOutput);
-        if (rateLimitDetection.isRateLimited) {
-          console.log('[Insights] Rate limit detected:', {
-            projectId,
-            resetTime: rateLimitDetection.resetTime,
-            limitType: rateLimitDetection.limitType,
-            suggestedProfile: rateLimitDetection.suggestedProfile?.name
-          });
-
-          const rateLimitInfo = createSDKRateLimitInfo('other', rateLimitDetection, {
-            projectId
-          });
-          this.emit('sdk-rate-limit', rateLimitInfo);
-        }
-      }
-
-      if (code === 0) {
-        // Add assistant message to session
-        const assistantMessage: InsightsChatMessage = {
-          id: `msg-${Date.now()}`,
-          role: 'assistant',
-          content: fullResponse.trim(),
-          timestamp: new Date(),
-          suggestedTask,
-          toolsUsed: toolsUsed.length > 0 ? toolsUsed : undefined
-        };
-
-        session!.messages.push(assistantMessage);
-        session!.updatedAt = new Date();
-        this.saveSession(projectPath, session!);
-
-        this.emit('stream-chunk', projectId, {
-          type: 'done'
-        } as InsightsStreamChunk);
-
-        this.emit('status', projectId, {
-          phase: 'complete'
-        } as InsightsChatStatus);
-      } else {
-        this.emit('stream-chunk', projectId, {
-          type: 'error',
-          error: `Process exited with code ${code}`
-        } as InsightsStreamChunk);
-
-        this.emit('error', projectId, `Process exited with code ${code}`);
-      }
-    });
-
-    proc.on('error', (err) => {
-      this.activeSessions.delete(projectId);
-      this.emit('error', projectId, err.message);
-    });
  }
-
 }

 // Singleton instance
@@ -0,0 +1,88 @@
+# Insights Module
+
+This directory contains the modular architecture for the AI-powered codebase insights feature.
+
+## Architecture Overview
+
+The insights module follows a clean separation of concerns with each module handling a specific responsibility:
+
+```
+insights-service.ts (186 lines)
+├── config.ts (109 lines) - Configuration & Environment Management
+├── paths.ts (46 lines) - Path Resolution Utilities
+├── session-storage.ts (212 lines) - Filesystem Persistence
+├── session-manager.ts (151 lines) - Session Lifecycle Management
+└── insights-executor.ts (267 lines) - Python Process Execution
+```
+
+## Module Responsibilities
+
+### InsightsConfig (`config.ts`)
+- Manages Python and auto-claude source path configuration
+- Detects auto-claude installation automatically
+- Loads environment variables from auto-claude .env file
+- Provides complete process environment with profile support
+
+### InsightsPaths (`paths.ts`)
+- Provides consistent path resolution for insights data
+- Manages session directory structure
+- Handles migration paths for old session format
+
+### SessionStorage (`session-storage.ts`)
+- Handles filesystem persistence of sessions
+- Loads and saves session JSON files
+- Manages session file operations (create, read, update, delete)
+- Handles old session format migration
+- Generates session titles from first user message
+
+### SessionManager (`session-manager.ts`)
+- Manages in-memory session cache
+- Coordinates session lifecycle operations
+- Provides high-level session operations (create, switch, delete, rename)
+- Manages current session pointer
+
+### InsightsExecutor (`insights-executor.ts`)
+- Spawns and manages Python insights_runner.py process
+- Handles streaming output parsing
+- Detects and emits tool usage events
+- Detects and handles rate limiting
+- Emits status updates and stream chunks
+
+## Usage
+
+The main `InsightsService` class (in `insights-service.ts`) coordinates all these modules:
+
+```typescript
+import { InsightsService } from './insights-service';
+
+const service = new InsightsService();
+
+// Configure paths
+service.configure(pythonPath, autoBuildSourcePath);
+
+// Load session
+const session = service.loadSession(projectId, projectPath);
+
+// Send message
+await service.sendMessage(projectId, projectPath, message);
+```
+
+## Event Flow
+
+1. User sends message via `sendMessage()`
+2. Service loads/creates session via `SessionManager`
+3. Service executes query via `InsightsExecutor`
+4. Executor emits streaming events (status, chunks, tools)
+5. Service saves assistant response via `SessionManager`
+
+## Benefits of This Architecture
+
+- **Maintainability**: Each module has a single, clear responsibility
+- **Testability**: Modules can be unit tested independently
+- **Reusability**: Modules can be used independently if needed
+- **Readability**: Much easier to understand and navigate
+- **Extensibility**: Easy to add new features to specific modules
+
+## Migration Notes
+
+This refactoring maintains 100% backward compatibility. All functionality from the original 659-line file is preserved, just better organized across 5 focused modules.
@@ -0,0 +1,160 @@
+# Insights Service Refactoring Notes
+
+## Overview
+
+The insights-service.ts file (originally 659 lines) has been successfully refactored into a modular architecture with clear separation of concerns.
+
+## Changes Made
+
+### Before
+```
+insights-service.ts (659 lines)
+└── Single monolithic file containing:
+    - Configuration management
+    - Path utilities
+    - Session storage
+    - Session management
+    - Python process execution
+```
+
+### After
+```
+insights-service.ts (186 lines) - Main orchestrator
+insights/
+  ├── config.ts (109 lines) - Configuration & environment
+  ├── paths.ts (46 lines) - Path resolution
+  ├── session-storage.ts (212 lines) - Filesystem persistence
+  ├── session-manager.ts (151 lines) - Session lifecycle
+  ├── insights-executor.ts (267 lines) - Python process execution
+  ├── index.ts (17 lines) - Module exports
+  └── README.md - Architecture documentation
+```
+
+## Key Improvements
+
+### 1. Single Responsibility Principle
+Each module has one clear, focused responsibility:
+- **InsightsConfig**: Manages configuration and environment variables
+- **InsightsPaths**: Provides path resolution utilities
+- **SessionStorage**: Handles filesystem I/O operations
+- **SessionManager**: Coordinates session lifecycle with caching
+- **InsightsExecutor**: Manages Python process execution and output parsing
+
+### 2. Dependency Injection
+Modules are properly injected into their dependents:
+- SessionStorage depends on InsightsPaths
+- SessionManager depends on SessionStorage and InsightsPaths
+- InsightsExecutor depends on InsightsConfig
+- InsightsService orchestrates all modules
+
+### 3. Event-Driven Architecture
+InsightsExecutor emits events that are forwarded by InsightsService:
+- `status` - Status updates during execution
+- `stream-chunk` - Streaming response chunks
+- `error` - Error notifications
+- `sdk-rate-limit` - Rate limit detection
+
+### 4. Improved Testability
+Each module can now be unit tested independently:
+- Mock file system for SessionStorage tests
+- Mock process spawning for InsightsExecutor tests
+- Test configuration loading in isolation
+- Test path resolution independently
+
+### 5. Better Maintainability
+- 72% reduction in main file size (659 → 186 lines)
+- Clear module boundaries
+- Easier to locate and modify specific functionality
+- Self-documenting code structure
+
+## Backward Compatibility
+
+**100% backward compatible** - All existing functionality is preserved:
+- All public methods maintain the same signatures
+- Event emissions work identically
+- Session storage format unchanged
+- No changes required to consuming code
+
+## Migration Path
+
+No migration needed! The refactoring is transparent to consumers:
+
+```typescript
+// This code continues to work exactly as before
+import { insightsService } from '../insights-service';
+
+insightsService.configure(pythonPath, autoBuildSourcePath);
+const session = insightsService.loadSession(projectId, projectPath);
+await insightsService.sendMessage(projectId, projectPath, message);
+```
+
+## Build Verification
+
+The refactoring has been verified with:
+- ✅ Full TypeScript compilation successful
+- ✅ Production build completes without errors
+- ✅ All imports resolve correctly
+- ✅ No circular dependencies
+
+## Future Enhancements
+
+The modular architecture makes it easy to add:
+- Session export/import functionality
+- Advanced caching strategies
+- Alternative storage backends (SQLite, etc.)
+- Session search and filtering
+- Analytics and usage tracking
+- Process pooling for parallel queries
+
+## Architecture Diagram
+
+```
+┌─────────────────────────────────────────┐
+│        InsightsService (Main)           │
+│   - Orchestrates all modules            │
+│   - Forwards events from executor       │
+│   - Manages high-level workflows        │
+└────────────┬────────────────────────────┘
+             │
+      ┌──────┴──────┐
+      │             │
+      ▼             ▼
+┌──────────┐  ┌──────────────┐
+│ Config   │  │  Executor    │
+│ - Env    │  │  - Process   │
+│ - Paths  │  │  - Streaming │
+└──────────┘  └──────────────┘
+      ▼
+┌──────────┐
+│  Paths   │
+│ - Dirs   │
+│ - Files  │
+└────┬─────┘
+     │
+     ▼
+┌─────────────┐     ┌──────────────┐
+│  Storage    │────▶│   Manager    │
+│  - Load/Save│     │   - Cache    │
+│  - Migrate  │     │   - Lifecycle│
+└─────────────┘     └──────────────┘
+```
+
+## Code Quality Metrics
+
+| Metric | Before | After | Improvement |
+|--------|--------|-------|-------------|
+| Main file size | 659 lines | 186 lines | 72% reduction |
+| Largest module | 659 lines | 267 lines | 59% reduction |
+| Average module size | 659 lines | 140 lines | 79% smaller |
+| Number of modules | 1 | 7 | Better organization |
+| Cyclomatic complexity | High | Low | Easier to maintain |
+
+## Related Files
+
+Files that import insights-service (no changes needed):
+- `ipc-handlers/insights-handlers.ts`
+- `ipc-handlers/project-handlers.ts`
+
+## Date
+
+Refactored: December 16, 2025
@@ -0,0 +1,109 @@
+import path from 'path';
+import { existsSync, readFileSync } from 'fs';
+import { app } from 'electron';
+import { getProfileEnv } from '../rate-limit-detector';
+
+/**
+ * Configuration manager for insights service
+ * Handles path detection and environment variable loading
+ */
+export class InsightsConfig {
+  private pythonPath: string = 'python3';
+  private autoBuildSourcePath: string = '';
+
+  /**
+   * Configure paths for Python and auto-claude source
+   */
+  configure(pythonPath?: string, autoBuildSourcePath?: string): void {
+    if (pythonPath) {
+      this.pythonPath = pythonPath;
+    }
+    if (autoBuildSourcePath) {
+      this.autoBuildSourcePath = autoBuildSourcePath;
+    }
+  }
+
+  /**
+   * Get configured Python path
+   */
+  getPythonPath(): string {
+    return this.pythonPath;
+  }
+
+  /**
+   * Get the auto-claude source path (detects automatically if not configured)
+   */
+  getAutoBuildSourcePath(): string | null {
+    if (this.autoBuildSourcePath && existsSync(this.autoBuildSourcePath)) {
+      return this.autoBuildSourcePath;
+    }
+
+    const possiblePaths = [
+      path.resolve(__dirname, '..', '..', '..', 'auto-claude'),
+      path.resolve(app.getAppPath(), '..', 'auto-claude'),
+      path.resolve(process.cwd(), 'auto-claude')
+    ];
+
+    for (const p of possiblePaths) {
+      if (existsSync(p) && existsSync(path.join(p, 'VERSION'))) {
+        return p;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Load environment variables from auto-claude .env file
+   */
+  loadAutoBuildEnv(): Record<string, string> {
+    const autoBuildSource = this.getAutoBuildSourcePath();
+    if (!autoBuildSource) return {};
+
+    const envPath = path.join(autoBuildSource, '.env');
+    if (!existsSync(envPath)) return {};
+
+    try {
+      const envContent = readFileSync(envPath, 'utf-8');
+      const envVars: Record<string, string> = {};
+
+      // Handle both Unix (\n) and Windows (\r\n) line endings
+      for (const line of envContent.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#')) continue;
+
+        const eqIndex = trimmed.indexOf('=');
+        if (eqIndex > 0) {
+          const key = trimmed.substring(0, eqIndex).trim();
+          let value = trimmed.substring(eqIndex + 1).trim();
+
+          if ((value.startsWith('"') && value.endsWith('"')) ||
+              (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+          }
+
+          envVars[key] = value;
+        }
+      }
+
+      return envVars;
+    } catch {
+      return {};
+    }
+  }
+
+  /**
+   * Get complete environment for process execution
+   * Includes system env, auto-claude env, and active Claude profile
+   */
+  getProcessEnv(): Record<string, string> {
+    const autoBuildEnv = this.loadAutoBuildEnv();
+    const profileEnv = getProfileEnv();
+
+    return {
+      ...process.env as Record<string, string>,
+      ...autoBuildEnv,
+      ...profileEnv,
+      PYTHONUNBUFFERED: '1'
+    };
+  }
+}
@@ -0,0 +1,16 @@
+/**
+ * Insights module - modular architecture for AI-powered codebase insights
+ *
+ * This module provides a clean separation of concerns:
+ * - config: Environment and configuration management
+ * - paths: Path resolution utilities
+ * - session-storage: Filesystem persistence layer
+ * - session-manager: Session lifecycle management
+ * - insights-executor: Python process execution
+ */
+
+export { InsightsConfig } from './config';
+export { InsightsPaths } from './paths';
+export { SessionStorage } from './session-storage';
+export { SessionManager } from './session-manager';
+export { InsightsExecutor } from './insights-executor';
@@ -0,0 +1,267 @@
+import { spawn, ChildProcess } from 'child_process';
+import { existsSync } from 'fs';
+import path from 'path';
+import { EventEmitter } from 'events';
+import type {
+  InsightsChatMessage,
+  InsightsChatStatus,
+  InsightsStreamChunk,
+  InsightsToolUsage
+} from '../../shared/types';
+import { InsightsConfig } from './config';
+import { detectRateLimit, createSDKRateLimitInfo } from '../rate-limit-detector';
+
+/**
+ * Message processor result
+ */
+interface ProcessorResult {
+  fullResponse: string;
+  suggestedTask?: InsightsChatMessage['suggestedTask'];
+  toolsUsed: InsightsToolUsage[];
+}
+
+/**
+ * Python process executor for insights
+ * Handles spawning and managing the Python insights runner process
+ */
+export class InsightsExecutor extends EventEmitter {
+  private config: InsightsConfig;
+  private activeSessions: Map<string, ChildProcess> = new Map();
+
+  constructor(config: InsightsConfig) {
+    super();
+    this.config = config;
+  }
+
+  /**
+   * Check if a session is currently active
+   */
+  isSessionActive(projectId: string): boolean {
+    return this.activeSessions.has(projectId);
+  }
+
+  /**
+   * Cancel an active session
+   */
+  cancelSession(projectId: string): boolean {
+    const existingProcess = this.activeSessions.get(projectId);
+    if (!existingProcess) return false;
+
+    existingProcess.kill();
+    this.activeSessions.delete(projectId);
+    return true;
+  }
+
+  /**
+   * Execute insights query
+   */
+  async execute(
+    projectId: string,
+    projectPath: string,
+    message: string,
+    conversationHistory: Array<{ role: string; content: string }>
+  ): Promise<ProcessorResult> {
+    // Cancel any existing session
+    this.cancelSession(projectId);
+
+    const autoBuildSource = this.config.getAutoBuildSourcePath();
+    if (!autoBuildSource) {
+      throw new Error('Auto Claude source not found');
+    }
+
+    const runnerPath = path.join(autoBuildSource, 'insights_runner.py');
+    if (!existsSync(runnerPath)) {
+      throw new Error('insights_runner.py not found in auto-claude directory');
+    }
+
+    // Emit thinking status
+    this.emit('status', projectId, {
+      phase: 'thinking',
+      message: 'Processing your message...'
+    } as InsightsChatStatus);
+
+    // Get process environment
+    const processEnv = this.config.getProcessEnv();
+
+    // Spawn Python process
+    const proc = spawn(this.config.getPythonPath(), [
+      runnerPath,
+      '--project-dir', projectPath,
+      '--message', message,
+      '--history', JSON.stringify(conversationHistory)
+    ], {
+      cwd: autoBuildSource,
+      env: processEnv
+    });
+
+    this.activeSessions.set(projectId, proc);
+
+    return new Promise((resolve, reject) => {
+      let fullResponse = '';
+      let suggestedTask: InsightsChatMessage['suggestedTask'] | undefined;
+      const toolsUsed: InsightsToolUsage[] = [];
+      let allInsightsOutput = '';
+
+      proc.stdout?.on('data', (data: Buffer) => {
+        const text = data.toString();
+        // Collect output for rate limit detection (keep last 10KB)
+        allInsightsOutput = (allInsightsOutput + text).slice(-10000);
+
+        // Process output lines
+        const lines = text.split('\n');
+        for (const line of lines) {
+          if (line.startsWith('__TASK_SUGGESTION__:')) {
+            this.handleTaskSuggestion(projectId, line, (task) => {
+              suggestedTask = task;
+            });
+          } else if (line.startsWith('__TOOL_START__:')) {
+            this.handleToolStart(projectId, line, toolsUsed);
+          } else if (line.startsWith('__TOOL_END__:')) {
+            this.handleToolEnd(projectId, line);
+          } else if (line.trim()) {
+            fullResponse += line + '\n';
+            this.emit('stream-chunk', projectId, {
+              type: 'text',
+              content: line + '\n'
+            } as InsightsStreamChunk);
+          }
+        }
+      });
+
+      proc.stderr?.on('data', (data: Buffer) => {
+        const text = data.toString();
+        // Collect stderr for rate limit detection too
+        allInsightsOutput = (allInsightsOutput + text).slice(-10000);
+        console.error('[Insights]', text);
+      });
+
+      proc.on('close', (code) => {
+        this.activeSessions.delete(projectId);
+
+        // Check for rate limit if process failed
+        if (code !== 0) {
+          this.handleRateLimit(projectId, allInsightsOutput);
+        }
+
+        if (code === 0) {
+          this.emit('stream-chunk', projectId, {
+            type: 'done'
+          } as InsightsStreamChunk);
+
+          this.emit('status', projectId, {
+            phase: 'complete'
+          } as InsightsChatStatus);
+
+          resolve({
+            fullResponse: fullResponse.trim(),
+            suggestedTask,
+            toolsUsed
+          });
+        } else {
+          const error = `Process exited with code ${code}`;
+          this.emit('stream-chunk', projectId, {
+            type: 'error',
+            error
+          } as InsightsStreamChunk);
+
+          this.emit('error', projectId, error);
+          reject(new Error(error));
+        }
+      });
+
+      proc.on('error', (err) => {
+        this.activeSessions.delete(projectId);
+        this.emit('error', projectId, err.message);
+        reject(err);
+      });
+    });
+  }
+
+  /**
+   * Handle task suggestion from output
+   */
+  private handleTaskSuggestion(
+    projectId: string,
+    line: string,
+    onTaskFound: (task: InsightsChatMessage['suggestedTask']) => void
+  ): void {
+    try {
+      const taskJson = line.substring('__TASK_SUGGESTION__:'.length);
+      const suggestedTask = JSON.parse(taskJson);
+      onTaskFound(suggestedTask);
+      this.emit('stream-chunk', projectId, {
+        type: 'task_suggestion',
+        suggestedTask
+      } as InsightsStreamChunk);
+    } catch {
+      // Not valid JSON, treat as normal text (should not emit here as it's already handled)
+    }
+  }
+
+  /**
+   * Handle tool start marker
+   */
+  private handleToolStart(
+    projectId: string,
+    line: string,
+    toolsUsed: InsightsToolUsage[]
+  ): void {
+    try {
+      const toolJson = line.substring('__TOOL_START__:'.length);
+      const toolData = JSON.parse(toolJson);
+      // Accumulate tool usage for persistence
+      toolsUsed.push({
+        name: toolData.name,
+        input: toolData.input,
+        timestamp: new Date()
+      });
+      this.emit('stream-chunk', projectId, {
+        type: 'tool_start',
+        tool: {
+          name: toolData.name,
+          input: toolData.input
+        }
+      } as InsightsStreamChunk);
+    } catch {
+      // Ignore parse errors for tool markers
+    }
+  }
+
+  /**
+   * Handle tool end marker
+   */
+  private handleToolEnd(projectId: string, line: string): void {
+    try {
+      const toolJson = line.substring('__TOOL_END__:'.length);
+      const toolData = JSON.parse(toolJson);
+      this.emit('stream-chunk', projectId, {
+        type: 'tool_end',
+        tool: {
+          name: toolData.name
+        }
+      } as InsightsStreamChunk);
+    } catch {
+      // Ignore parse errors for tool markers
+    }
+  }
+
+  /**
+   * Handle rate limit detection
+   */
+  private handleRateLimit(projectId: string, output: string): void {
+    const rateLimitDetection = detectRateLimit(output);
+    if (rateLimitDetection.isRateLimited) {
+      console.log('[Insights] Rate limit detected:', {
+        projectId,
+        resetTime: rateLimitDetection.resetTime,
+        limitType: rateLimitDetection.limitType,
+        suggestedProfile: rateLimitDetection.suggestedProfile?.name
+      });
+
+      const rateLimitInfo = createSDKRateLimitInfo('other', rateLimitDetection, {
+        projectId
+      });
+      this.emit('sdk-rate-limit', rateLimitInfo);
+    }
+  }
+}
@@ -0,0 +1,46 @@
+import path from 'path';
+
+const INSIGHTS_DIR = '.auto-claude/insights';
+const SESSIONS_DIR = 'sessions';
+const CURRENT_SESSION_FILE = 'current_session.json';
+
+/**
+ * Path utilities for insights service
+ * Provides consistent path resolution for sessions and insights data
+ */
+export class InsightsPaths {
+  /**
+   * Get insights directory path for a project
+   */
+  getInsightsDir(projectPath: string): string {
+    return path.join(projectPath, INSIGHTS_DIR);
+  }
+
+  /**
+   * Get sessions directory path for a project
+   */
+  getSessionsDir(projectPath: string): string {
+    return path.join(this.getInsightsDir(projectPath), SESSIONS_DIR);
+  }
+
+  /**
+   * Get session file path for a specific session
+   */
+  getSessionPath(projectPath: string, sessionId: string): string {
+    return path.join(this.getSessionsDir(projectPath), `${sessionId}.json`);
+  }
+
+  /**
+   * Get current session pointer file path
+   */
+  getCurrentSessionPath(projectPath: string): string {
+    return path.join(this.getInsightsDir(projectPath), CURRENT_SESSION_FILE);
+  }
+
+  /**
+   * Get old session path for migration
+   */
+  getOldSessionPath(projectPath: string): string {
+    return path.join(this.getInsightsDir(projectPath), 'session.json');
+  }
+}
@@ -0,0 +1,151 @@
+import type { InsightsSession, InsightsSessionSummary } from '../../shared/types';
+import { SessionStorage } from './session-storage';
+import { InsightsPaths } from './paths';
+
+/**
+ * Session manager
+ * Manages in-memory session cache and coordinates with session storage
+ */
+export class SessionManager {
+  private sessions: Map<string, InsightsSession> = new Map();
+  private storage: SessionStorage;
+  private paths: InsightsPaths;
+
+  constructor(storage: SessionStorage, paths: InsightsPaths) {
+    this.storage = storage;
+    this.paths = paths;
+  }
+
+  /**
+   * Load current session from disk or cache
+   */
+  loadSession(projectId: string, projectPath: string): InsightsSession | null {
+    // Check in-memory cache first
+    if (this.sessions.has(projectId)) {
+      return this.sessions.get(projectId)!;
+    }
+
+    // Migrate old format if needed
+    this.storage.migrateOldSession(projectPath);
+
+    const currentSessionId = this.storage.getCurrentSessionId(projectPath);
+    if (!currentSessionId) return null;
+
+    const session = this.storage.loadSessionById(projectPath, currentSessionId);
+    if (session) {
+      this.sessions.set(projectId, session);
+    }
+    return session;
+  }
+
+  /**
+   * List all sessions for a project
+   */
+  listSessions(projectPath: string): InsightsSessionSummary[] {
+    // Migrate old format if needed
+    this.storage.migrateOldSession(projectPath);
+    return this.storage.listSessions(projectPath);
+  }
+
+  /**
+   * Create a new session
+   */
+  createNewSession(projectId: string, projectPath: string): InsightsSession {
+    const sessionId = `session-${Date.now()}`;
+    const session: InsightsSession = {
+      id: sessionId,
+      projectId,
+      title: 'New Conversation',
+      messages: [],
+      createdAt: new Date(),
+      updatedAt: new Date()
+    };
+
+    // Save new session
+    this.storage.saveSession(projectPath, session);
+    this.storage.saveCurrentSessionId(projectPath, sessionId);
+    this.sessions.set(projectId, session);
+
+    return session;
+  }
+
+  /**
+   * Switch to a different session
+   */
+  switchSession(projectId: string, projectPath: string, sessionId: string): InsightsSession | null {
+    const session = this.storage.loadSessionById(projectPath, sessionId);
+    if (session) {
+      this.storage.saveCurrentSessionId(projectPath, sessionId);
+      this.sessions.set(projectId, session);
+    }
+    return session;
+  }
+
+  /**
+   * Delete a session
+   */
+  deleteSession(projectId: string, projectPath: string, sessionId: string): boolean {
+    const success = this.storage.deleteSession(projectPath, sessionId);
+    if (!success) return false;
+
+    // If this was the current session, clear the cache
+    const currentSession = this.sessions.get(projectId);
+    if (currentSession?.id === sessionId) {
+      this.sessions.delete(projectId);
+
+      // Find another session to switch to, or create new
+      const remaining = this.listSessions(projectPath);
+      if (remaining.length > 0) {
+        this.switchSession(projectId, projectPath, remaining[0].id);
+      } else {
+        // Clear current session pointer
+        this.storage.clearCurrentSessionId(projectPath);
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Rename a session
+   */
+  renameSession(projectPath: string, sessionId: string, newTitle: string): boolean {
+    const session = this.storage.loadSessionById(projectPath, sessionId);
+    if (!session) return false;
+
+    session.title = newTitle;
+    session.updatedAt = new Date();
+    this.storage.saveSession(projectPath, session);
+    return true;
+  }
+
+  /**
+   * Save session to disk and update cache
+   */
+  saveSession(projectPath: string, session: InsightsSession): void {
+    this.storage.saveSession(projectPath, session);
+    this.sessions.set(session.projectId, session);
+  }
+
+  /**
+   * Clear current session (create a new one)
+   */
+  clearSession(projectId: string, projectPath: string): void {
+    const newSession = this.createNewSession(projectId, projectPath);
+    this.sessions.set(projectId, newSession);
+  }
+
+  /**
+   * Get cached session without loading from disk
+   */
+  getCachedSession(projectId: string): InsightsSession | null {
+    return this.sessions.get(projectId) || null;
+  }
+
+  /**
+   * Clear session from cache
+   */
+  clearCache(projectId: string): void {
+    this.sessions.delete(projectId);
+  }
+}
@@ -0,0 +1,212 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, unlinkSync } from 'fs';
+import path from 'path';
+import type { InsightsSession, InsightsSessionSummary } from '../../shared/types';
+import { InsightsPaths } from './paths';
+
+/**
+ * Session storage manager
+ * Handles persisting and loading sessions from the filesystem
+ */
+export class SessionStorage {
+  private paths: InsightsPaths;
+
+  constructor(paths: InsightsPaths) {
+    this.paths = paths;
+  }
+
+  /**
+   * Generate a title from the first user message
+   */
+  generateTitle(message: string): string {
+    // Truncate to first 50 characters and clean up
+    const title = message.trim().replace(/\n/g, ' ').slice(0, 50);
+    return title.length < message.trim().length ? `${title}...` : title;
+  }
+
+  /**
+   * Load a specific session from disk
+   */
+  loadSessionById(projectPath: string, sessionId: string): InsightsSession | null {
+    const sessionPath = this.paths.getSessionPath(projectPath, sessionId);
+    if (!existsSync(sessionPath)) return null;
+
+    try {
+      const content = readFileSync(sessionPath, 'utf-8');
+      const session = JSON.parse(content) as InsightsSession;
+      // Convert date strings back to Date objects
+      session.createdAt = new Date(session.createdAt);
+      session.updatedAt = new Date(session.updatedAt);
+      session.messages = session.messages.map(m => ({
+        ...m,
+        timestamp: new Date(m.timestamp),
+        // Convert toolsUsed timestamps if present
+        toolsUsed: m.toolsUsed?.map(t => ({
+          ...t,
+          timestamp: new Date(t.timestamp)
+        }))
+      }));
+      return session;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Save session to disk
+   */
+  saveSession(projectPath: string, session: InsightsSession): void {
+    const sessionsDir = this.paths.getSessionsDir(projectPath);
+    if (!existsSync(sessionsDir)) {
+      mkdirSync(sessionsDir, { recursive: true });
+    }
+
+    const sessionPath = this.paths.getSessionPath(projectPath, session.id);
+    writeFileSync(sessionPath, JSON.stringify(session, null, 2));
+  }
+
+  /**
+   * Delete a session from disk
+   */
+  deleteSession(projectPath: string, sessionId: string): boolean {
+    const sessionPath = this.paths.getSessionPath(projectPath, sessionId);
+    if (!existsSync(sessionPath)) return false;
+
+    try {
+      unlinkSync(sessionPath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * List all sessions for a project
+   */
+  listSessions(projectPath: string): InsightsSessionSummary[] {
+    const sessionsDir = this.paths.getSessionsDir(projectPath);
+    if (!existsSync(sessionsDir)) return [];
+
+    try {
+      const files = readdirSync(sessionsDir).filter(f => f.endsWith('.json'));
+      const sessions: InsightsSessionSummary[] = [];
+
+      for (const file of files) {
+        try {
+          const content = readFileSync(path.join(sessionsDir, file), 'utf-8');
+          const session = JSON.parse(content) as InsightsSession;
+
+          // Generate title if not present
+          let title = session.title;
+          if (!title && session.messages.length > 0) {
+            const firstUserMessage = session.messages.find(m => m.role === 'user');
+            title = firstUserMessage
+              ? this.generateTitle(firstUserMessage.content)
+              : 'Untitled Conversation';
+          }
+
+          sessions.push({
+            id: session.id,
+            projectId: session.projectId,
+            title: title || 'New Conversation',
+            messageCount: session.messages.length,
+            createdAt: new Date(session.createdAt),
+            updatedAt: new Date(session.updatedAt)
+          });
+        } catch {
+          // Skip invalid session files
+        }
+      }
+
+      // Sort by updatedAt descending (most recent first)
+      return sessions.sort((a, b) =>
+        new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime()
+      );
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Get current session ID for a project
+   */
+  getCurrentSessionId(projectPath: string): string | null {
+    const currentPath = this.paths.getCurrentSessionPath(projectPath);
+    if (!existsSync(currentPath)) return null;
+
+    try {
+      const content = readFileSync(currentPath, 'utf-8');
+      const data = JSON.parse(content);
+      return data.currentSessionId || null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Save current session ID pointer
+   */
+  saveCurrentSessionId(projectPath: string, sessionId: string): void {
+    const insightsDir = this.paths.getInsightsDir(projectPath);
+    if (!existsSync(insightsDir)) {
+      mkdirSync(insightsDir, { recursive: true });
+    }
+
+    const currentPath = this.paths.getCurrentSessionPath(projectPath);
+    writeFileSync(currentPath, JSON.stringify({ currentSessionId: sessionId }, null, 2));
+  }
+
+  /**
+   * Clear current session pointer
+   */
+  clearCurrentSessionId(projectPath: string): void {
+    const currentPath = this.paths.getCurrentSessionPath(projectPath);
+    if (existsSync(currentPath)) {
+      unlinkSync(currentPath);
+    }
+  }
+
+  /**
+   * Migrate old session format to new multi-session format
+   */
+  migrateOldSession(projectPath: string): void {
+    const oldSessionPath = this.paths.getOldSessionPath(projectPath);
+    if (!existsSync(oldSessionPath)) return;
+
+    try {
+      const content = readFileSync(oldSessionPath, 'utf-8');
+      const oldSession = JSON.parse(content) as InsightsSession;
+
+      // Only migrate if it has messages
+      if (oldSession.messages && oldSession.messages.length > 0) {
+        // Ensure sessions directory exists
+        const sessionsDir = this.paths.getSessionsDir(projectPath);
+        if (!existsSync(sessionsDir)) {
+          mkdirSync(sessionsDir, { recursive: true });
+        }
+
+        // Generate title from first user message
+        const firstUserMessage = oldSession.messages.find(m => m.role === 'user');
+        const title = firstUserMessage
+          ? this.generateTitle(firstUserMessage.content)
+          : 'Imported Conversation';
+
+        // Create new session with title
+        const newSession: InsightsSession = {
+          ...oldSession,
+          title
+        };
+
+        // Save as new session file
+        this.saveSession(projectPath, newSession);
+
+        // Set as current session
+        this.saveCurrentSessionId(projectPath, oldSession.id);
+      }
+
+      // Remove old session file
+      unlinkSync(oldSessionPath);
+    } catch {
+      // Ignore migration errors
+    }
+  }
+}
@@ -17,6 +17,7 @@ import type { ProcessType, ExecutionProgressData } from '../agent';
 import { titleGenerator } from '../title-generator';
 import { fileWatcher } from '../file-watcher';
 import { projectStore } from '../project-store';
+import { notificationService } from '../notification-service';


 /**
@@ -88,12 +89,12 @@ export function registerAgenteventsHandlers(
        newStatus = 'human_review';
      }

-      // Persist status to disk so it survives hot reload
-      // This is a backup in case the Python backend didn't sync properly
+      // Find task and project for status persistence and notifications
+      let task: Task | undefined;
+      let project: Project | undefined;
+
      try {
        const projects = projectStore.getProjects();
-        let task: Task | undefined;
-        let project: Project | undefined;

        for (const p of projects) {
          const tasks = projectStore.getTasks(p.id);
@@ -104,6 +105,8 @@ export function registerAgenteventsHandlers(
          }
        }

+        // Persist status to disk so it survives hot reload
+        // This is a backup in case the Python backend didn't sync properly
        if (task && project) {
          const specsBaseDir = getSpecsDir(project.autoBuildPath);
          const specDir = path.join(project.path, specsBaseDir, task.specId);
@@ -135,6 +138,19 @@ export function registerAgenteventsHandlers(
        console.error(`[Task ${taskId}] Failed to persist status:`, persistError);
      }

+      // Send notifications based on task completion status
+      if (task && project) {
+        const taskTitle = task.title || task.specId;
+        
+        if (code === 0) {
+          // Task completed successfully - ready for review
+          notificationService.notifyReviewNeeded(taskTitle, project.id, taskId);
+        } else {
+          // Task failed
+          notificationService.notifyTaskFailed(taskTitle, project.id, taskId);
+        }
+      }
+
      mainWindow.webContents.send(
        IPC_CHANNELS.TASK_STATUS_CHANGE,
        taskId,
@@ -20,7 +20,7 @@ export function registerAutobuildSourceHandlers(

  ipcMain.handle(
    IPC_CHANNELS.AUTOBUILD_SOURCE_CHECK,
-    async (): Promise<IPCResult<{ updateAvailable: boolean; currentVersion: string; latestVersion?: string; releaseNotes?: string; error?: string }>> => {
+    async (): Promise<IPCResult<{ updateAvailable: boolean; currentVersion: string; latestVersion?: string; releaseNotes?: string; releaseUrl?: string; error?: string }>> => {
      try {
        const result = await checkSourceUpdates();
        return { success: true, data: result };
@@ -1,7 +1,7 @@
 import { ipcMain } from 'electron';
 import type { BrowserWindow } from 'electron';
 import path from 'path';
-import { existsSync, readFileSync } from 'fs';
+import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'fs';
 import { execSync } from 'child_process';
 import { IPC_CHANNELS, getSpecsDir } from '../../shared/constants';
 import type {
@@ -210,6 +210,48 @@ export function registerChangelogHandlers(
    }
  );

+  ipcMain.handle(
+    IPC_CHANNELS.CHANGELOG_SUGGEST_VERSION_FROM_COMMITS,
+    async (_, projectId: string, commits: GitCommit[]): Promise<IPCResult<{ version: string; reason: string }>> => {
+      const project = projectStore.getProject(projectId);
+      if (!project) {
+        return { success: false, error: 'Project not found' };
+      }
+
+      try {
+        // Get current version from existing changelog or git tags
+        const existing = changelogService.readExistingChangelog(project.path);
+        let currentVersion = existing.lastVersion;
+
+        // If no version in changelog, try to get latest tag
+        if (!currentVersion) {
+          const tags = changelogService.getTags(project.path);
+          if (tags.length > 0) {
+            // Extract version from tag name (e.g., "v2.1.0" -> "2.1.0")
+            currentVersion = tags[0].name.replace(/^v/, '');
+          }
+        }
+
+        // Use AI to analyze commits and suggest version
+        const result = await changelogService.suggestVersionFromCommits(
+          project.path,
+          commits,
+          currentVersion
+        );
+
+        return {
+          success: true,
+          data: result
+        };
+      } catch (error) {
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : 'Failed to suggest version from commits'
+        };
+      }
+    }
+  );
+
  // ============================================
  // Changelog Git Operations
  // ============================================
@@ -292,6 +334,48 @@ export function registerChangelogHandlers(
    }
  );

+  // ============================================
+  // Changelog Image Operations
+  // ============================================
+
+  ipcMain.handle(
+    IPC_CHANNELS.CHANGELOG_SAVE_IMAGE,
+    async (_, projectId: string, imageData: string, filename: string): Promise<IPCResult<{ relativePath: string; url: string }>> => {
+      const project = projectStore.getProject(projectId);
+      if (!project) {
+        return { success: false, error: 'Project not found' };
+      }
+
+      try {
+        // Create .github/assets directory if it doesn't exist
+        const assetsDir = path.join(project.path, '.github', 'assets');
+        if (!existsSync(assetsDir)) {
+          mkdirSync(assetsDir, { recursive: true });
+        }
+
+        // Decode base64 image data
+        const base64Data = imageData.includes(',') ? imageData.split(',')[1] : imageData;
+        const buffer = Buffer.from(base64Data, 'base64');
+
+        // Save image file
+        const imagePath = path.join(assetsDir, filename);
+        writeFileSync(imagePath, buffer);
+
+        // Return relative path for use in markdown
+        const relativePath = `.github/assets/${filename}`;
+        // For GitHub releases, we'll use the relative path which will work when the release is created
+        const url = relativePath;
+
+        return { success: true, data: { relativePath, url } };
+      } catch (error) {
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : 'Failed to save image'
+        };
+      }
+    }
+  );
+
  // ============================================
  // Changelog Agent Events → Renderer
 }
@@ -1,551 +1,29 @@
-import { ipcMain, app } from 'electron';
+/**
+ * Context Handlers
+ *
+ * This module serves as the entry point for all context-related IPC handlers.
+ * The implementation has been refactored into smaller, focused modules in the context/ subdirectory:
+ *
+ * - utils.ts: Shared utility functions for environment parsing and configuration
+ * - memory-status-handlers.ts: Handlers for checking Graphiti/memory configuration
+ * - memory-data-handlers.ts: Handlers for getting and searching memories
+ * - project-context-handlers.ts: Handlers for project context and index operations
+ *
+ * All handlers are registered through the main registerContextHandlers function.
+ */
+
 import type { BrowserWindow } from 'electron';
-import path from 'path';
-import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
-import { spawn } from 'child_process';
-import { IPC_CHANNELS, getSpecsDir, AUTO_BUILD_PATHS } from '../../shared/constants';
-import type {
-  IPCResult,
-  ProjectContextData,
-  GraphitiMemoryStatus,
-  MemoryEpisode,
-  ContextSearchResult,
-  ProjectIndex,
-  GraphitiMemoryState
-} from '../../shared/types';
-import { projectStore } from '../project-store';
-
-const settingsPath = path.join(app.getPath('userData'), 'settings.json');
-
-const getAutoBuildSourcePath = (): string | null => {
-  if (existsSync(settingsPath)) {
-    try {
-      const content = readFileSync(settingsPath, 'utf-8');
-      const settings = JSON.parse(content);
-      if (settings.autoBuildPath && existsSync(settings.autoBuildPath)) {
-        return settings.autoBuildPath;
-      }
-    } catch {
-      // Fall through to null
-    }
-  }
-  return null;
-};
+import { registerContextHandlers } from './context';

+export { registerContextHandlers };

 /**
 * Register all context-related IPC handlers
+ *
+ * @param getMainWindow - Function that returns the main BrowserWindow instance
 */
-export function registerContextHandlers(
+export function setupContextHandlers(
  getMainWindow: () => BrowserWindow | null
 ): void {
-  // ============================================
-  // Context Operations
-  // ============================================
-
-  ipcMain.handle(
-    IPC_CHANNELS.CONTEXT_GET,
-    async (_, projectId: string): Promise<IPCResult<ProjectContextData>> => {
-      const project = projectStore.getProject(projectId);
-      if (!project) {
-        return { success: false, error: 'Project not found' };
-      }
-
-      try {
-        // Load project index
-        let projectIndex: ProjectIndex | null = null;
-        const indexPath = path.join(project.path, AUTO_BUILD_PATHS.PROJECT_INDEX);
-        if (existsSync(indexPath)) {
-          const content = readFileSync(indexPath, 'utf-8');
-          projectIndex = JSON.parse(content);
-        }
-
-        // Load graphiti state from most recent spec or project root
-        let memoryState: GraphitiMemoryState | null = null;
-        let memoryStatus: GraphitiMemoryStatus = {
-          enabled: false,
-          available: false,
-          reason: 'Graphiti not configured'
-        };
-
-        // Check for graphiti state in specs
-                const specsBaseDir = getSpecsDir(project.autoBuildPath);
-        const specsDir = path.join(project.path, specsBaseDir);
-        if (existsSync(specsDir)) {
-          const specDirs = readdirSync(specsDir)
-            .filter((f: string) => {
-              const specPath = path.join(specsDir, f);
-              return statSync(specPath).isDirectory();
-            })
-            .sort()
-            .reverse();
-
-          for (const specDir of specDirs) {
-            const statePath = path.join(specsDir, specDir, AUTO_BUILD_PATHS.GRAPHITI_STATE);
-            if (existsSync(statePath)) {
-              const stateContent = readFileSync(statePath, 'utf-8');
-              memoryState = JSON.parse(stateContent);
-
-              // If we found a state, update memory status
-              if (memoryState?.initialized) {
-                memoryStatus = {
-                  enabled: true,
-                  available: true,
-                  database: memoryState.database || 'auto_build_memory',
-                  host: process.env.GRAPHITI_FALKORDB_HOST || 'localhost',
-                  port: parseInt(process.env.GRAPHITI_FALKORDB_PORT || '6380', 10)
-                };
-              }
-              break;
-            }
-          }
-        }
-
-        // Check environment for Graphiti config if not found in specs
-        if (!memoryState) {
-          // Load project .env file and global settings to check for Graphiti config
-          let projectEnvVars: Record<string, string> = {};
-          if (project.autoBuildPath) {
-            const projectEnvPath = path.join(project.path, project.autoBuildPath, '.env');
-            if (existsSync(projectEnvPath)) {
-              try {
-                const envContent = readFileSync(projectEnvPath, 'utf-8');
-                // Parse .env file inline - handle both Unix and Windows line endings
-                for (const line of envContent.split(/\r?\n/)) {
-                  const trimmed = line.trim();
-                  if (!trimmed || trimmed.startsWith('#')) continue;
-                  const eqIndex = trimmed.indexOf('=');
-                  if (eqIndex > 0) {
-                    const key = trimmed.substring(0, eqIndex).trim();
-                    let value = trimmed.substring(eqIndex + 1).trim();
-                    if ((value.startsWith('"') && value.endsWith('"')) ||
-                        (value.startsWith("'") && value.endsWith("'"))) {
-                      value = value.slice(1, -1);
-                    }
-                    projectEnvVars[key] = value;
-                  }
-                }
-              } catch {
-                // Continue with empty vars
-              }
-            }
-          }
-
-          // Load global settings for OpenAI API key fallback
-          let globalOpenAIKey: string | undefined;
-          if (existsSync(settingsPath)) {
-            try {
-              const settingsContent = readFileSync(settingsPath, 'utf-8');
-              const globalSettings = JSON.parse(settingsContent);
-              globalOpenAIKey = globalSettings.globalOpenAIApiKey;
-            } catch {
-              // Continue without global settings
-            }
-          }
-
-          // Check for Graphiti config: project .env > process.env
-          const graphitiEnabled =
-            projectEnvVars['GRAPHITI_ENABLED']?.toLowerCase() === 'true' ||
-            process.env.GRAPHITI_ENABLED?.toLowerCase() === 'true';
-
-          // Check for OpenAI key: project .env > global settings > process.env
-          const hasOpenAI =
-            !!projectEnvVars['OPENAI_API_KEY'] ||
-            !!globalOpenAIKey ||
-            !!process.env.OPENAI_API_KEY;
-
-          // Get Graphiti connection details from project .env or process.env
-          const graphitiHost = projectEnvVars['GRAPHITI_FALKORDB_HOST'] || process.env.GRAPHITI_FALKORDB_HOST || 'localhost';
-          const graphitiPort = parseInt(projectEnvVars['GRAPHITI_FALKORDB_PORT'] || process.env.GRAPHITI_FALKORDB_PORT || '6380', 10);
-          const graphitiDatabase = projectEnvVars['GRAPHITI_DATABASE'] || process.env.GRAPHITI_DATABASE || 'auto_build_memory';
-
-          if (graphitiEnabled && hasOpenAI) {
-            memoryStatus = {
-              enabled: true,
-              available: true,
-              host: graphitiHost,
-              port: graphitiPort,
-              database: graphitiDatabase
-            };
-          } else if (graphitiEnabled && !hasOpenAI) {
-            memoryStatus = {
-              enabled: true,
-              available: false,
-              reason: 'OPENAI_API_KEY not set (required for Graphiti embeddings)'
-            };
-          }
-        }
-
-        // Load recent memories from file-based memory (session insights)
-        const recentMemories: MemoryEpisode[] = [];
-        if (existsSync(specsDir)) {
-          const recentSpecDirs = readdirSync(specsDir)
-            .filter((f: string) => {
-              const specPath = path.join(specsDir, f);
-              return statSync(specPath).isDirectory();
-            })
-            .sort()
-            .reverse()
-            .slice(0, 10); // Last 10 specs
-
-          for (const specDir of recentSpecDirs) {
-            const memoryDir = path.join(specsDir, specDir, 'memory');
-            if (existsSync(memoryDir)) {
-              // Load session insights from session_insights subdirectory
-              const sessionInsightsDir = path.join(memoryDir, 'session_insights');
-              if (existsSync(sessionInsightsDir)) {
-                const sessionFiles = readdirSync(sessionInsightsDir)
-                  .filter((f: string) => f.startsWith('session_') && f.endsWith('.json'))
-                  .sort()
-                  .reverse();
-
-                for (const sessionFile of sessionFiles.slice(0, 3)) {
-                  try {
-                    const sessionPath = path.join(sessionInsightsDir, sessionFile);
-                    const sessionContent = readFileSync(sessionPath, 'utf-8');
-                    const sessionData = JSON.parse(sessionContent);
-
-                    // Session files have: session_number, timestamp, subtasks_completed,
-                    // discoveries, what_worked, what_failed, recommendations_for_next_session
-                    if (sessionData.session_number !== undefined) {
-                      recentMemories.push({
-                        id: `${specDir}-${sessionFile}`,
-                        type: 'session_insight',
-                        timestamp: sessionData.timestamp || new Date().toISOString(),
-                        content: JSON.stringify({
-                          discoveries: sessionData.discoveries,
-                          what_worked: sessionData.what_worked,
-                          what_failed: sessionData.what_failed,
-                          recommendations: sessionData.recommendations_for_next_session,
-                          subtasks_completed: sessionData.subtasks_completed
-                        }, null, 2),
-                        session_number: sessionData.session_number
-                      });
-                    }
-                  } catch {
-                    // Skip invalid files
-                  }
-                }
-              }
-
-              // Also load codebase_map.json as a memory item
-              const codebaseMapPath = path.join(memoryDir, 'codebase_map.json');
-              if (existsSync(codebaseMapPath)) {
-                try {
-                  const mapContent = readFileSync(codebaseMapPath, 'utf-8');
-                  const mapData = JSON.parse(mapContent);
-                  if (mapData.discovered_files && Object.keys(mapData.discovered_files).length > 0) {
-                    recentMemories.push({
-                      id: `${specDir}-codebase_map`,
-                      type: 'codebase_map',
-                      timestamp: mapData.last_updated || new Date().toISOString(),
-                      content: JSON.stringify(mapData.discovered_files, null, 2),
-                      session_number: undefined
-                    });
-                  }
-                } catch {
-                  // Skip invalid files
-                }
-              }
-            }
-          }
-        }
-
-        return {
-          success: true,
-          data: {
-            projectIndex,
-            memoryStatus,
-            memoryState,
-            recentMemories: recentMemories.slice(0, 20),
-            isLoading: false
-          }
-        };
-      } catch (error) {
-        return {
-          success: false,
-          error: error instanceof Error ? error.message : 'Failed to load project context'
-        };
-      }
-    }
-  );
-
-  ipcMain.handle(
-    IPC_CHANNELS.CONTEXT_REFRESH_INDEX,
-    async (_, projectId: string): Promise<IPCResult<ProjectIndex>> => {
-      const project = projectStore.getProject(projectId);
-      if (!project) {
-        return { success: false, error: 'Project not found' };
-      }
-
-      try {
-        // Run the analyzer script to regenerate project_index.json
-        const autoBuildSource = getAutoBuildSourcePath();
-
-        if (!autoBuildSource) {
-          return {
-            success: false,
-            error: 'Auto-build source path not configured'
-          };
-        }
-
-        const analyzerPath = path.join(autoBuildSource, 'analyzer.py');
-        const indexOutputPath = path.join(project.path, AUTO_BUILD_PATHS.PROJECT_INDEX);
-
-        // Run analyzer
-        await new Promise<void>((resolve, reject) => {
-          const proc = spawn('python', [
-            analyzerPath,
-            '--project-dir', project.path,
-            '--output', indexOutputPath
-          ], {
-            cwd: project.path,
-            env: { ...process.env }
-          });
-
-          proc.on('close', (code: number) => {
-            if (code === 0) {
-              resolve();
-            } else {
-              reject(new Error(`Analyzer exited with code ${code}`));
-            }
-          });
-
-          proc.on('error', reject);
-        });
-
-        // Read the new index
-        if (existsSync(indexOutputPath)) {
-          const content = readFileSync(indexOutputPath, 'utf-8');
-          const projectIndex = JSON.parse(content);
-          return { success: true, data: projectIndex };
-        }
-
-        return { success: false, error: 'Failed to generate project index' };
-      } catch (error) {
-        return {
-          success: false,
-          error: error instanceof Error ? error.message : 'Failed to refresh project index'
-        };
-      }
-    }
-  );
-
-  ipcMain.handle(
-    IPC_CHANNELS.CONTEXT_MEMORY_STATUS,
-    async (_, projectId: string): Promise<IPCResult<GraphitiMemoryStatus>> => {
-      const project = projectStore.getProject(projectId);
-      if (!project) {
-        return { success: false, error: 'Project not found' };
-      }
-
-      // Load project .env file to check for Graphiti config
-      let projectEnvVars: Record<string, string> = {};
-      if (project.autoBuildPath) {
-        const projectEnvPath = path.join(project.path, project.autoBuildPath, '.env');
-        if (existsSync(projectEnvPath)) {
-          try {
-            const envContent = readFileSync(projectEnvPath, 'utf-8');
-            // Parse .env file inline - handle both Unix and Windows line endings
-            for (const line of envContent.split(/\r?\n/)) {
-              const trimmed = line.trim();
-              if (!trimmed || trimmed.startsWith('#')) continue;
-              const eqIndex = trimmed.indexOf('=');
-              if (eqIndex > 0) {
-                const key = trimmed.substring(0, eqIndex).trim();
-                let value = trimmed.substring(eqIndex + 1).trim();
-                if ((value.startsWith('"') && value.endsWith('"')) ||
-                    (value.startsWith("'") && value.endsWith("'"))) {
-                  value = value.slice(1, -1);
-                }
-                projectEnvVars[key] = value;
-              }
-            }
-          } catch {
-            // Continue with empty vars
-          }
-        }
-      }
-
-      // Load global settings for OpenAI API key fallback
-      let globalOpenAIKey: string | undefined;
-      if (existsSync(settingsPath)) {
-        try {
-          const settingsContent = readFileSync(settingsPath, 'utf-8');
-          const globalSettings = JSON.parse(settingsContent);
-          globalOpenAIKey = globalSettings.globalOpenAIApiKey;
-        } catch {
-          // Continue without global settings
-        }
-      }
-
-      // Check for Graphiti config: project .env > process.env
-      const graphitiEnabled =
-        projectEnvVars['GRAPHITI_ENABLED']?.toLowerCase() === 'true' ||
-        process.env.GRAPHITI_ENABLED?.toLowerCase() === 'true';
-
-      // Check for OpenAI key: project .env > global settings > process.env
-      const hasOpenAI =
-        !!projectEnvVars['OPENAI_API_KEY'] ||
-        !!globalOpenAIKey ||
-        !!process.env.OPENAI_API_KEY;
-
-      // Get Graphiti connection details from project .env or process.env
-      const graphitiHost = projectEnvVars['GRAPHITI_FALKORDB_HOST'] || process.env.GRAPHITI_FALKORDB_HOST || 'localhost';
-      const graphitiPort = parseInt(projectEnvVars['GRAPHITI_FALKORDB_PORT'] || process.env.GRAPHITI_FALKORDB_PORT || '6380', 10);
-      const graphitiDatabase = projectEnvVars['GRAPHITI_DATABASE'] || process.env.GRAPHITI_DATABASE || 'auto_build_memory';
-
-      if (!graphitiEnabled) {
-        return {
-          success: true,
-          data: {
-            enabled: false,
-            available: false,
-            reason: 'GRAPHITI_ENABLED not set to true'
-          }
-        };
-      }
-
-      if (!hasOpenAI) {
-        return {
-          success: true,
-          data: {
-            enabled: true,
-            available: false,
-            reason: 'OPENAI_API_KEY not set (required for embeddings)'
-          }
-        };
-      }
-
-      return {
-        success: true,
-        data: {
-          enabled: true,
-          available: true,
-          host: graphitiHost,
-          port: graphitiPort,
-          database: graphitiDatabase
-        }
-      };
-    }
-  );
-
-  ipcMain.handle(
-    IPC_CHANNELS.CONTEXT_SEARCH_MEMORIES,
-    async (_, projectId: string, query: string): Promise<IPCResult<ContextSearchResult[]>> => {
-      const project = projectStore.getProject(projectId);
-      if (!project) {
-        return { success: false, error: 'Project not found' };
-      }
-
-      // For now, do simple text search in file-based memories
-      // Graphiti search would require running Python subprocess
-      const results: ContextSearchResult[] = [];
-      const queryLower = query.toLowerCase();
-
-      // Get specs directory path
-      const specsBaseDir = getSpecsDir(project.autoBuildPath);
-      const specsDir = path.join(project.path, specsBaseDir);
-      if (existsSync(specsDir)) {
-        const allSpecDirs = readdirSync(specsDir)
-          .filter((f: string) => {
-            const specPath = path.join(specsDir, f);
-            return statSync(specPath).isDirectory();
-          });
-
-        for (const specDir of allSpecDirs) {
-          const memoryDir = path.join(specsDir, specDir, 'memory');
-          if (existsSync(memoryDir)) {
-            const memoryFiles = readdirSync(memoryDir)
-              .filter((f: string) => f.endsWith('.json'));
-
-            for (const memFile of memoryFiles) {
-              try {
-                const memPath = path.join(memoryDir, memFile);
-                const memContent = readFileSync(memPath, 'utf-8');
-
-                if (memContent.toLowerCase().includes(queryLower)) {
-                  const memData = JSON.parse(memContent);
-                  results.push({
-                    content: JSON.stringify(memData.insights || memData, null, 2),
-                    score: 1.0,
-                    type: 'session_insight'
-                  });
-                }
-              } catch {
-                // Skip invalid files
-              }
-            }
-          }
-        }
-      }
-
-      return { success: true, data: results.slice(0, 20) };
-    }
-  );
-
-  ipcMain.handle(
-    IPC_CHANNELS.CONTEXT_GET_MEMORIES,
-    async (_, projectId: string, limit: number = 20): Promise<IPCResult<MemoryEpisode[]>> => {
-      const project = projectStore.getProject(projectId);
-      if (!project) {
-        return { success: false, error: 'Project not found' };
-      }
-
-      const memories: MemoryEpisode[] = [];
-
-      // Get specs directory path
-      const specsBaseDir = getSpecsDir(project.autoBuildPath);
-      const specsDir = path.join(project.path, specsBaseDir);
-
-      if (existsSync(specsDir)) {
-        const sortedSpecDirs = readdirSync(specsDir)
-          .filter((f: string) => {
-            const specPath = path.join(specsDir, f);
-            return statSync(specPath).isDirectory();
-          })
-          .sort()
-          .reverse();
-
-        for (const specDir of sortedSpecDirs) {
-          const memoryDir = path.join(specsDir, specDir, 'memory');
-          if (existsSync(memoryDir)) {
-            const memoryFiles = readdirSync(memoryDir)
-              .filter((f: string) => f.endsWith('.json'))
-              .sort()
-              .reverse();
-
-            for (const memFile of memoryFiles) {
-              try {
-                const memPath = path.join(memoryDir, memFile);
-                const memContent = readFileSync(memPath, 'utf-8');
-                const memData = JSON.parse(memContent);
-
-                memories.push({
-                  id: `${specDir}-${memFile}`,
-                  type: memData.type || 'session_insight',
-                  timestamp: memData.timestamp || new Date().toISOString(),
-                  content: JSON.stringify(memData.insights || memData, null, 2),
-                  session_number: memData.session_number
-                });
-
-                if (memories.length >= limit) {
-                  break;
-                }
-              } catch {
-                // Skip invalid files
-              }
-            }
-          }
-
-          if (memories.length >= limit) {
-            break;
-          }
-        }
-      }
-
-      return { success: true, data: memories };
-    }
-  );
-
+  registerContextHandlers(getMainWindow);
 }
@@ -0,0 +1,158 @@
+# Context Handlers Module
+
+This directory contains the refactored context-related IPC handlers for the Auto Claude UI application. The handlers manage project context, memory systems (both file-based and Graphiti/FalkorDB), and project index operations.
+
+## Architecture
+
+The module is organized into focused, single-responsibility files:
+
+### Core Modules
+
+#### `utils.ts` (148 lines)
+Shared utility functions for environment configuration and parsing.
+
+**Exports:**
+- `getAutoBuildSourcePath()` - Get auto-build source path from settings
+- `parseEnvFile(content)` - Parse .env file content into key-value pairs
+- `loadProjectEnvVars(projectPath, autoBuildPath)` - Load project-specific environment variables
+- `loadGlobalSettings()` - Load global application settings
+- `isGraphitiEnabled(projectEnvVars)` - Check if Graphiti memory system is enabled
+- `hasOpenAIKey(projectEnvVars, globalSettings)` - Check if OpenAI API key is available
+- `getGraphitiConnectionDetails(projectEnvVars)` - Get FalkorDB connection configuration
+
+**Types:**
+- `EnvironmentVars` - Environment variable dictionary
+- `GlobalSettings` - Global application settings
+- `GraphitiConnectionDetails` - FalkorDB connection details
+
+#### `memory-status-handlers.ts` (130 lines)
+Handlers for checking Graphiti/memory system configuration status.
+
+**Exports:**
+- `loadGraphitiStateFromSpecs(projectPath, autoBuildPath)` - Load Graphiti state from most recent spec
+- `buildMemoryStatus(projectPath, autoBuildPath, memoryState)` - Build memory status from environment
+- `registerMemoryStatusHandlers(getMainWindow)` - Register IPC handlers
+
+**IPC Channels:**
+- `CONTEXT_MEMORY_STATUS` - Get memory system status
+
+#### `memory-data-handlers.ts` (242 lines)
+Handlers for retrieving and searching memories (both file-based and FalkorDB).
+
+**Exports:**
+- `loadFileBasedMemories(specsDir, limit)` - Load memories from spec files
+- `searchFileBasedMemories(specsDir, query, limit)` - Search file-based memories
+- `registerMemoryDataHandlers(getMainWindow)` - Register IPC handlers
+
+**IPC Channels:**
+- `CONTEXT_GET_MEMORIES` - Get recent memories (with FalkorDB fallback)
+- `CONTEXT_SEARCH_MEMORIES` - Search memories by query
+
+**Features:**
+- Dual-source memory loading (FalkorDB primary, file-based fallback)
+- Session insights extraction from spec directories
+- Codebase map integration
+- Semantic search support (when Graphiti is available)
+
+#### `project-context-handlers.ts` (199 lines)
+Handlers for project context and index operations.
+
+**Exports:**
+- `registerProjectContextHandlers(getMainWindow)` - Register IPC handlers
+
+**IPC Channels:**
+- `CONTEXT_GET` - Get full project context (index, memory status, recent memories)
+- `CONTEXT_REFRESH_INDEX` - Refresh project index by running analyzer
+
+**Features:**
+- Project index loading and caching
+- Graphiti state detection from specs
+- Memory status aggregation
+- Analyzer script execution for index regeneration
+
+#### `index.ts` (21 lines)
+Main entry point that aggregates all context handlers.
+
+**Exports:**
+- `registerContextHandlers(getMainWindow)` - Register all context-related handlers
+- Re-exports all utility functions and handler functions
+
+## Refactoring Benefits
+
+### Before (676 lines in single file)
+- All context logic in one large file
+- Difficult to navigate and maintain
+- Repeated code for environment parsing
+- Hard to test individual components
+- No clear separation of concerns
+
+### After (29 lines main + 740 lines in 5 focused modules)
+- **Single Responsibility**: Each module has one clear purpose
+- **Reusability**: Utility functions can be imported and tested independently
+- **Maintainability**: Easier to find and fix issues in specific areas
+- **Testability**: Each module can be unit tested in isolation
+- **Readability**: Clear module boundaries with descriptive names
+- **Scalability**: Easy to add new handlers without cluttering existing files
+
+## Module Dependencies
+
+```
+context-handlers.ts (main entry)
+    ↓
+context/index.ts (aggregator)
+    ↓
+    ├── utils.ts (no dependencies, pure utilities)
+    ├── memory-status-handlers.ts (depends on: utils)
+    ├── memory-data-handlers.ts (depends on: utils, falkordb-service)
+    └── project-context-handlers.ts (depends on: utils, memory-status-handlers, memory-data-handlers)
+```
+
+## Usage Example
+
+```typescript
+import { registerContextHandlers } from './ipc-handlers/context-handlers';
+
+// In main process setup
+const getMainWindow = () => mainWindow;
+registerContextHandlers(getMainWindow);
+```
+
+## Testing Strategy
+
+Each module can be tested independently:
+
+```typescript
+// Example: Testing utility functions
+import { parseEnvFile, isGraphitiEnabled } from './utils';
+
+test('parseEnvFile handles quotes correctly', () => {
+  const content = 'API_KEY="test-key"\nDEBUG=true';
+  const vars = parseEnvFile(content);
+  expect(vars.API_KEY).toBe('test-key');
+  expect(vars.DEBUG).toBe('true');
+});
+
+// Example: Testing memory status
+import { buildMemoryStatus } from './memory-status-handlers';
+
+test('buildMemoryStatus returns correct status', () => {
+  const status = buildMemoryStatus('/path/to/project', 'auto-claude');
+  expect(status).toHaveProperty('enabled');
+  expect(status).toHaveProperty('available');
+});
+```
+
+## Future Enhancements
+
+- Add TypeScript interface documentation for all data structures
+- Implement caching layer for frequently accessed context data
+- Add telemetry for memory system performance
+- Support additional memory providers beyond FalkorDB
+- Implement memory compression for large session insights
+
+## Related Documentation
+
+- [Project Memory System](../../../../auto-claude/memory.py)
+- [Graphiti Memory Integration](../../../../auto-claude/graphiti_memory.py)
+- [FalkorDB Service](../../falkordb-service.ts)
+- [IPC Channels](../../../shared/constants.ts)
@@ -0,0 +1,21 @@
+import type { BrowserWindow } from 'electron';
+import { registerProjectContextHandlers } from './project-context-handlers';
+import { registerMemoryStatusHandlers } from './memory-status-handlers';
+import { registerMemoryDataHandlers } from './memory-data-handlers';
+
+/**
+ * Register all context-related IPC handlers
+ */
+export function registerContextHandlers(
+  getMainWindow: () => BrowserWindow | null
+): void {
+  registerProjectContextHandlers(getMainWindow);
+  registerMemoryStatusHandlers(getMainWindow);
+  registerMemoryDataHandlers(getMainWindow);
+}
+
+// Re-export utility functions for testing or external use
+export * from './utils';
+export * from './memory-status-handlers';
+export * from './memory-data-handlers';
+export * from './project-context-handlers';
@@ -0,0 +1,242 @@
+import { ipcMain } from 'electron';
+import type { BrowserWindow } from 'electron';
+import path from 'path';
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { IPC_CHANNELS, getSpecsDir } from '../../../shared/constants';
+import type {
+  IPCResult,
+  MemoryEpisode,
+  ContextSearchResult
+} from '../../../shared/types';
+import { projectStore } from '../../project-store';
+import { getFalkorDBService } from '../../falkordb-service';
+import {
+  loadProjectEnvVars,
+  isGraphitiEnabled,
+  getGraphitiConnectionDetails
+} from './utils';
+
+/**
+ * Load file-based memories from spec directories
+ */
+export function loadFileBasedMemories(
+  specsDir: string,
+  limit: number
+): MemoryEpisode[] {
+  const memories: MemoryEpisode[] = [];
+
+  if (!existsSync(specsDir)) {
+    return memories;
+  }
+
+  const recentSpecDirs = readdirSync(specsDir)
+    .filter((f: string) => {
+      const specPath = path.join(specsDir, f);
+      return statSync(specPath).isDirectory();
+    })
+    .sort()
+    .reverse()
+    .slice(0, 10); // Last 10 specs
+
+  for (const specDir of recentSpecDirs) {
+    const memoryDir = path.join(specsDir, specDir, 'memory');
+    if (!existsSync(memoryDir)) continue;
+
+    // Load session insights
+    const sessionInsightsDir = path.join(memoryDir, 'session_insights');
+    if (existsSync(sessionInsightsDir)) {
+      const sessionFiles = readdirSync(sessionInsightsDir)
+        .filter((f: string) => f.startsWith('session_') && f.endsWith('.json'))
+        .sort()
+        .reverse();
+
+      for (const sessionFile of sessionFiles.slice(0, 3)) {
+        try {
+          const sessionPath = path.join(sessionInsightsDir, sessionFile);
+          const sessionContent = readFileSync(sessionPath, 'utf-8');
+          const sessionData = JSON.parse(sessionContent);
+
+          if (sessionData.session_number !== undefined) {
+            memories.push({
+              id: `${specDir}-${sessionFile}`,
+              type: 'session_insight',
+              timestamp: sessionData.timestamp || new Date().toISOString(),
+              content: JSON.stringify({
+                discoveries: sessionData.discoveries,
+                what_worked: sessionData.what_worked,
+                what_failed: sessionData.what_failed,
+                recommendations: sessionData.recommendations_for_next_session,
+                subtasks_completed: sessionData.subtasks_completed
+              }, null, 2),
+              session_number: sessionData.session_number
+            });
+          }
+        } catch {
+          // Skip invalid files
+        }
+      }
+    }
+
+    // Load codebase map
+    const codebaseMapPath = path.join(memoryDir, 'codebase_map.json');
+    if (existsSync(codebaseMapPath)) {
+      try {
+        const mapContent = readFileSync(codebaseMapPath, 'utf-8');
+        const mapData = JSON.parse(mapContent);
+        if (mapData.discovered_files && Object.keys(mapData.discovered_files).length > 0) {
+          memories.push({
+            id: `${specDir}-codebase_map`,
+            type: 'codebase_map',
+            timestamp: mapData.last_updated || new Date().toISOString(),
+            content: JSON.stringify(mapData.discovered_files, null, 2),
+            session_number: undefined
+          });
+        }
+      } catch {
+        // Skip invalid files
+      }
+    }
+  }
+
+  return memories.slice(0, limit);
+}
+
+/**
+ * Search file-based memories for a query
+ */
+export function searchFileBasedMemories(
+  specsDir: string,
+  query: string,
+  limit: number
+): ContextSearchResult[] {
+  const results: ContextSearchResult[] = [];
+  const queryLower = query.toLowerCase();
+
+  if (!existsSync(specsDir)) {
+    return results;
+  }
+
+  const allSpecDirs = readdirSync(specsDir)
+    .filter((f: string) => {
+      const specPath = path.join(specsDir, f);
+      return statSync(specPath).isDirectory();
+    });
+
+  for (const specDir of allSpecDirs) {
+    const memoryDir = path.join(specsDir, specDir, 'memory');
+    if (!existsSync(memoryDir)) continue;
+
+    const memoryFiles = readdirSync(memoryDir)
+      .filter((f: string) => f.endsWith('.json'));
+
+    for (const memFile of memoryFiles) {
+      try {
+        const memPath = path.join(memoryDir, memFile);
+        const memContent = readFileSync(memPath, 'utf-8');
+
+        if (memContent.toLowerCase().includes(queryLower)) {
+          const memData = JSON.parse(memContent);
+          results.push({
+            content: JSON.stringify(memData.insights || memData, null, 2),
+            score: 1.0,
+            type: 'session_insight'
+          });
+        }
+      } catch {
+        // Skip invalid files
+      }
+    }
+  }
+
+  return results.slice(0, limit);
+}
+
+/**
+ * Register memory data handlers
+ */
+export function registerMemoryDataHandlers(
+  getMainWindow: () => BrowserWindow | null
+): void {
+  // Get all memories
+  ipcMain.handle(
+    IPC_CHANNELS.CONTEXT_GET_MEMORIES,
+    async (_, projectId: string, limit: number = 20): Promise<IPCResult<MemoryEpisode[]>> => {
+      const project = projectStore.getProject(projectId);
+      if (!project) {
+        return { success: false, error: 'Project not found' };
+      }
+
+      const projectEnvVars = loadProjectEnvVars(project.path, project.autoBuildPath);
+      const graphitiEnabled = isGraphitiEnabled(projectEnvVars);
+
+      // Try FalkorDB first if available
+      if (graphitiEnabled) {
+        try {
+          const connDetails = getGraphitiConnectionDetails(projectEnvVars);
+          const falkorService = getFalkorDBService({
+            host: connDetails.host,
+            port: connDetails.port,
+          });
+          const falkorMemories = await falkorService.getAllMemories(limit);
+          if (falkorMemories.length > 0) {
+            return { success: true, data: falkorMemories };
+          }
+        } catch (error) {
+          console.warn('Failed to get memories from FalkorDB, falling back to file-based:', error);
+        }
+      }
+
+      // Fall back to file-based memories
+      const specsBaseDir = getSpecsDir(project.autoBuildPath);
+      const specsDir = path.join(project.path, specsBaseDir);
+      const memories = loadFileBasedMemories(specsDir, limit);
+
+      return { success: true, data: memories };
+    }
+  );
+
+  // Search memories
+  ipcMain.handle(
+    IPC_CHANNELS.CONTEXT_SEARCH_MEMORIES,
+    async (_, projectId: string, query: string): Promise<IPCResult<ContextSearchResult[]>> => {
+      const project = projectStore.getProject(projectId);
+      if (!project) {
+        return { success: false, error: 'Project not found' };
+      }
+
+      const projectEnvVars = loadProjectEnvVars(project.path, project.autoBuildPath);
+      const graphitiEnabled = isGraphitiEnabled(projectEnvVars);
+
+      // Try FalkorDB search if available
+      if (graphitiEnabled) {
+        try {
+          const connDetails = getGraphitiConnectionDetails(projectEnvVars);
+          const falkorService = getFalkorDBService({
+            host: connDetails.host,
+            port: connDetails.port,
+          });
+          const falkorResults = await falkorService.searchMemories(query, 20);
+          if (falkorResults.length > 0) {
+            return {
+              success: true,
+              data: falkorResults.map(r => ({
+                content: r.content,
+                score: r.score || 1.0,
+                type: r.type
+              }))
+            };
+          }
+        } catch (error) {
+          console.warn('Failed to search FalkorDB, falling back to file-based:', error);
+        }
+      }
+
+      // Fall back to file-based search
+      const specsBaseDir = getSpecsDir(project.autoBuildPath);
+      const specsDir = path.join(project.path, specsBaseDir);
+      const results = searchFileBasedMemories(specsDir, query, 20);
+
+      return { success: true, data: results };
+    }
+  );
+}
@@ -0,0 +1,130 @@
+import { ipcMain } from 'electron';
+import type { BrowserWindow } from 'electron';
+import path from 'path';
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { IPC_CHANNELS, getSpecsDir, AUTO_BUILD_PATHS } from '../../../shared/constants';
+import type { IPCResult, GraphitiMemoryStatus, GraphitiMemoryState } from '../../../shared/types';
+import { projectStore } from '../../project-store';
+import {
+  loadProjectEnvVars,
+  loadGlobalSettings,
+  isGraphitiEnabled,
+  hasOpenAIKey,
+  getGraphitiConnectionDetails
+} from './utils';
+
+/**
+ * Load Graphiti state from most recent spec directory
+ */
+export function loadGraphitiStateFromSpecs(
+  projectPath: string,
+  autoBuildPath?: string
+): GraphitiMemoryState | null {
+  if (!autoBuildPath) return null;
+
+  const specsBaseDir = getSpecsDir(autoBuildPath);
+  const specsDir = path.join(projectPath, specsBaseDir);
+
+  if (!existsSync(specsDir)) {
+    return null;
+  }
+
+  const specDirs = readdirSync(specsDir)
+    .filter((f: string) => {
+      const specPath = path.join(specsDir, f);
+      return statSync(specPath).isDirectory();
+    })
+    .sort()
+    .reverse();
+
+  for (const specDir of specDirs) {
+    const statePath = path.join(specsDir, specDir, AUTO_BUILD_PATHS.GRAPHITI_STATE);
+    if (existsSync(statePath)) {
+      try {
+        const stateContent = readFileSync(statePath, 'utf-8');
+        return JSON.parse(stateContent);
+      } catch {
+        continue;
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Build memory status from environment configuration
+ */
+export function buildMemoryStatus(
+  projectPath: string,
+  autoBuildPath?: string,
+  memoryState?: GraphitiMemoryState | null
+): GraphitiMemoryStatus {
+  const projectEnvVars = loadProjectEnvVars(projectPath, autoBuildPath);
+  const globalSettings = loadGlobalSettings();
+
+  // If we have initialized state from specs, use it
+  if (memoryState?.initialized) {
+    const connDetails = getGraphitiConnectionDetails(projectEnvVars);
+    return {
+      enabled: true,
+      available: true,
+      database: memoryState.database || 'auto_claude_memory',
+      host: connDetails.host,
+      port: connDetails.port
+    };
+  }
+
+  // Check environment configuration
+  const graphitiEnabled = isGraphitiEnabled(projectEnvVars);
+  const hasOpenAI = hasOpenAIKey(projectEnvVars, globalSettings);
+
+  if (!graphitiEnabled) {
+    return {
+      enabled: false,
+      available: false,
+      reason: 'Graphiti not configured'
+    };
+  }
+
+  if (!hasOpenAI) {
+    return {
+      enabled: true,
+      available: false,
+      reason: 'OPENAI_API_KEY not set (required for Graphiti embeddings)'
+    };
+  }
+
+  const connDetails = getGraphitiConnectionDetails(projectEnvVars);
+  return {
+    enabled: true,
+    available: true,
+    host: connDetails.host,
+    port: connDetails.port,
+    database: connDetails.database
+  };
+}
+
+/**
+ * Register memory status handlers
+ */
+export function registerMemoryStatusHandlers(
+  getMainWindow: () => BrowserWindow | null
+): void {
+  ipcMain.handle(
+    IPC_CHANNELS.CONTEXT_MEMORY_STATUS,
+    async (_, projectId: string): Promise<IPCResult<GraphitiMemoryStatus>> => {
+      const project = projectStore.getProject(projectId);
+      if (!project) {
+        return { success: false, error: 'Project not found' };
+      }
+
+      const memoryStatus = buildMemoryStatus(project.path, project.autoBuildPath);
+
+      return {
+        success: true,
+        data: memoryStatus
+      };
+    }
+  );
+}
@@ -0,0 +1,199 @@
+import { ipcMain } from 'electron';
+import type { BrowserWindow } from 'electron';
+import path from 'path';
+import { existsSync, readFileSync } from 'fs';
+import { spawn } from 'child_process';
+import { IPC_CHANNELS, getSpecsDir, AUTO_BUILD_PATHS } from '../../../shared/constants';
+import type {
+  IPCResult,
+  ProjectContextData,
+  ProjectIndex,
+  MemoryEpisode
+} from '../../../shared/types';
+import { projectStore } from '../../project-store';
+import { getFalkorDBService } from '../../falkordb-service';
+import {
+  getAutoBuildSourcePath,
+  loadProjectEnvVars,
+  isGraphitiEnabled,
+  getGraphitiConnectionDetails
+} from './utils';
+import {
+  loadGraphitiStateFromSpecs,
+  buildMemoryStatus
+} from './memory-status-handlers';
+import { loadFileBasedMemories } from './memory-data-handlers';
+
+/**
+ * Load project index from file
+ */
+function loadProjectIndex(projectPath: string): ProjectIndex | null {
+  const indexPath = path.join(projectPath, AUTO_BUILD_PATHS.PROJECT_INDEX);
+  if (!existsSync(indexPath)) {
+    return null;
+  }
+
+  try {
+    const content = readFileSync(indexPath, 'utf-8');
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Load recent memories with FalkorDB fallback
+ */
+async function loadRecentMemories(
+  projectPath: string,
+  autoBuildPath: string | undefined,
+  memoryStatusAvailable: boolean,
+  memoryHost?: string,
+  memoryPort?: number
+): Promise<MemoryEpisode[]> {
+  let recentMemories: MemoryEpisode[] = [];
+
+  // Try to load from FalkorDB first if Graphiti is available
+  if (memoryStatusAvailable && memoryHost && memoryPort) {
+    try {
+      const falkorService = getFalkorDBService({
+        host: memoryHost,
+        port: memoryPort,
+      });
+      const falkorMemories = await falkorService.getAllMemories(20);
+      if (falkorMemories.length > 0) {
+        recentMemories = falkorMemories;
+      }
+    } catch (error) {
+      console.warn('Failed to load memories from FalkorDB, falling back to file-based:', error);
+    }
+  }
+
+  // Fall back to file-based memory if no FalkorDB memories found
+  if (recentMemories.length === 0) {
+    const specsBaseDir = getSpecsDir(autoBuildPath);
+    const specsDir = path.join(projectPath, specsBaseDir);
+    recentMemories = loadFileBasedMemories(specsDir, 20);
+  }
+
+  return recentMemories;
+}
+
+/**
+ * Register project context handlers
+ */
+export function registerProjectContextHandlers(
+  getMainWindow: () => BrowserWindow | null
+): void {
+  // Get full project context
+  ipcMain.handle(
+    IPC_CHANNELS.CONTEXT_GET,
+    async (_, projectId: string): Promise<IPCResult<ProjectContextData>> => {
+      const project = projectStore.getProject(projectId);
+      if (!project) {
+        return { success: false, error: 'Project not found' };
+      }
+
+      try {
+        // Load project index
+        const projectIndex = loadProjectIndex(project.path);
+
+        // Load graphiti state from most recent spec
+        const memoryState = loadGraphitiStateFromSpecs(project.path, project.autoBuildPath);
+
+        // Build memory status
+        const memoryStatus = buildMemoryStatus(
+          project.path,
+          project.autoBuildPath,
+          memoryState
+        );
+
+        // Load recent memories
+        const recentMemories = await loadRecentMemories(
+          project.path,
+          project.autoBuildPath,
+          memoryStatus.available,
+          memoryStatus.host,
+          memoryStatus.port
+        );
+
+        return {
+          success: true,
+          data: {
+            projectIndex,
+            memoryStatus,
+            memoryState,
+            recentMemories,
+            isLoading: false
+          }
+        };
+      } catch (error) {
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : 'Failed to load project context'
+        };
+      }
+    }
+  );
+
+  // Refresh project index
+  ipcMain.handle(
+    IPC_CHANNELS.CONTEXT_REFRESH_INDEX,
+    async (_, projectId: string): Promise<IPCResult<ProjectIndex>> => {
+      const project = projectStore.getProject(projectId);
+      if (!project) {
+        return { success: false, error: 'Project not found' };
+      }
+
+      try {
+        // Run the analyzer script to regenerate project_index.json
+        const autoBuildSource = getAutoBuildSourcePath();
+
+        if (!autoBuildSource) {
+          return {
+            success: false,
+            error: 'Auto-build source path not configured'
+          };
+        }
+
+        const analyzerPath = path.join(autoBuildSource, 'analyzer.py');
+        const indexOutputPath = path.join(project.path, AUTO_BUILD_PATHS.PROJECT_INDEX);
+
+        // Run analyzer
+        await new Promise<void>((resolve, reject) => {
+          const proc = spawn('python', [
+            analyzerPath,
+            '--project-dir', project.path,
+            '--output', indexOutputPath
+          ], {
+            cwd: project.path,
+            env: { ...process.env }
+          });
+
+          proc.on('close', (code: number) => {
+            if (code === 0) {
+              resolve();
+            } else {
+              reject(new Error(`Analyzer exited with code ${code}`));
+            }
+          });
+
+          proc.on('error', reject);
+        });
+
+        // Read the new index
+        const projectIndex = loadProjectIndex(project.path);
+        if (projectIndex) {
+          return { success: true, data: projectIndex };
+        }
+
+        return { success: false, error: 'Failed to generate project index' };
+      } catch (error) {
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : 'Failed to refresh project index'
+        };
+      }
+    }
+  );
+}
@@ -0,0 +1,148 @@
+import { app } from 'electron';
+import path from 'path';
+import { existsSync, readFileSync } from 'fs';
+
+export interface EnvironmentVars {
+  [key: string]: string;
+}
+
+export interface GlobalSettings {
+  autoBuildPath?: string;
+  globalOpenAIApiKey?: string;
+}
+
+const settingsPath = path.join(app.getPath('userData'), 'settings.json');
+
+/**
+ * Get the auto-build source path from settings
+ */
+export function getAutoBuildSourcePath(): string | null {
+  if (existsSync(settingsPath)) {
+    try {
+      const content = readFileSync(settingsPath, 'utf-8');
+      const settings = JSON.parse(content);
+      if (settings.autoBuildPath && existsSync(settings.autoBuildPath)) {
+        return settings.autoBuildPath;
+      }
+    } catch {
+      // Fall through to null
+    }
+  }
+  return null;
+}
+
+/**
+ * Parse .env file content into key-value pairs
+ * Handles both Unix and Windows line endings
+ */
+export function parseEnvFile(envContent: string): EnvironmentVars {
+  const vars: EnvironmentVars = {};
+
+  for (const line of envContent.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    const eqIndex = trimmed.indexOf('=');
+    if (eqIndex > 0) {
+      const key = trimmed.substring(0, eqIndex).trim();
+      let value = trimmed.substring(eqIndex + 1).trim();
+
+      // Remove quotes if present
+      if ((value.startsWith('"') && value.endsWith('"')) ||
+          (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+      }
+
+      vars[key] = value;
+    }
+  }
+
+  return vars;
+}
+
+/**
+ * Load environment variables from project .env file
+ */
+export function loadProjectEnvVars(projectPath: string, autoBuildPath?: string): EnvironmentVars {
+  if (!autoBuildPath) {
+    return {};
+  }
+
+  const projectEnvPath = path.join(projectPath, autoBuildPath, '.env');
+  if (!existsSync(projectEnvPath)) {
+    return {};
+  }
+
+  try {
+    const envContent = readFileSync(projectEnvPath, 'utf-8');
+    return parseEnvFile(envContent);
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Load global settings from user data directory
+ */
+export function loadGlobalSettings(): GlobalSettings {
+  if (!existsSync(settingsPath)) {
+    return {};
+  }
+
+  try {
+    const settingsContent = readFileSync(settingsPath, 'utf-8');
+    return JSON.parse(settingsContent);
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Check if Graphiti is enabled in project or global environment
+ */
+export function isGraphitiEnabled(projectEnvVars: EnvironmentVars): boolean {
+  return (
+    projectEnvVars['GRAPHITI_ENABLED']?.toLowerCase() === 'true' ||
+    process.env.GRAPHITI_ENABLED?.toLowerCase() === 'true'
+  );
+}
+
+/**
+ * Check if OpenAI API key is available
+ * Priority: project .env > global settings > process.env
+ */
+export function hasOpenAIKey(projectEnvVars: EnvironmentVars, globalSettings: GlobalSettings): boolean {
+  return !!(
+    projectEnvVars['OPENAI_API_KEY'] ||
+    globalSettings.globalOpenAIApiKey ||
+    process.env.OPENAI_API_KEY
+  );
+}
+
+/**
+ * Get Graphiti connection details
+ */
+export interface GraphitiConnectionDetails {
+  host: string;
+  port: number;
+  database: string;
+}
+
+export function getGraphitiConnectionDetails(projectEnvVars: EnvironmentVars): GraphitiConnectionDetails {
+  const host = projectEnvVars['GRAPHITI_FALKORDB_HOST'] ||
+               process.env.GRAPHITI_FALKORDB_HOST ||
+               'localhost';
+
+  const port = parseInt(
+    projectEnvVars['GRAPHITI_FALKORDB_PORT'] ||
+    process.env.GRAPHITI_FALKORDB_PORT ||
+    '6380',
+    10
+  );
+
+  const database = projectEnvVars['GRAPHITI_DATABASE'] ||
+                   process.env.GRAPHITI_DATABASE ||
+                   'auto_claude_memory';
+
+  return { host, port, database };
+}
--- a/Show More
+++ b/Show More