dear-claude: Instructions file for Claude Code

dear-claude

MCP server that triggers local Claude Code instances from external platforms (Linear, GitHub, Jira, GitLab, Notion, Obsidian) when "Dear Claude" is mentioned.

Architecture Notes

Data directory (do NOT use process.cwd())

All persistent state resolves through getDataDir() in src/utils/paths.ts:

1. DEAR_CLAUDE_DATA_DIR (explicit override)
2. $XDG_DATA_HOME/dear-claude
3. ~/.local/share/dear-claude (default)

This holds dear-claude.db, workspaces/, contexts/, and api-token.

Never resolve state against process.cwd(). A stdio MCP server inherits the working directory of whatever project the client opened, so a cwd relative path creates a stray data/ folder in every project. That was a real bug, fixed in v1.1.3.

Two transports

The same tool surface is served two ways:

• stdio: dear-claude start --mcp. Spawned per Claude Code window.
• Stateless Streamable HTTP: POST /mcp on the Hono server, mounted by mountMcpEndpoint() in src/mcp.ts.

The HTTP endpoint runs stateless (sessionIdGenerator: undefined), building a fresh Server and transport per request, so nothing is shared across requests. Prefer it when running several Claude Code windows: one shared process instead of one per window, which avoids contention on the webhook port.

"dear-claude": {
  "type": "http",
  "url": "http://127.0.0.1:3334/mcp",
  "headers": { "Authorization": "Bearer <dear-claude token>" }
}

stdout is the MCP protocol channel

In --mcp mode, console.log is redirected to stderr at the top of the start action in src/cli.ts. Anything written to stdout that is not JSON-RPC corrupts the framing and the client drops the connection with CONNECTION_CLOSED. Use console.error for any new logging on a code path that can run under stdio.

Auth and binding

/api/* and /mcp require a bearer token (src/utils/auth.ts). These endpoints can spawn Claude with bypassPermissions on this machine, so they must never be open.