path: root/AI_AGENT_SETUP.md

# AI Agent Access Setup Guide

## Quick Start

### 1. Generate API Key
```bash
# Generate a secure 64-character API key
openssl rand -hex 32
```

Example output: `a1b2c3d4e5f6...`

### 2. Add to Environment
Add to your `.env` file:
```bash
AI_AGENT_API_KEY=a1b2c3d4e5f6...
```

### 3. Start the Dashboard
```bash
go run cmd/dashboard/main.go
```

You should see:
```
AI agent access enabled at /api/claude/snapshot
Starting server on http://localhost:8080
```

### 4. Test the Endpoint
```bash
curl -H "Authorization: Bearer a1b2c3d4e5f6..." \
     http://localhost:8080/api/claude/snapshot | jq .
```

## Usage from Claude.ai

### Method 1: Direct WebFetch
When conversing with Claude, share:

**URL:** `http://localhost:8080/api/claude/snapshot`
**Token:** `a1b2c3d4e5f6...` (share separately, not in chat history)

Claude can then fetch your dashboard:
```
User: "What tasks do I have today?"

Claude: [Calls WebFetch with Authorization header]
Claude: "You have 3 tasks due today:
1. Review PRs (Work, Priority 4)
2. Buy groceries (Personal, Priority 1)
3. Call dentist (Health, Priority 2)"
```

### Method 2: MCP Server (Advanced)
If you have Claude Desktop with MCP support:

Add to your MCP config:
```json
{
  "mcpServers": {
    "personal-dashboard": {
      "command": "curl",
      "args": [
        "-H",
        "Authorization: Bearer YOUR_TOKEN_HERE",
        "-s",
        "http://localhost:8080/api/claude/snapshot"
      ]
    }
  }
}
```

## Response Format

### Successful Response (200 OK)
```json
{
  "generated_at": "2026-01-09T15:30:00Z",
  "tasks": {
    "today": [
      {
        "id": "task_123",
        "content": "Review PRs",
        "priority": 4,
        "due": "2026-01-09T17:00:00Z",
        "project": "Work",
        "completed": false
      }
    ],
    "overdue": [],
    "next_7_days": []
  },
  "meals": {
    "today": {
      "date": "2026-01-09",
      "breakfast": "Oatmeal with protein powder",
      "lunch": "Chicken salad",
      "dinner": "Salmon with veggies"
    },
    "next_7_days": []
  },
  "notes": {
    "recent": [
      {
        "title": "Sprint planning notes",
        "modified": "2026-01-09T10:15:00Z",
        "preview": "Discussed Q1 goals and team capacity...",
        "path": "work/sprint-planning.md"
      }
    ]
  },
  "trello_boards": [
    {
      "id": "board_123",
      "name": "Work Projects",
      "cards": [
        {
          "id": "card_456",
          "name": "Complete project proposal",
          "list": "In Progress",
          "due": "2026-01-15T00:00:00Z",
          "url": "https://trello.com/c/card456"
        }
      ]
    }
  ]
}
```

### Error Response (401 Unauthorized)
```json
{
  "error": "unauthorized",
  "message": "Invalid or missing token"
}
```

## Security Best Practices

### ✅ Do
- Generate a long, random key (32+ bytes)
- Store key in `.env` file (gitignored)
- Use HTTPS in production
- Rotate key periodically (change in `.env`)
- Share token with Claude separately from URL

### ❌ Don't
- Commit API key to git
- Share key in chat history
- Use simple/guessable keys
- Expose over HTTP in production
- Include key in URL query parameters

## Data Limits

The endpoint is optimized for AI consumption:

- **Tasks**: Today + overdue + next 7 days only
- **Notes**: 10 most recent, 150 char preview each
- **Meals**: Today + next 7 days
- **Trello**: All boards and cards
- **Total Response**: < 100KB (typically 10-50KB)

## Caching

- Responses are cached for 5 minutes
- Same cache as web dashboard
- Reduces load on external APIs (Todoist, Trello, etc.)

## Troubleshooting

### "Invalid or missing token"
- Check `Authorization: Bearer` prefix is included
- Verify token matches `.env` file exactly
- No extra spaces or newlines in token

### "AI agent access not configured"
- Ensure `AI_AGENT_API_KEY` is set in `.env`
- Restart the server after changing `.env`

### Empty response sections
- Trello/Todoist/PlanToEat APIs may be down
- Check dashboard web UI to see if data loads there
- Review server logs for API errors

## Production Deployment

### With Caddy (Automatic HTTPS)
```caddyfile
dashboard.yourdomain.com {
    reverse_proxy localhost:8080
}
```

### With nginx
```nginx
server {
    listen 443 ssl http2;
    server_name dashboard.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

Then share with Claude:
- **URL**: `https://dashboard.yourdomain.com/api/claude/snapshot`
- **Token**: (your API key)

## Example Claude Conversations

### Check Today's Tasks
```
User: "What do I need to do today?"

Claude: [Fetches /api/claude/snapshot]

Claude: "Here's what you have for today:

Tasks:
- Review PRs (Work, Priority 4, due 5pm)
- Buy groceries (Personal, Priority 1)

Meals:
- Breakfast: Oatmeal
- Lunch: Chicken salad
- Dinner: Salmon with veggies"
```

### Check Overdue Items
```
User: "Do I have anything overdue?"

Claude: [Fetches snapshot]

Claude: "You have 2 overdue tasks:
1. Submit expense report (Work, was due Jan 5)
2. Schedule dentist appointment (Health, was due Jan 7)"
```

### Review Recent Notes
```
User: "What notes have I created recently?"

Claude: [Fetches snapshot]

Claude: "Your 3 most recent notes:
1. Sprint planning notes (modified today at 10:15am)
2. Customer feedback summary (modified Jan 8)
3. Architecture decision record (modified Jan 6)"
```

## Rate Limiting (Future)

Currently no rate limiting. For production use, consider adding:
- 100 requests/hour per token
- Implement using middleware
- Return 429 status when exceeded

## Next Steps

1. ✅ Generate API key
2. ✅ Add to .env
3. ✅ Test with curl
4. ✅ Share URL + token with Claude
5. ✅ Start conversing!

Enjoy your AI-powered personal dashboard! 🚀