@lightupai/polaris 0.0.16 → 0.0.18

package/bin/polaris-mcp

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# Polaris MCP server — runs as a child process of Claude Code
+SCRIPT="$(realpath "$0" 2>/dev/null || readlink -f "$0" 2>/dev/null || echo "$0")"
+DIR="$(cd "$(dirname "$SCRIPT")/.." && pwd)"
+
+if command -v bun &>/dev/null; then
+  exec bun "$DIR/src/client/client.ts" "$@"
+elif command -v bunx &>/dev/null; then
+  exec bunx bun "$DIR/src/client/client.ts" "$@"
+else
+  exec npx --yes bun "$DIR/src/client/client.ts" "$@"
+fi

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,9 +1,10 @@
 {
   "name": "@lightupai/polaris",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "type": "module",
   "bin": {
-    "polaris": "bin/polaris"
+    "polaris": "bin/polaris",
+    "polaris-mcp": "bin/polaris-mcp"
   },
   "scripts": {
     "test": "bun test"

package/src/cli/cli.ts

@@ -110,12 +110,14 @@ async function install(participantId?: string) {
   await mkdir(CLAUDE_DIR, { recursive: true });
 
   // MCP server config
-  const clientPath = join(import.meta.dir, "..", "client", "client.ts");
+  // Use npx to run polaris-mcp from the published package. This avoids
+  // dangling file paths when installed via npx (temp directory gets cleaned up).
+  // The polaris-mcp bin entry resolves to src/client/client.ts within the package.
   const mcpConfig = {
     mcpServers: {
       polaris: {
         command: "npx",
-        args: ["bun", clientPath],
+        args: ["-y", "-p", "@lightupai/polaris", "polaris-mcp"],
         env: {
           POLARIS_DAEMON_URL: "http://127.0.0.1:4322",
         },