io.github.sns45/dear-claude

Official

by sns45 · TypeScript

Spawn Claude Code instances from 6 platforms when 'Dear Claude' is mentioned.

Spawn Claude Code instances from 6 platforms when triggered.

<img src="assets/marketing/hero-poster.png" alt="Dear Claude - Just say Dear Claude" width="500"> <h1 align="center">Dear Claude</h1> MCP server that triggers local Claude Code instances from external platforms. Say "Dear Claude" in Linear, GitHub, Jira, GitLab, Notion, or Obsidian — and a Claude Code instance spins up to handle it. Your notes become architecture. Your tasks become pull requests.

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:

Write a spec in Obsidian → "Dear Claude, create these tasks in Linear"
Discuss on Linear → "Dear Claude, code this on GitHub"
Review on GitHub → "Dear Claude, resolve the merge conflicts"
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 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:

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

Install Tailscale:

bash

# macOS
brew install tailscale

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

Authenticate: tailscale up
Enable Funnel in the admin console: https://login.tailscale.com/admin/acls
- Add the "funnel" capability to your ACL policy
The server auto-configures Funnel on startup. Your public URL will be:
code
```
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)

Go to GitHub Settings → Developer settings → GitHub Apps → New GitHub App
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
Under Permissions:
- Repository: Issues (Read & Write), Pull Requests (Read & Write), Contents (Read & Write)
Under Subscribe to events:
- Issue comments, Pull request review comments

Copy credentials and set env vars:

bash

GITHUB_CLIENT_ID=Iv1.abc123...
GITHUB_CLIENT_SECRET=abc123...
GITHUB_WEBHOOK_SECRET=your-webhook-secret

Install the app on your repos
Complete OAuth: visit https://<your-hostname>.ts.net/dc/setup/github

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

Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
Create a token with scopes: repo, write:discussion
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

Go to Linear Settings → API → OAuth Applications → New Application
Set the callback URL: https://<your-hostname>.ts.net/dc/oauth/callback/linear
Copy Client ID and Client Secret
Enable the Webhooks toggle on the OAuth app
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)

Set env vars:

bash

LINEAR_CLIENT_ID=your-client-id
LINEAR_CLIENT_SECRET=your-client-secret
LINEAR_WEBHOOK_SECRET=your-signing-secret

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

Create an API token at https://id.atlassian.com/manage-profile/security/api-tokens

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

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

Create a Personal Access Token at GitLab → Settings → Access Tokens
- Scopes: api, read_repository, write_repository

Set env vars:

bash

GITLAB_ACCESS_TOKEN=glpat-...
GITLAB_WEBHOOK_SECRET=your-secret

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
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)

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

Option B: OAuth (public app)

Create an OAuth integration at https://www.notion.so/my-integrations
Set callback URL: https://<your-hostname>.ts.net/dc/oauth/callback/notion

Set env vars:

bash

NOTION_CLIENT_ID=your-client-id
NOTION_CLIENT_SECRET=your-secret

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.

Set env var with the absolute path to your vault:

bash

OBSIDIAN_VAULT_PATH=/Users/yourname/Documents/MyVault

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:

code

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:

SQL injection in user.ts:45

Missing input validation in api.ts:102

Created PR #15 with fixes.

Instance Orchestration

Claude instances can spawn other instances for parallel work:

code

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

Claude will:

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

All Environment Variables

bash

# 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
JIRA_USER_EMAIL=you@example.com
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

bash

# 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

json

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

code

                  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

code

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

bash

# 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

Install

Configuration

Environment variables

DEAR_CLAUDE_PORT

HTTP server port for webhooks (default: 3334)

TAILSCALE_HOSTNAME

Override Tailscale hostname for webhook URLs (auto-detected if not set)

GITHUB_CLIENT_ID

GitHub OAuth App or GitHub App client ID

GITHUB_CLIENT_SECRETsecret

GitHub OAuth App or GitHub App client secret

GITHUB_WEBHOOK_SECRETsecret

GitHub webhook signature secret

GITHUB_ACCESS_TOKENsecret

GitHub personal access token (alternative to OAuth)

GITHUB_APP_ID

GitHub App ID (for installation-based auth)

GITHUB_APP_PRIVATE_KEY_PATH

Path to GitHub App private key PEM file

LINEAR_CLIENT_ID

Linear OAuth application client ID

LINEAR_CLIENT_SECRETsecret

Linear OAuth application client secret

LINEAR_WEBHOOK_SECRETsecret

Linear webhook signing secret

LINEAR_ACCESS_TOKENsecret

Linear personal API key (alternative to OAuth)

JIRA_DOMAIN

Jira Cloud domain (e.g. 'mycompany' for mycompany.atlassian.net)

JIRA_USER_EMAIL

Jira account email for API authentication

JIRA_API_TOKENsecret

Jira API token from id.atlassian.com

JIRA_WEBHOOK_SECRETsecret

Shared secret for Jira webhook URL validation

GITLAB_ACCESS_TOKENsecret

GitLab personal or project access token

GITLAB_WEBHOOK_SECRETsecret

GitLab webhook secret token

NOTION_CLIENT_ID

Notion OAuth integration client ID

NOTION_CLIENT_SECRETsecret

Notion OAuth integration client secret

NOTION_ACCESS_TOKENsecret

Notion internal integration token (alternative to OAuth)

NOTION_WEBHOOK_SECRETsecret

Notion webhook verification secret

OBSIDIAN_VAULT_PATH

Absolute path to Obsidian vault directory for file watching

GIPHY_API_KEYsecret

Giphy API key for embedding GIF reactions in responses

claude_desktop_config.json

{
  "mcpServers": {
    "dear-claude": {
      "command": "npx",
      "args": [
        "-y",
        "dear-claude@1.1.0"
      ],
      "env": {
        "DEAR_CLAUDE_PORT": "<YOUR_DEAR_CLAUDE_PORT>",
        "TAILSCALE_HOSTNAME": "<YOUR_TAILSCALE_HOSTNAME>",
        "GITHUB_CLIENT_ID": "<YOUR_GITHUB_CLIENT_ID>",
        "GITHUB_CLIENT_SECRET": "<YOUR_GITHUB_CLIENT_SECRET>",
        "GITHUB_WEBHOOK_SECRET": "<YOUR_GITHUB_WEBHOOK_SECRET>",
        "GITHUB_ACCESS_TOKEN": "<YOUR_GITHUB_ACCESS_TOKEN>",
        "GITHUB_APP_ID": "<YOUR_GITHUB_APP_ID>",
        "GITHUB_APP_PRIVATE_KEY_PATH": "<YOUR_GITHUB_APP_PRIVATE_KEY_PATH>",
        "LINEAR_CLIENT_ID": "<YOUR_LINEAR_CLIENT_ID>",
        "LINEAR_CLIENT_SECRET": "<YOUR_LINEAR_CLIENT_SECRET>",
        "LINEAR_WEBHOOK_SECRET": "<YOUR_LINEAR_WEBHOOK_SECRET>",
        "LINEAR_ACCESS_TOKEN": "<YOUR_LINEAR_ACCESS_TOKEN>",
        "JIRA_DOMAIN": "<YOUR_JIRA_DOMAIN>",
        "JIRA_USER_EMAIL": "<YOUR_JIRA_USER_EMAIL>",
        "JIRA_API_TOKEN": "<YOUR_JIRA_API_TOKEN>",
        "JIRA_WEBHOOK_SECRET": "<YOUR_JIRA_WEBHOOK_SECRET>",
        "GITLAB_ACCESS_TOKEN": "<YOUR_GITLAB_ACCESS_TOKEN>",
        "GITLAB_WEBHOOK_SECRET": "<YOUR_GITLAB_WEBHOOK_SECRET>",
        "NOTION_CLIENT_ID": "<YOUR_NOTION_CLIENT_ID>",
        "NOTION_CLIENT_SECRET": "<YOUR_NOTION_CLIENT_SECRET>",
        "NOTION_ACCESS_TOKEN": "<YOUR_NOTION_ACCESS_TOKEN>",
        "NOTION_WEBHOOK_SECRET": "<YOUR_NOTION_WEBHOOK_SECRET>",
        "OBSIDIAN_VAULT_PATH": "<YOUR_OBSIDIAN_VAULT_PATH>",
        "GIPHY_API_KEY": "<YOUR_GIPHY_API_KEY>"
      }
    }
  }
}