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

claude mcp add dear-claude -- bunx dear-claude start --mcp

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

Prerequisites

• Claude Code CLI installed (claude command available)
• Bun runtime (for bunx)
• Tailscale with Funnel enabled (for webhooks from external platforms)

Manual setup (alternative)

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

{
  "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:

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 for stable public HTTPS URLs to receive webhooks. Setup is mostly automatic.

1. Install Tailscale:

   # 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:

   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:

   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:

   JIRA_DOMAIN=mycompany              # Your Jira subdomain (mycompany.atlassian.net)
   [email protected]    # 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:

   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:

   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 verification

| Environment Variable | Description | |---------------------|-------------| | NOTION_ACCESS_TOKEN | Internal integration token | | NOTION_CLIENT_ID | OAuth client ID | | NOTION_CLIENT_SECRET | OAuth client secret | | NOTION_WEBHOOK_SECRET | Webhook verification secret |

Obsidian

Obsidian integration works via filesystem watching — no webhooks needed. Claude watches your vault for files containing "Dear Claude" and responds by appending to the same file.

1. Set env var with the absolute path to your vault:

   OBSIDIAN_VAULT_PATH=/Users/yourname/Documents/MyVault

2. That's it! Write "Dear Claude, ..." in any .md file and save.

Claude's response appears as a callout block appended to the same note. The frontmatter gets a claude-status field (processing → done / error).

How it works:

• Watches for .md file changes in the vault
• Ignores files in .obsidian/, .trash/, and dotfile directories
• 2-second debounce to avoid triggering on every keystroke
• Supports wikilink references ([[other-note]]) — Claude resolves and reads them
• Supports embedded images — Claude can see and analyze them

| Environment Variable | Description | |---------------------|-------------| | OBSIDIAN_VAULT_PATH | Absolute path to your Obsidian vault | | OBSIDIAN_WATCH_DEBOUNCE_MS | Debounce delay in ms (default: 2000) |

Usage

Trigger Format

Write "Dear Claude" (case-insensitive, with a space) anywhere in:

• GitHub issue/PR comments
• Linear issue descriptions or comments
• Jira issue descriptions or comments
• GitLab issue/MR descriptions or comments
• Notion page comments
• Obsidian .md files

Example

GitHub PR Comment:

Dear Claude, please review this code for bugs and security issues.

Claude responds on GitHub:

Claude Instance Started (Instance: abc12345) Processing your request...

Task Completed Found 2 issues:

1. SQL injection in user.ts:45
2. Missing input validation in api.ts:102

Created PR #15 with fixes.

Instance Orchestration

Claude instances can spawn other instances for parallel work:

Dear Claude, code tasks 1-5 in parallel. Each task should be a separate branch.

Claude will:

1. Parse the tasks
2. Spawn 5 child instances via the /api/spawn endpoint
3. Each child works in its own git worktree (same repo, different branch)
4. Each child creates a PR when done
5. Parent polls child statuses

All Environment Variables

# Server
DEAR_CLAUDE_PORT=3334
TAILSCALE_HOSTNAME=              # Optional: auto-detected

# GitHub
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
GITHUB_WEBHOOK_SECRET=
GITHUB_ACCESS_TOKEN=

# Linear
LINEAR_CLIENT_ID=
LINEAR_CLIENT_SECRET=
LINEAR_WEBHOOK_SECRET=
LINEAR_ACCESS_TOKEN=

# Jira Cloud
JIRA_DOMAIN=mycompany
[email protected]
JIRA_API_TOKEN=
JIRA_WEBHOOK_SECRET=

# GitLab
GITLAB_ACCESS_TOKEN=
GITLAB_WEBHOOK_SECRET=
GITLAB_URL=                      # Default: https://gitlab.com

# Notion
NOTION_CLIENT_ID=
NOTION_CLIENT_SECRET=
NOTION_WEBHOOK_SECRET=
NOTION_ACCESS_TOKEN=

# Obsidian
OBSIDIAN_VAULT_PATH=
OBSIDIAN_WATCH_DEBOUNCE_MS=2000

# Optional
GIPHY_API_KEY=                   # For fun GIF reactions in responses

CLI Commands

# Start the server (standalone mode)
bun run src/index.ts start

# Start as MCP server (stdio, for Claude Code)
bun run src/index.ts start --mcp

# Check server and platform status
bun run src/index.ts status

# List instances
bun run src/index.ts instances

# Setup instructions for a platform
bun run src/index.ts setup <platform>

MCP Tools

When running as an MCP server inside Claude Code, these tools are available:

| Tool | Description | |------|-------------| | list_platforms | List configured platforms and their status | | list_instances | List all Claude instances (filter by status) | | get_instance_status | Get detailed status of a specific instance | | get_instance_messages | Get conversation history for an instance | | kill_instance | Terminate a running instance | | get_running_instances | List currently running instance IDs | | spawn_instance | Spawn a new Claude instance for a task | | get_project_instances | List all instances in a project group |

HTTP API

The server also exposes REST endpoints on localhost:3334:

| Endpoint | Method | Description | |----------|--------|-------------| | /health | GET | Health check + platform status | | /webhook/:platform | POST | Webhook receiver | | /api/instances | GET | List instances (?project_id= filter) | | /api/instances/:id | GET | Get instance details + children | | /api/instances/:id/kill | POST | Kill a running instance | | /api/spawn | POST | Spawn a new instance programmatically | | /api/platforms | GET | List configured platforms | | /setup/:platform | GET | Start OAuth flow | | /oauth/callback/:platform | GET | OAuth callback |

POST /api/spawn

{
  "prompt": "Implement the login page",
  "repo_url": "https://github.com/owner/repo",
  "branch": "feature/login",
  "base_branch": "main",
  "parent_instance_id": "optional-parent-id",
  "project_id": "optional-project-id"
}

Architecture

                  Webhooks / File Watcher
  ┌────────┐ ┌────────┐ ┌──────┐ ┌────────┐ ┌──────────┐ ┌────────┐
  │ GitHub │ │ Linear │ │ Jira │ │ GitLab │ │ Obsidian │ │ Notion │
  └───┬────┘ └───┬────┘ └──┬───┘ └───┬────┘ └────┬─────┘ └───┬────┘
      │          │         │         │            │            │
      └──────────┴────┬────┴─────────┴────────────┴────────────┘
                      │
                      ▼
           ┌─────────────────────┐
           │  Tailscale Funnel   │
           │ (Public HTTPS URL)  │
           └─────────┬───────────┘
                     │
                     ▼
           ┌─────────────────────┐
           │   dear-claude       │
           │   MCP Server        │
           │                     │
           │ • Trigger detection │
           │ • Instance manager  │
           │ • Platform adapters │
           │ • Spawn API         │
           │ • SQLite DB         │
           └─────────┬───────────┘
                     │
                     ▼
           ┌─────────────────────┐
           │  Claude Code        │
           │  Instances          │
           │ (Agent SDK)         │
           │                     │
           │ • Git worktrees     │
           │ • Cross-platform    │
           │   API access        │
           │ • Child spawning    │
           └─────────────────────┘

Instance Lifecycle

PENDING → RUNNING → IDLE → (follow-up) → RUNNING → IDLE → ... → EXPIRED (7 days)
                  ↘ COMPLETED
                  ↘ FAILED

• PENDING: Trigger detected, instance queued
• RUNNING: Claude Code actively processing
• IDLE: Waiting for follow-up "Dear Claude" mentions
• COMPLETED: Task finished successfully
• FAILED: Error occurred
• EXPIRED: 7-day TTL exceeded, instance cleaned up

Development

# Install dependencies
bun install

# Run dev mode
bun run dev

# Type check
bunx tsc --noEmit

# Build
bun run build

# Run tests
bun test

Troubleshooting

Tailscale

• "Tailscale not running": Open the Tailscale app (macOS) or sudo systemctl start tailscaled && tailscale up (Linux)
• "Funnel not enabled": Visit https://login.tailscale.com/admin/acls and add Funnel capability
• Funnel disappears: Another tailscale serve/tailscale funnel command may have overwritten it. The health check auto-repairs within 10 seconds. Verify with tailscale serve status --json.

Webhooks

• Not triggering: Check bun run src/index.ts status to verify the server is up. Test with curl https://<your-hostname>.ts.net/dc/health.
• "Invalid signature": Verify the webhook secret matches in both the platform config and your env vars.
• GitHub: The app subscribes to issue_comment events. To trigger on a new PR, post a comment — PR descriptions alone won't trigger.

OAuth

• Token expired: Re-visit https://<your-hostname>.ts.net/dc/setup/<platform> to re-authenticate.
• 401 errors: The stored OAuth token may have been revoked. Delete the stale token from data/dear-claude.db and re-authenticate.

Instances

• Stuck in PENDING: Check that Claude Code CLI (claude) is installed and accessible in your PATH.
• Working directory issues: Instances create workspaces under data/workspaces/. Ensure write permissions.

License

MIT