Esper

A developer productivity daemon that observes your workflow and suggests automations via Claude.

Esper runs in the background, watching your file changes, git activity, screen content, and active windows. It uses Claude to detect patterns and delivers insights through Claude Code integration, macOS notifications, and a knowledge base.

Quick Start

# Install dependencies
bun install

# Start observing (zero-config, sets everything up on first run)
bun run src/index.ts start

# Check status
bun run src/index.ts status

# View insights
bun run src/index.ts insights

# Stop
bun run src/index.ts stop

What It Observes

Observer	Method	Interval
File system	chokidar (FSEvents)	Real-time
Git	Ref polling	10s
Screen	screencapture + Claude Vision	30s
Active window	osascript	5s

Claude Code Integration

Esper integrates with Claude Code via MCP. Add the .mcp.json to your project:

{
  "mcpServers": {
    "esper": {
      "command": "bun",
      "args": ["run", "path/to/esper/src/mcp/server.ts"]
    }
  }
}

Claude Code can then use these tools:

• get_recent_activity — what you've been doing
• get_insights — automation suggestions
• get_developer_context — your current state (branch, focus mode, active files)

Architecture

Observers → EventBus (+ SQLite WAL) → Analyzers → Actions
                    ↓
              MCP Server ← Claude Code

Configuration

Config lives at ~/.config/esper/esper.toml (auto-created on first run).

[api]
model = "claude-sonnet-4-20250514"
max_requests_per_hour = 12

[observers.screen]
enabled = true
capture_interval_seconds = 30

Requirements

• macOS (uses screencapture, osascript)
• Bun runtime
• ANTHROPIC_API_KEY environment variable (for analysis features)

License

MIT