dear-claude

<p align="center">
  <img src="assets/marketing/hero-poster.png" alt="Dear Claude - Just say Dear Claude" width="500">
</p>

<h1 align="center">Dear Claude</h1>

<p align="center">
  <strong>MCP server that triggers local Claude Code instances from external platforms.</strong><br>
  Say "Dear Claude" in Linear, GitHub, Jira, GitLab, Notion, or Obsidian — and a Claude Code instance spins up to handle it.
</p>

<p align="center">
  <em>Your notes become architecture. Your tasks become pull requests.</em>
</p>

---

## What is this?

Dear Claude is an MCP (Model Context Protocol) server that watches your project management tools for the phrase **"Dear Claude"**. When detected, it spawns a local Claude Code instance that:

- Reads the issue/comment/note context
- Executes the requested task (code, review, create tasks, etc.)
- Posts results back to the originating platform
- Persists sessions for 7 days so you can have multi-turn conversations

**No Anthropic API keys needed.** Works with your existing Claude Code subscription. 100% local and private — your code never leaves your machine.

## Supported Platforms

| Platform | Trigger on issue/PR | Trigger on comment | Comment back | Emoji reactions | Sub-tasks | PR/MR review |
|----------|:------------------:|:-----------------:|:------------:|:--------------:|:---------:|:------------:|
| GitHub   | Yes | Yes | Yes | Yes | - | Yes |
| Linear   | Yes | Yes | Yes | Yes | Yes | - |
| Jira     | Yes | Yes | Yes | - | Yes | - |
| GitLab   | Yes | Yes | Yes | Yes | - | Yes |
| Notion   | Yes | Yes | Yes | - | - | - |
| Obsidian | Yes | - | Yes | - | - | - |

## Cross-Platform Orchestration

Instances from **any** platform get API access to **all** configured platforms. This enables workflows like:

1. Write a spec in **Obsidian** → "Dear Claude, create these tasks in Linear"
2. Discuss on **Linear** → "Dear Claude, code this on GitHub"
3. Review on **GitHub** → "Dear Claude, resolve the merge conflicts"
4. **Parallel coding** → Claude spawns multiple instances, one per branch, using git worktrees

## Quick Start

### Install in one line

```bash
claude mcp add dear-claude -- bunx dear-claude start --mcp
```

That's it. Start Claude Code and Dear Claude is ready.

### Prerequisites

- [Claude Code](https://claude.ai/claude-code) CLI installed (`claude` command available)
- [Bun](https://bun.sh) runtime (for `bunx`)
- [Tailscale](https://tailscale.com/download) with Funnel enabled (for webhooks from external platforms)

### Manual setup (alternative)

If you prefer manual configuration, add to `~/.claude.json` under `mcpServers`:

```json
{
  "mcpServers": {
    "dear-claude": {
      "command": "bunx",
      "args": ["dear-claude", "start", "--mcp"],
      "env": {
        "DEAR_CLAUDE_PORT": "3334",
        "GITHUB_CLIENT_ID": "...",
        "GITHUB_CLIENT_SECRET": "...",
        "GITHUB_WEBHOOK_SECRET": "...",
        "LINEAR_CLIENT_ID": "...",
        "LINEAR_CLIENT_SECRET": "...",
        "LINEAR_WEBHOOK_SECRET": "..."
      }
    }
  }
}
```

Then start Claude Code:

```bash
claude
```

The MCP server starts automatically, sets up Tailscale Funnel, and prints your public webhook URLs.

---

## Platform Setup

### Tailscale Funnel

Dear Claude uses [Tailscale Funnel](https://tailscale.com/kb/1223/funnel) for stable public HTTPS URLs to receive webhooks. Setup is mostly automatic.

1. **Install Tailscale**:
   ```bash
   # macOS
   brew install tailscale

   # Linux
   curl -fsSL https://tailscale.com/install.sh | sh
   ```

2. **Authenticate**: `tailscale up`

3. **Enable Funnel** in the admin console: https://login.tailscale.com/admin/acls
   - Add the `"funnel"` capability to your ACL policy

4. The server auto-configures Funnel on startup. Your public URL will be:
   ```
   https://<your-hostname>.ts.net/dc
   ```

> **Tip**: Run `tailscale serve status --json` to verify your config. The health check auto-repairs the Funnel config every 10 seconds.

---

### GitHub

#### Option A: GitHub App (recommended)

1. Go to **GitHub Settings** → **Developer settings** → **GitHub Apps** → **New GitHub App**
2. Set these fields:
   - **Homepage URL**: `https://<your-hostname>.ts.net/dc`
   - **Callback URL**: `https://<your-hostname>.ts.net/dc/oauth/callback/github`
   - **Webhook URL**: `https://<your-hostname>.ts.net/dc/webhook/github`
   - **Webhook secret**: generate a random string
3. Under **Permissions**:
   - Repository: Issues (Read & Write), Pull Requests (Read & Write), Contents (Read & Write)
4. Under **Subscribe to events**:
   - Issue comments, Pull request review comments
5. Copy credentials and set env vars:
   ```bash
   GITHUB_CLIENT_ID=Iv1.abc123...
   GITHUB_CLIENT_SECRET=abc123...
   GITHUB_WEBHOOK_SECRET=your-webhook-secret
   ```
6. Install the app on your repos
7. Complete OAuth: visit `https://<your-hostname>.ts.net/dc/setup/github`

#### Option B: Personal Access Token (simpler, no webhooks)

1. Go to **GitHub Settings** → **Developer settings** → **Personal access tokens** → **Tokens (classic)**
2. Create a token with scopes: `repo`, `write:discussion`
3. Set: `GITHUB_ACCESS_TOKEN=ghp_...`

> **Note**: With a PAT alone you won't get webhook-triggered instances. You'd use the `spawn_instance` MCP tool or `/api/spawn` endpoint instead.

| Environment Variable | Description |
|---------------------|-------------|
| `GITHUB_CLIENT_ID` | GitHub App client ID |
| `GITHUB_CLIENT_SECRET` | GitHub App client secret |
| `GITHUB_WEBHOOK_SECRET` | Webhook signature verification secret |
| `GITHUB_ACCESS_TOKEN` | Personal access token (alternative to OAuth) |

---

### Linear

1. Go to **Linear Settings** → **API** → **OAuth Applications** → **New Application**
2. Set the callback URL: `https://<your-hostname>.ts.net/dc/oauth/callback/linear`
3. Copy **Client ID** and **Client Secret**
4. Enable the **Webhooks** toggle on the OAuth app
5. Go to **Linear Settings** → **API** → **Webhooks** → **New Webhook**:
   - URL: `https://<your-hostname>.ts.net/dc/webhook/linear`
   - Copy the **Signing Secret**
   - Enable events: **Comments** (create), **Issues** (create, update)
6. Set env vars:
   ```bash
   LINEAR_CLIENT_ID=your-client-id
   LINEAR_CLIENT_SECRET=your-client-secret
   LINEAR_WEBHOOK_SECRET=your-signing-secret
   ```
7. Complete OAuth: visit `https://<your-hostname>.ts.net/dc/setup/linear`

After OAuth, only issues/comments from your authenticated Linear account trigger Claude.

**Alternative**: Use a Personal API Key (`LINEAR_ACCESS_TOKEN=lin_api_...`) from Linear Settings → Account → API.

| Environment Variable | Description |
|---------------------|-------------|
| `LINEAR_CLIENT_ID` | OAuth client ID |
| `LINEAR_CLIENT_SECRET` | OAuth client secret |
| `LINEAR_WEBHOOK_SECRET` | Webhook signing secret |
| `LINEAR_ACCESS_TOKEN` | Personal API key (alternative to OAuth) |

---

### Jira Cloud

1. **Create an API token** at https://id.atlassian.com/manage-profile/security/api-tokens
2. Set env vars:
   ```bash
   JIRA_DOMAIN=mycompany              # Your Jira subdomain (mycompany.atlassian.net)
   JIRA_USER_EMAIL=you@example.com    # Your Atlassian account email
   JIRA_API_TOKEN=ATATT3x...          # The API token you just created
   JIRA_WEBHOOK_SECRET=optional-secret # Optional shared secret
   ```
3. **Create a webhook** in Jira:
   - Go to **Jira Admin** → **System** → **Webhooks** → **Create webhook**
   - URL: `https://<your-hostname>.ts.net/dc/webhook/jira`
     - If using `JIRA_WEBHOOK_SECRET`, append it: `?secret=YOUR_SECRET`
   - Select events: `issue_created`, `issue_updated`, `comment_created`
4. Save the webhook

Claude can create sub-tasks, transition issue status, and add comments via the Jira REST API v2.

| Environment Variable | Description |
|---------------------|-------------|
| `JIRA_DOMAIN` | Jira subdomain (e.g. `mycompany` for mycompany.atlassian.net) |
| `JIRA_USER_EMAIL` | Your Atlassian email |
| `JIRA_API_TOKEN` | API token from Atlassian |
| `JIRA_WEBHOOK_SECRET` | Optional shared secret for webhook verification |

---

### GitLab

1. **Create a Personal Access Token** at GitLab → **Settings** → **Access Tokens**
   - Scopes: `api`, `read_repository`, `write_repository`
2. Set env vars:
   ```bash
   GITLAB_ACCESS_TOKEN=glpat-...
   GITLAB_WEBHOOK_SECRET=your-secret
   ```
3. **Add a webhook** to your project (or group):
   - Go to **Settings** → **Webhooks**
   - URL: `https://<your-hostname>.ts.net/dc/webhook/gitlab`
   - Secret token: same as `GITLAB_WEBHOOK_SECRET`
   - Trigger events: **Comments**, **Issues events**, **Merge request events**
4. Save

For self-hosted GitLab, also set `GITLAB_URL=https://your-gitlab-instance.com`.

| Environment Variable | Description |
|---------------------|-------------|
| `GITLAB_ACCESS_TOKEN` | Personal access token |
| `GITLAB_WEBHOOK_SECRET` | Webhook secret token |
| `GITLAB_URL` | GitLab instance URL (default: `https://gitlab.com`) |

---

### Notion

#### Option A: Internal Integration (simpler)

1. Go to https://www.notion.so/my-integrations → **New integration**
2. Give it a name, select your workspace
3. Copy the **Internal Integration Secret**
4. Set: `NOTION_ACCESS_TOKEN=ntn_...`
5. **Share pages/databases** with the integration (click "..." on a page → Connections → Add your integration)

#### Option B: OAuth (public app)

1. Create an OAuth integration at https://www.notion.so/my-integrations
2. Set callback URL: `https://<your-hostname>.ts.net/dc/oauth/callback/notion`
3. Set env vars:
   ```bash
   NOTION_CLIENT_ID=your-client-id
   NOTION_CLIENT_SECRET=your-secret
   ```
4. Complete OAuth: visit `https://<your-hostname>.ts.net/dc/setup/notion`

#### Webhook setup

Notion doesn't have native webhooks yet. To trigger Claude from Notion:
- Use Notion's automation rules with a webhook action (if available)
- Or use a third-party service like Zapier/Make to POST to `https://<your-hostname>.ts.net/dc/webhook/notion`
- Set `NOTION_WEBHOOK_SECRET` if you want signature ver