@lightupai/polaris 0.0.15 → 0.0.17

package/docs/design-claude-desktop.md

@@ -0,0 +1,112 @@
+# Design: Claude Desktop Support
+
+## Current State
+
+Polaris is built for Claude Code (CLI and desktop app), which provides:
+- Hook system for automatic event capture
+- Skills/slash commands for `/polaris join`
+- Status line for connection indicator
+- MCP server support for tools
+
+Claude Desktop supports MCP servers but lacks hooks, skills, and status line.
+
+## What Works Without Changes
+
+- **MCP tools**: polaris_connect, polaris_disconnect, polaris_status, polaris_reply, polaris_context, polaris_rename
+- **Advisor injection**: messages from Slack reach the agent via the MCP channel capability
+- **Agent collaboration**: the agent can join projects, read sibling sessions, and send replies
+
+## What's Missing
+
+### 1. Automatic Event Capture (critical gap)
+
+Claude Code captures every interaction via hooks:
+- `UserPromptSubmit` → human typed a prompt
+- `Stop` → agent responded
+- `PreToolUse` / `PostToolUse` → agent used a tool
+
+Claude Desktop has no hook system. Without it, the floor is blind to what's happening in a Claude Desktop session. Slack shows nothing. The dashboard shows no activity.
+
+#### Options for event capture
+
+**A. Agent self-reporting via MCP tool**
+
+Add a `polaris_log` tool. Instruct the agent (via MCP server instructions) to call it after every response:
+
+```
+After each response, call polaris_log with a brief summary of what you did.
+```
+
+Pros: Works today, no platform changes needed.
+Cons: Lossy (agent may forget), adds latency, clutters the tool call log, relies on instruction following.
+
+**B. MCP sampling / conversation observation**
+
+The MCP spec has a `sampling` capability where the server can request to see conversation messages. If Claude Desktop supports this, the MCP server could observe the conversation passively.
+
+Pros: Automatic, no agent cooperation needed.
+Cons: May not be supported, privacy implications, spec is experimental.
+
+**C. Claude Desktop adds hook support**
+
+Anthropic adds a hook system to Claude Desktop, similar to Claude Code.
+
+Pros: Full parity, same code works everywhere.
+Cons: Depends on Anthropic's roadmap, not in our control.
+
+**D. Accept the gap**
+
+Claude Desktop users get tools (join, reply, context) but not automatic capture. Their sessions appear on the floor only when they explicitly send a reply or when advisors inject messages.
+
+Pros: No work needed, honest about limitations.
+Cons: Half the value prop is missing — teammates can't see what's happening.
+
+#### Recommendation
+
+Start with **D** (accept the gap) + **A** (agent self-reporting) as an opt-in enhancement. Document the limitation clearly. Push for **C** as a feature request to Anthropic.
+
+### 2. MCP Config Path
+
+| Platform | Claude Code | Claude Desktop |
+|----------|-------------|----------------|
+| macOS | `~/.claude/.mcp.json` | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Windows | `%USERPROFILE%\.claude\.mcp.json` | `%APPDATA%\Claude\claude_desktop_config.json` |
+| Linux | `~/.claude/.mcp.json` | `~/.config/Claude/claude_desktop_config.json` |
+
+The `polaris install` command needs to detect which apps are installed and write to both config files.
+
+### 3. Skills / Slash Commands
+
+Claude Desktop doesn't have skills. The user can't type `/polaris join`. Instead:
+- The MCP server's `instructions` field tells the agent about available tools
+- The user says "connect to polaris project X" and the agent calls `polaris_connect`
+- Less discoverable but functional
+
+### 4. Status Line
+
+No equivalent in Claude Desktop. The user can ask "are we connected to polaris?" and the agent calls `polaris_status`. Not ideal but workable.
+
+## Implementation Plan (when ready)
+
+### Phase 1: Basic support
+- `polaris install` writes MCP config to both Claude Code and Claude Desktop paths
+- Document that event capture is limited
+- MCP server instructions are detailed enough for the agent to self-serve
+
+### Phase 2: Agent self-reporting
+- Add `polaris_log` tool to MCP server
+- MCP server instructions tell the agent to log after each response
+- Events appear on the floor with `agent:claude-desktop` identity
+- Accept that human prompts won't be captured (only agent responses)
+
+### Phase 3: Full parity (depends on platform)
+- If Claude Desktop adds hooks → same capture as Claude Code
+- If MCP sampling lands → passive observation of conversation
+- Either way, the architecture is ready — the daemon handles everything
+
+## Open Questions
+
+1. Does Claude Desktop respect MCP server `instructions` reliably enough for self-reporting?
+2. Is `sampling` capability available or planned for Claude Desktop?
+3. Should `polaris install` auto-detect installed apps or require `--desktop` flag?
+4. How do we handle the case where both Claude Code and Claude Desktop are installed on the same machine? Same daemon, same MCP server, different config files — should work.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightupai/polaris",
-  "version": "0.0.15",
+  "version": "0.0.17",
   "type": "module",
   "bin": {
     "polaris": "bin/polaris"

package/src/cli/cli.ts

@@ -178,7 +178,7 @@ async function install(participantId?: string) {
 name: polaris
 description: Connect to a Polaris multiplayer collaboration session
 allowed-tools: polaris_connect polaris_disconnect polaris_status polaris_reply polaris_context polaris_rename
-argument-hint: [join <project> <session> | rename <new-name> | disconnect | (no args for status)]
+argument-hint: [join <project> | rename <new-name> | disconnect | (no args for status)]
 ---
 
 ## Polaris — Multiplayer Collaboration
@@ -189,9 +189,10 @@ Manage your connection to a Polaris collaboration session.
 
 Based on the arguments provided, do ONE of the following:
 
-**\`/polaris join <project> <session>\`** — Connect to a session:
-1. Call \`polaris_connect\` with the given project, session, and user identity ${identity}
-2. Report the connection status
+**\`/polaris join <project>\`** — Connect to a session:
+1. Call \`polaris_connect\` with the given project and user identity ${identity}
+2. A session name is auto-generated
+3. Report the connection status including the session name
 
 **\`/polaris rename <new-name>\`** — Rename the current project:
 1. Call \`polaris_rename\` with the new name
@@ -309,7 +310,7 @@ async function login(appUrl: string, profileName?: string) {
 name: polaris
 description: Connect to a Polaris multiplayer collaboration session
 allowed-tools: polaris_connect polaris_disconnect polaris_status polaris_reply polaris_context polaris_rename
-argument-hint: [join <project> <session> | rename <new-name> | disconnect | (no args for status)]
+argument-hint: [join <project> | rename <new-name> | disconnect | (no args for status)]
 ---
 
 ## Polaris — Multiplayer Collaboration
@@ -320,9 +321,10 @@ Manage your connection to a Polaris collaboration session.
 
 Based on the arguments provided, do ONE of the following:
 
-**\`/polaris join <project> <session>\`** — Connect to a session:
-1. Call \`polaris_connect\` with the given project, session, and user identity ${identity}
-2. Report the connection status
+**\`/polaris join <project>\`** — Connect to a session:
+1. Call \`polaris_connect\` with the given project and user identity ${identity}
+2. A session name is auto-generated
+3. Report the connection status including the session name
 
 **\`/polaris rename <new-name>\`** — Rename the current project:
 1. Call \`polaris_rename\` with the new name
@@ -517,7 +519,16 @@ switch (command) {
     console.log("Polaris — authenticating\n");
     await login(appUrl, profileName);
     console.log("\n✓ Login complete!");
-    console.log("\nNext: start the daemon with `polaris daemon`, then `/polaris join <project> <session>` in your AI agent.");
+    // Auto-start daemon in background
+    const daemonPath = join(import.meta.dir, "..", "daemon", "daemon.ts");
+    Bun.spawn(["bun", "run", daemonPath], {
+      stdout: "ignore",
+      stderr: "ignore",
+      env: { ...process.env },
+    }).unref?.();
+    console.log("  ✓ Daemon started in background");
+
+    console.log("\nNext: restart Claude Code, then run `/polaris join <project>` in your AI agent.");
     break;
   }
 
@@ -554,7 +565,16 @@ switch (command) {
     console.log("[2/2] Authenticating...\n");
     await login(DEFAULT_APP_URL);
     console.log("\n✓ Polaris is set up on this machine!");
-    console.log("\nNext: start the daemon with `polaris daemon`, then `/polaris join <project> <session>` in your AI agent.");
+    // Auto-start daemon in background
+    const daemonPath = join(import.meta.dir, "..", "daemon", "daemon.ts");
+    Bun.spawn(["bun", "run", daemonPath], {
+      stdout: "ignore",
+      stderr: "ignore",
+      env: { ...process.env },
+    }).unref?.();
+    console.log("  ✓ Daemon started in background");
+
+    console.log("\nNext: restart Claude Code, then run `/polaris join <project>` in your AI agent.");
     break;
 
   default: