agentrace 0.0.1 → 0.0.3

package/README.md

@@ -0,0 +1,132 @@
+# AgenTrace CLI
+
+A CLI tool to send Claude Code sessions to the AgenTrace server.
+
+## Overview
+
+AgenTrace is a self-hosted service that enables teams to review Claude Code conversations. Since Claude Code logs contain source code and environment information, AgenTrace is designed to run on your local machine or internal network rather than on the public internet.
+
+This CLI uses Claude Code's hooks feature to automatically send session data to your AgenTrace server.
+
+## Setup
+
+### 1. Start the Server
+
+```bash
+# Using Docker (recommended)
+docker run -d --name agentrace -p 9080:9080 -v $(pwd)/data:/data satetsu888/agentrace:latest
+```
+
+Docker Hub: <https://hub.docker.com/r/satetsu888/agentrace>
+
+### 2. Initialize the CLI
+
+```bash
+npx agentrace init --url http://localhost:9080
+```
+
+A browser window will open displaying the registration/login page. After registration, hooks are automatically configured.
+
+That's it! When you use Claude Code, sessions will be automatically sent to AgenTrace.
+
+## Commands
+
+| Command                      | Description                            |
+| ---------------------------- | -------------------------------------- |
+| `agentrace init --url <url>` | Initial setup + hooks installation     |
+| `agentrace login`            | Open the web dashboard                 |
+| `agentrace send`             | Send transcript diff (used by hooks)   |
+| `agentrace on`               | Enable hooks                           |
+| `agentrace off`              | Disable hooks                          |
+| `agentrace uninstall`        | Remove hooks and configuration         |
+
+## Command Details
+
+### init
+
+Sets up the server connection and installs Claude Code hooks.
+
+```bash
+npx agentrace init --url http://localhost:9080
+```
+
+**Process flow:**
+
+1. Opens the server's registration/login page in browser
+2. After registration, API key is automatically retrieved
+3. Claude Code hooks are configured
+
+### login
+
+Issues a login URL for the web dashboard and opens it in browser.
+
+```bash
+npx agentrace login
+```
+
+### on / off
+
+Toggle hooks enabled/disabled. Configuration is preserved.
+
+```bash
+# Temporarily stop sending
+npx agentrace off
+
+# Resume sending
+npx agentrace on
+```
+
+### uninstall
+
+Completely removes hooks and configuration files.
+
+```bash
+npx agentrace uninstall
+```
+
+### send
+
+This command is automatically called by Claude Code's Stop hook. You normally don't need to run it manually.
+
+## Configuration Files
+
+Configuration is stored in the following locations:
+
+| File                 | Location                          |
+| -------------------- | --------------------------------- |
+| AgenTrace config     | `~/.config/agentrace/config.json` |
+| Cursor data          | `~/.config/agentrace/cursors/`    |
+| Claude Code hooks    | `~/.claude/settings.json`         |
+
+## How It Works
+
+```text
+┌─────────────────┐
+│   Claude Code   │
+│  (Stop hook)    │
+└────────┬────────┘
+         │ npx agentrace send
+         ↓
+┌─────────────────┐
+│  AgenTrace CLI  │
+│  Extract & Send │
+└────────┬────────┘
+         │ POST /api/ingest
+         ↓
+┌─────────────────┐
+│ AgenTrace Server│
+│   Save to DB    │
+└─────────────────┘
+```
+
+- Only the transcript diff is sent to the server when a Claude Code conversation ends
+- Errors do not block Claude Code's operation by design
+
+## Requirements
+
+- Node.js 18 or later
+- Claude Code installed
+
+## License
+
+MIT

package/dist/commands/init.js

@@ -1,7 +1,7 @@
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { saveConfig, getConfigPath } from "../config/manager.js";
-import { installHooks } from "../hooks/installer.js";
+import { installHooks, installMcpServer, installPreToolUseHook } from "../hooks/installer.js";
 import { startCallbackServer, getRandomPort, generateToken, } from "../utils/callback-server.js";
 import { openBrowser, buildSetupUrl } from "../utils/browser.js";
 const __filename = fileURLToPath(import.meta.url);
@@ -80,6 +80,30 @@ export async function initCommand(options = {}) {
         else {
             console.error(`✗ ${hookResult.message}`);
         }
+        // Install MCP server
+        let mcpCommand;
+        let mcpArgs;
+        if (options.dev) {
+            const cliRoot = path.resolve(__dirname, "../..");
+            const indexPath = path.join(cliRoot, "src/index.ts");
+            mcpCommand = "npx";
+            mcpArgs = ["tsx", indexPath, "mcp-server"];
+        }
+        const mcpResult = installMcpServer({ command: mcpCommand, args: mcpArgs });
+        if (mcpResult.success) {
+            console.log(`✓ ${mcpResult.message}`);
+        }
+        else {
+            console.error(`✗ ${mcpResult.message}`);
+        }
+        // Install PreToolUse hook for session_id injection
+        const preToolUseResult = installPreToolUseHook();
+        if (preToolUseResult.success) {
+            console.log(`✓ ${preToolUseResult.message}`);
+        }
+        else {
+            console.error(`✗ ${preToolUseResult.message}`);
+        }
         console.log("\n✓ Setup complete!");
     }
     catch (error) {

package/dist/commands/mcp-server.d.ts

@@ -0,0 +1 @@
+export declare function mcpServerCommand(): Promise<void>;

package/dist/commands/mcp-server.js

@@ -0,0 +1,284 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { patchMake, patchToText } from "diff-match-patch-es";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { PlanDocumentClient } from "../mcp/plan-document-client.js";
+// Read session_id from file written by PreToolUse hook
+function getSessionIdFromFile() {
+    try {
+        const sessionFile = path.join(os.homedir(), ".agentrace", "current-session.json");
+        if (fs.existsSync(sessionFile)) {
+            const content = fs.readFileSync(sessionFile, "utf-8");
+            const data = JSON.parse(content);
+            return data.session_id;
+        }
+    }
+    catch {
+        // Ignore errors, return undefined
+    }
+    return undefined;
+}
+// Tool schemas
+const ListPlansSchema = z.object({
+    git_remote_url: z.string().describe("Git remote URL to filter plans"),
+});
+const ReadPlanSchema = z.object({
+    id: z.string().describe("Plan document ID"),
+});
+const CreatePlanSchema = z.object({
+    description: z.string().describe("Short description of the plan"),
+    body: z.string().describe("Plan content in Markdown format"),
+});
+const UpdatePlanSchema = z.object({
+    id: z.string().describe("Plan document ID"),
+    body: z.string().describe("Updated plan content in Markdown format"),
+});
+const SetPlanStatusSchema = z.object({
+    id: z.string().describe("Plan document ID"),
+    status: z.enum(["scratch", "draft", "planning", "pending", "implementation", "complete"]).describe("New status for the plan"),
+});
+// Tool descriptions with usage guidance
+const TOOL_DESCRIPTIONS = {
+    list_plans: `List plan documents for a repository.
+
+WHEN TO USE:
+- When you need to check existing plans for the current repository
+- When the user asks about available plans or implementation documents
+- Before creating a new plan to avoid duplicates`,
+    read_plan: `Read a plan document by ID.
+
+WHEN TO USE:
+- When the user asks you to check or review a specific plan by ID
+- When you need to understand an existing plan before making changes
+- When the user references a plan ID in their request`,
+    create_plan: `Create a new plan document to record implementation or design plans.
+
+WHEN TO USE:
+- ALWAYS use this when you create a design or implementation plan
+- When entering plan mode and documenting your approach
+- When the user asks you to save or persist a plan
+- When planning significant features, refactoring, or architectural changes
+
+The plan will be saved to Agentrace server and can be reviewed by the team.
+The project is automatically determined from the session's git repository.`,
+    update_plan: `Update an existing plan document.
+
+WHEN TO USE:
+- When the user asks you to modify a specific plan by ID
+- When implementation details change and the plan needs updating
+- When you need to add progress notes or completion status to a plan
+
+Changes are tracked with diff patches for history.`,
+    set_plan_status: `Set the status of a plan document.
+
+WHEN TO USE:
+- When transitioning a plan from planning to implementation phase
+- When marking a plan as complete after finishing the work
+- When the user explicitly asks to change the status of a plan
+
+Available statuses:
+- scratch: Initial rough notes, starting point for discussion with AI
+- draft: Plan not yet fully considered (optional intermediate status)
+- planning: Plan is being designed/refined through discussion
+- pending: Waiting for approval or blocked
+- implementation: Active development is in progress
+- complete: The work described in the plan is finished
+
+BASIC FLOW: scratch → planning → implementation → complete
+(draft and pending are optional auxiliary statuses)
+
+STATUS TRANSITION GUIDELINES:
+- scratch → planning: When you read a scratch plan (usually written by human), review its content and rewrite it into a more concrete plan, then change status to planning
+- planning → implementation: When the plan is finalized after discussion, change status to implementation before starting work
+- implementation → complete: When all work described in the plan is finished, change status to complete
+
+CAUTION:
+- When a plan is in "implementation" status, someone else might already be working on it. Check with the team before starting work on such plans.`,
+};
+export async function mcpServerCommand() {
+    const server = new McpServer({
+        name: "agentrace",
+        version: "1.0.0",
+        description: `Agentrace Plan Document Management Server.
+
+This server provides tools to manage implementation and design plans.
+Plans are stored on the Agentrace server and can be reviewed by the team.
+
+IMPORTANT GUIDELINES:
+- When you create a design or implementation plan, ALWAYS save it using create_plan
+- When the user asks you to check or modify a plan by ID, use the appropriate tool
+- Plans help track what you're working on and enable team collaboration`,
+    });
+    let client = null;
+    function getClient() {
+        if (!client) {
+            client = new PlanDocumentClient();
+        }
+        return client;
+    }
+    // list_plans tool
+    server.tool("list_plans", TOOL_DESCRIPTIONS.list_plans, ListPlansSchema.shape, async (args) => {
+        try {
+            const plans = await getClient().listPlans(args.git_remote_url);
+            if (plans.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "No plans found for this repository.",
+                        },
+                    ],
+                };
+            }
+            const planList = plans.map((plan) => ({
+                id: plan.id,
+                description: plan.description,
+                status: plan.status,
+                updated_at: plan.updated_at,
+                collaborators: plan.collaborators.map((c) => c.display_name).join(", "),
+            }));
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(planList, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // read_plan tool
+    server.tool("read_plan", TOOL_DESCRIPTIONS.read_plan, ReadPlanSchema.shape, async (args) => {
+        try {
+            const plan = await getClient().getPlan(args.id);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `# ${plan.description}\n\nStatus: ${plan.status}\n\n${plan.body}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // create_plan tool
+    server.tool("create_plan", TOOL_DESCRIPTIONS.create_plan, CreatePlanSchema.shape, async (args) => {
+        try {
+            // Read session_id from file written by PreToolUse hook
+            const claudeSessionId = getSessionIdFromFile();
+            const plan = await getClient().createPlan({
+                description: args.description,
+                body: args.body,
+                claude_session_id: claudeSessionId,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Plan created successfully.\n\nID: ${plan.id}\nDescription: ${plan.description}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // update_plan tool
+    server.tool("update_plan", TOOL_DESCRIPTIONS.update_plan, UpdatePlanSchema.shape, async (args) => {
+        try {
+            // Read session_id from file written by PreToolUse hook
+            const claudeSessionId = getSessionIdFromFile();
+            // Get current plan to compute patch
+            const currentPlan = await getClient().getPlan(args.id);
+            // Compute patch using diff-match-patch
+            const patches = patchMake(currentPlan.body, args.body);
+            const patchText = patchToText(patches);
+            const plan = await getClient().updatePlan(args.id, {
+                body: args.body,
+                patch: patchText,
+                claude_session_id: claudeSessionId,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Plan updated successfully.\n\nID: ${plan.id}\nDescription: ${plan.description}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // set_plan_status tool
+    server.tool("set_plan_status", TOOL_DESCRIPTIONS.set_plan_status, SetPlanStatusSchema.shape, async (args) => {
+        try {
+            const plan = await getClient().setStatus(args.id, args.status);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Plan status updated successfully.\n\nID: ${plan.id}\nDescription: ${plan.description}\nStatus: ${plan.status}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // Start the server with stdio transport
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/commands/off.js

@@ -1,4 +1,4 @@
-import { uninstallHooks } from "../hooks/installer.js";
+import { uninstallHooks, uninstallMcpServer, uninstallPreToolUseHook } from "../hooks/installer.js";
 import { loadConfig } from "../config/manager.js";
 export async function offCommand() {
     // Check if config exists
@@ -15,4 +15,19 @@ export async function offCommand() {
     else {
         console.error(`✗ ${result.message}`);
     }
+    // Remove PreToolUse hook
+    const preToolUseResult = uninstallPreToolUseHook();
+    if (preToolUseResult.success) {
+        console.log(`✓ ${preToolUseResult.message}`);
+    }
+    else {
+        console.error(`✗ ${preToolUseResult.message}`);
+    }
+    const mcpResult = uninstallMcpServer();
+    if (mcpResult.success) {
+        console.log(`✓ ${mcpResult.message}`);
+    }
+    else {
+        console.error(`✗ ${mcpResult.message}`);
+    }
 }

package/dist/commands/on.js

@@ -1,6 +1,6 @@
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-import { installHooks } from "../hooks/installer.js";
+import { installHooks, installMcpServer, installPreToolUseHook } from "../hooks/installer.js";
 import { loadConfig } from "../config/manager.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -26,4 +26,28 @@ export async function onCommand(options = {}) {
     else {
         console.error(`✗ ${result.message}`);
     }
+    // Install MCP server
+    let mcpCommand;
+    let mcpArgs;
+    if (options.dev) {
+        const cliRoot = path.resolve(__dirname, "../..");
+        const indexPath = path.join(cliRoot, "src/index.ts");
+        mcpCommand = "npx";
+        mcpArgs = ["tsx", indexPath, "mcp-server"];
+    }
+    const mcpResult = installMcpServer({ command: mcpCommand, args: mcpArgs });
+    if (mcpResult.success) {
+        console.log(`✓ ${mcpResult.message}`);
+    }
+    else {
+        console.error(`✗ ${mcpResult.message}`);
+    }
+    // Install PreToolUse hook for session_id injection
+    const preToolUseResult = installPreToolUseHook();
+    if (preToolUseResult.success) {
+        console.log(`✓ ${preToolUseResult.message}`);
+    }
+    else {
+        console.error(`✗ ${preToolUseResult.message}`);
+    }
 }

package/dist/commands/send.js

@@ -63,6 +63,11 @@ export async function sendCommand() {
         console.error("[agentrace] Warning: Missing session_id or transcript_path");
         process.exit(0);
     }
+    // For UserPromptSubmit, wait for transcript to be written
+    // (Claude hasn't started processing yet, so transcript may not be updated)
+    if (data.hook_event_name === "UserPromptSubmit") {
+        await sleep(10000);
+    }
     // Get new lines from transcript
     const { lines, totalLineCount } = getNewLines(transcriptPath, sessionId);
     if (lines.length === 0) {
@@ -109,6 +114,9 @@ export async function sendCommand() {
     // Always exit 0 to not block hooks
     process.exit(0);
 }
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 function readStdin() {
     return new Promise((resolve, reject) => {
         let data = "";

package/dist/commands/uninstall.js

@@ -1,5 +1,5 @@
 import { deleteConfig } from "../config/manager.js";
-import { uninstallHooks } from "../hooks/installer.js";
+import { uninstallHooks, uninstallMcpServer, uninstallPreToolUseHook } from "../hooks/installer.js";
 export async function uninstallCommand() {
     console.log("Uninstalling Agentrace...\n");
     // Remove hooks
@@ -10,6 +10,22 @@ export async function uninstallCommand() {
     else {
         console.error(`✗ ${hookResult.message}`);
     }
+    // Remove PreToolUse hook
+    const preToolUseResult = uninstallPreToolUseHook();
+    if (preToolUseResult.success) {
+        console.log(`✓ ${preToolUseResult.message}`);
+    }
+    else {
+        console.error(`✗ ${preToolUseResult.message}`);
+    }
+    // Remove MCP server
+    const mcpResult = uninstallMcpServer();
+    if (mcpResult.success) {
+        console.log(`✓ ${mcpResult.message}`);
+    }
+    else {
+        console.error(`✗ ${mcpResult.message}`);
+    }
     // Remove config
     const configRemoved = deleteConfig();
     if (configRemoved) {

package/dist/hooks/installer.d.ts

@@ -10,3 +10,25 @@ export declare function uninstallHooks(): {
     message: string;
 };
 export declare function checkHooksInstalled(): boolean;
+export interface InstallMcpServerOptions {
+    command?: string;
+    args?: string[];
+}
+export declare function installMcpServer(options?: InstallMcpServerOptions): {
+    success: boolean;
+    message: string;
+};
+export declare function uninstallMcpServer(): {
+    success: boolean;
+    message: string;
+};
+export declare function checkMcpServerInstalled(): boolean;
+export declare function installPreToolUseHook(): {
+    success: boolean;
+    message: string;
+};
+export declare function uninstallPreToolUseHook(): {
+    success: boolean;
+    message: string;
+};
+export declare function checkPreToolUseHookInstalled(): boolean;

package/dist/hooks/installer.js

@@ -2,6 +2,11 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import * as os from "node:os";
 const CLAUDE_SETTINGS_PATH = path.join(os.homedir(), ".claude", "settings.json");
+// MCP servers are configured in ~/.claude.json, NOT in settings.json
+const CLAUDE_CONFIG_PATH = path.join(os.homedir(), ".claude.json");
+// Agentrace hooks directory
+const AGENTRACE_HOOKS_DIR = path.join(os.homedir(), ".agentrace", "hooks");
+const SESSION_ID_HOOK_PATH = path.join(AGENTRACE_HOOKS_DIR, "inject-session-id.js");
 const DEFAULT_COMMAND = "npx agentrace send";
 function createAgentraceHook(command) {
     return {
@@ -27,17 +32,49 @@ export function installHooks(options = {}) {
         if (!settings.hooks) {
             settings.hooks = {};
         }
-        // Add Stop hook only (transcript diff is sent on each Stop)
+        // Add Stop hook (transcript diff is sent on each Stop)
         if (!settings.hooks.Stop) {
             settings.hooks.Stop = [];
         }
+        // Add UserPromptSubmit hook (transcript is sent when user sends a message)
+        if (!settings.hooks.UserPromptSubmit) {
+            settings.hooks.UserPromptSubmit = [];
+        }
+        // Add SubagentStop hook (transcript is sent when a subagent task completes)
+        if (!settings.hooks.SubagentStop) {
+            settings.hooks.SubagentStop = [];
+        }
+        // Add PostToolUse hook (transcript is sent after each tool use for real-time updates)
+        if (!settings.hooks.PostToolUse) {
+            settings.hooks.PostToolUse = [];
+        }
         const hasStopHook = settings.hooks.Stop.some((matcher) => matcher.hooks?.some(isAgentraceHook));
-        if (hasStopHook) {
+        const hasUserPromptSubmitHook = settings.hooks.UserPromptSubmit.some((matcher) => matcher.hooks?.some(isAgentraceHook));
+        const hasSubagentStopHook = settings.hooks.SubagentStop.some((matcher) => matcher.hooks?.some(isAgentraceHook));
+        const hasPostToolUseHook = settings.hooks.PostToolUse.some((matcher) => matcher.hooks?.some(isAgentraceHook));
+        if (hasStopHook && hasUserPromptSubmitHook && hasSubagentStopHook && hasPostToolUseHook) {
             return { success: true, message: "Hooks already installed (skipped)" };
         }
-        settings.hooks.Stop.push({
-            hooks: [agentraceHook],
-        });
+        if (!hasStopHook) {
+            settings.hooks.Stop.push({
+                hooks: [agentraceHook],
+            });
+        }
+        if (!hasUserPromptSubmitHook) {
+            settings.hooks.UserPromptSubmit.push({
+                hooks: [agentraceHook],
+            });
+        }
+        if (!hasSubagentStopHook) {
+            settings.hooks.SubagentStop.push({
+                hooks: [agentraceHook],
+            });
+        }
+        if (!hasPostToolUseHook) {
+            settings.hooks.PostToolUse.push({
+                hooks: [agentraceHook],
+            });
+        }
         // Ensure directory exists
         const dir = path.dirname(CLAUDE_SETTINGS_PATH);
         if (!fs.existsSync(dir)) {
@@ -69,6 +106,27 @@ export function uninstallHooks() {
                 delete settings.hooks.Stop;
             }
         }
+        // Remove agentrace hooks from UserPromptSubmit
+        if (settings.hooks.UserPromptSubmit) {
+            settings.hooks.UserPromptSubmit = settings.hooks.UserPromptSubmit.filter((matcher) => !matcher.hooks?.some(isAgentraceHook));
+            if (settings.hooks.UserPromptSubmit.length === 0) {
+                delete settings.hooks.UserPromptSubmit;
+            }
+        }
+        // Remove agentrace hooks from SubagentStop
+        if (settings.hooks.SubagentStop) {
+            settings.hooks.SubagentStop = settings.hooks.SubagentStop.filter((matcher) => !matcher.hooks?.some(isAgentraceHook));
+            if (settings.hooks.SubagentStop.length === 0) {
+                delete settings.hooks.SubagentStop;
+            }
+        }
+        // Remove agentrace hooks from PostToolUse
+        if (settings.hooks.PostToolUse) {
+            settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter((matcher) => !matcher.hooks?.some(isAgentraceHook));
+            if (settings.hooks.PostToolUse.length === 0) {
+                delete settings.hooks.PostToolUse;
+            }
+        }
         // Clean up empty hooks object
         if (Object.keys(settings.hooks).length === 0) {
             delete settings.hooks;
@@ -92,7 +150,221 @@ export function checkHooksInstalled() {
         const content = fs.readFileSync(CLAUDE_SETTINGS_PATH, "utf-8");
         const settings = JSON.parse(content);
         const hasStopHook = settings.hooks?.Stop?.some((matcher) => matcher.hooks?.some(isAgentraceHook));
-        return !!hasStopHook;
+        const hasUserPromptSubmitHook = settings.hooks?.UserPromptSubmit?.some((matcher) => matcher.hooks?.some(isAgentraceHook));
+        const hasSubagentStopHook = settings.hooks?.SubagentStop?.some((matcher) => matcher.hooks?.some(isAgentraceHook));
+        const hasPostToolUseHook = settings.hooks?.PostToolUse?.some((matcher) => matcher.hooks?.some(isAgentraceHook));
+        return !!hasStopHook && !!hasUserPromptSubmitHook && !!hasSubagentStopHook && !!hasPostToolUseHook;
+    }
+    catch {
+        return false;
+    }
+}
+// MCP Server installer functions
+const MCP_SERVER_NAME = "agentrace";
+export function installMcpServer(options = {}) {
+    const command = options.command || "npx";
+    const args = options.args || ["agentrace", "mcp-server"];
+    try {
+        let config = {};
+        // Load existing config if file exists
+        // MCP servers are configured in ~/.claude.json (NOT settings.json)
+        if (fs.existsSync(CLAUDE_CONFIG_PATH)) {
+            const content = fs.readFileSync(CLAUDE_CONFIG_PATH, "utf-8");
+            config = JSON.parse(content);
+        }
+        // Initialize mcpServers structure if not present
+        if (!config.mcpServers) {
+            config.mcpServers = {};
+        }
+        // Check if already installed
+        if (config.mcpServers[MCP_SERVER_NAME]) {
+            // Update existing config
+            config.mcpServers[MCP_SERVER_NAME] = { command, args };
+            fs.writeFileSync(CLAUDE_CONFIG_PATH, JSON.stringify(config, null, 2));
+            return { success: true, message: "MCP server config updated" };
+        }
+        // Add MCP server config
+        config.mcpServers[MCP_SERVER_NAME] = { command, args };
+        // Write config
+        fs.writeFileSync(CLAUDE_CONFIG_PATH, JSON.stringify(config, null, 2));
+        return { success: true, message: `MCP server added to ${CLAUDE_CONFIG_PATH}` };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { success: false, message: `Failed to install MCP server: ${message}` };
+    }
+}
+export function uninstallMcpServer() {
+    try {
+        if (!fs.existsSync(CLAUDE_CONFIG_PATH)) {
+            return { success: true, message: "No config file found" };
+        }
+        const content = fs.readFileSync(CLAUDE_CONFIG_PATH, "utf-8");
+        const config = JSON.parse(content);
+        if (!config.mcpServers || !config.mcpServers[MCP_SERVER_NAME]) {
+            return { success: true, message: "MCP server not configured" };
+        }
+        // Remove agentrace MCP server
+        delete config.mcpServers[MCP_SERVER_NAME];
+        // Clean up empty mcpServers object
+        if (Object.keys(config.mcpServers).length === 0) {
+            delete config.mcpServers;
+        }
+        fs.writeFileSync(CLAUDE_CONFIG_PATH, JSON.stringify(config, null, 2));
+        return {
+            success: true,
+            message: `Removed MCP server from ${CLAUDE_CONFIG_PATH}`,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { success: false, message: `Failed to uninstall MCP server: ${message}` };
+    }
+}
+export function checkMcpServerInstalled() {
+    try {
+        if (!fs.existsSync(CLAUDE_CONFIG_PATH)) {
+            return false;
+        }
+        const content = fs.readFileSync(CLAUDE_CONFIG_PATH, "utf-8");
+        const config = JSON.parse(content);
+        return !!config.mcpServers?.[MCP_SERVER_NAME];
+    }
+    catch {
+        return false;
+    }
+}
+// PreToolUse hook for injecting session_id into agentrace MCP tools
+const SESSION_ID_HOOK_SCRIPT = `#!/usr/bin/env node
+// Agentrace PreToolUse hook: Writes session_id to file for MCP tools
+// This hook is called before agentrace MCP tools (create_plan, update_plan)
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const sessionFile = path.join(os.homedir(), '.agentrace', 'current-session.json');
+
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => { input += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const sessionId = data.session_id;
+
+    // Write session_id to file for MCP server to read
+    fs.writeFileSync(sessionFile, JSON.stringify({ session_id: sessionId }));
+
+    // Allow the tool to proceed
+    const output = {
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "allow"
+      }
+    };
+    console.log(JSON.stringify(output));
+  } catch (e) {
+    process.stderr.write('Error: ' + e.message);
+    process.exit(1);
+  }
+});
+`;
+const AGENTRACE_MCP_TOOLS_MATCHER = "mcp__agentrace__create_plan|mcp__agentrace__update_plan";
+function isAgentracePreToolUseHook(matcher) {
+    return matcher.matcher === AGENTRACE_MCP_TOOLS_MATCHER &&
+        matcher.hooks?.some(h => h.command?.includes("inject-session-id"));
+}
+export function installPreToolUseHook() {
+    try {
+        // Create hooks directory if not exists
+        if (!fs.existsSync(AGENTRACE_HOOKS_DIR)) {
+            fs.mkdirSync(AGENTRACE_HOOKS_DIR, { recursive: true });
+        }
+        // Write hook script
+        fs.writeFileSync(SESSION_ID_HOOK_PATH, SESSION_ID_HOOK_SCRIPT, { mode: 0o755 });
+        // Load existing settings
+        let settings = {};
+        if (fs.existsSync(CLAUDE_SETTINGS_PATH)) {
+            const content = fs.readFileSync(CLAUDE_SETTINGS_PATH, "utf-8");
+            settings = JSON.parse(content);
+        }
+        // Initialize hooks structure if not present
+        if (!settings.hooks) {
+            settings.hooks = {};
+        }
+        if (!settings.hooks.PreToolUse) {
+            settings.hooks.PreToolUse = [];
+        }
+        // Check if already installed
+        const hasPreToolUseHook = settings.hooks.PreToolUse.some(isAgentracePreToolUseHook);
+        if (hasPreToolUseHook) {
+            return { success: true, message: "PreToolUse hook already installed (skipped)" };
+        }
+        // Add PreToolUse hook
+        settings.hooks.PreToolUse.push({
+            matcher: AGENTRACE_MCP_TOOLS_MATCHER,
+            hooks: [
+                {
+                    type: "command",
+                    command: SESSION_ID_HOOK_PATH,
+                },
+            ],
+        });
+        // Ensure directory exists
+        const dir = path.dirname(CLAUDE_SETTINGS_PATH);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        // Write settings
+        fs.writeFileSync(CLAUDE_SETTINGS_PATH, JSON.stringify(settings, null, 2));
+        return { success: true, message: `PreToolUse hook installed to ${SESSION_ID_HOOK_PATH}` };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { success: false, message: `Failed to install PreToolUse hook: ${message}` };
+    }
+}
+export function uninstallPreToolUseHook() {
+    try {
+        // Remove hook script
+        if (fs.existsSync(SESSION_ID_HOOK_PATH)) {
+            fs.unlinkSync(SESSION_ID_HOOK_PATH);
+        }
+        // Remove from settings
+        if (!fs.existsSync(CLAUDE_SETTINGS_PATH)) {
+            return { success: true, message: "No settings file found" };
+        }
+        const content = fs.readFileSync(CLAUDE_SETTINGS_PATH, "utf-8");
+        const settings = JSON.parse(content);
+        if (!settings.hooks?.PreToolUse) {
+            return { success: true, message: "No PreToolUse hooks configured" };
+        }
+        // Remove agentrace PreToolUse hooks
+        settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter((matcher) => !isAgentracePreToolUseHook(matcher));
+        if (settings.hooks.PreToolUse.length === 0) {
+            delete settings.hooks.PreToolUse;
+        }
+        // Clean up empty hooks object
+        if (Object.keys(settings.hooks).length === 0) {
+            delete settings.hooks;
+        }
+        fs.writeFileSync(CLAUDE_SETTINGS_PATH, JSON.stringify(settings, null, 2));
+        return { success: true, message: "PreToolUse hook removed" };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { success: false, message: `Failed to uninstall PreToolUse hook: ${message}` };
+    }
+}
+export function checkPreToolUseHookInstalled() {
+    try {
+        if (!fs.existsSync(CLAUDE_SETTINGS_PATH) || !fs.existsSync(SESSION_ID_HOOK_PATH)) {
+            return false;
+        }
+        const content = fs.readFileSync(CLAUDE_SETTINGS_PATH, "utf-8");
+        const settings = JSON.parse(content);
+        return settings.hooks?.PreToolUse?.some(isAgentracePreToolUseHook) ?? false;
     }
     catch {
         return false;

package/dist/index.js

@@ -6,6 +6,7 @@ import { sendCommand } from "./commands/send.js";
 import { uninstallCommand } from "./commands/uninstall.js";
 import { onCommand } from "./commands/on.js";
 import { offCommand } from "./commands/off.js";
+import { mcpServerCommand } from "./commands/mcp-server.js";
 const program = new Command();
 program.name("agentrace").description("CLI for Agentrace").version("0.1.0");
 program
@@ -47,4 +48,10 @@ program
     .action(async () => {
     await offCommand();
 });
+program
+    .command("mcp-server")
+    .description("Run MCP server for Claude Code integration (stdio)")
+    .action(async () => {
+    await mcpServerCommand();
+});
 program.parse();

package/dist/mcp/plan-document-client.d.ts

@@ -0,0 +1,57 @@
+export type PlanDocumentStatus = "scratch" | "draft" | "planning" | "pending" | "implementation" | "complete";
+export interface Project {
+    id: string;
+    canonical_git_repository: string;
+}
+export interface PlanDocument {
+    id: string;
+    description: string;
+    body: string;
+    project: Project | null;
+    status: PlanDocumentStatus;
+    collaborators: {
+        id: string;
+        display_name: string;
+    }[];
+    created_at: string;
+    updated_at: string;
+}
+export interface PlanDocumentEvent {
+    id: string;
+    plan_document_id: string;
+    claude_session_id: string | null;
+    user_id: string | null;
+    user_name: string | null;
+    patch: string;
+    created_at: string;
+}
+export interface ListPlansResponse {
+    plans: PlanDocument[];
+}
+export interface ListEventsResponse {
+    events: PlanDocumentEvent[];
+}
+export interface CreatePlanRequest {
+    description: string;
+    body: string;
+    claude_session_id?: string;
+}
+export interface UpdatePlanRequest {
+    description?: string;
+    body?: string;
+    patch?: string;
+    claude_session_id?: string;
+}
+export declare class PlanDocumentClient {
+    private serverUrl;
+    private apiKey;
+    constructor();
+    private request;
+    listPlans(gitRemoteUrl?: string): Promise<PlanDocument[]>;
+    getPlan(id: string): Promise<PlanDocument>;
+    getPlanEvents(id: string): Promise<PlanDocumentEvent[]>;
+    createPlan(req: CreatePlanRequest): Promise<PlanDocument>;
+    updatePlan(id: string, req: UpdatePlanRequest): Promise<PlanDocument>;
+    deletePlan(id: string): Promise<void>;
+    setStatus(id: string, status: PlanDocumentStatus): Promise<PlanDocument>;
+}

package/dist/mcp/plan-document-client.js

@@ -0,0 +1,61 @@
+import { loadConfig } from "../config/manager.js";
+export class PlanDocumentClient {
+    serverUrl;
+    apiKey;
+    constructor() {
+        const config = loadConfig();
+        if (!config) {
+            throw new Error("Agentrace is not configured. Run 'npx agentrace init' first.");
+        }
+        this.serverUrl = config.server_url;
+        this.apiKey = config.api_key;
+    }
+    async request(method, path, body) {
+        const url = `${this.serverUrl}${path}`;
+        const headers = {
+            "Authorization": `Bearer ${this.apiKey}`,
+            "Content-Type": "application/json",
+        };
+        const response = await fetch(url, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`API request failed: ${response.status} ${errorText}`);
+        }
+        // Handle 204 No Content
+        if (response.status === 204) {
+            return undefined;
+        }
+        return response.json();
+    }
+    async listPlans(gitRemoteUrl) {
+        let path = "/api/plans";
+        if (gitRemoteUrl) {
+            path += `?git_remote_url=${encodeURIComponent(gitRemoteUrl)}`;
+        }
+        const response = await this.request("GET", path);
+        return response.plans;
+    }
+    async getPlan(id) {
+        return this.request("GET", `/api/plans/${id}`);
+    }
+    async getPlanEvents(id) {
+        const response = await this.request("GET", `/api/plans/${id}/events`);
+        return response.events;
+    }
+    async createPlan(req) {
+        return this.request("POST", "/api/plans", req);
+    }
+    async updatePlan(id, req) {
+        return this.request("PATCH", `/api/plans/${id}`, req);
+    }
+    async deletePlan(id) {
+        await this.request("DELETE", `/api/plans/${id}`);
+    }
+    async setStatus(id, status) {
+        return this.request("PATCH", `/api/plans/${id}/status`, { status });
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agentrace",
-  "version": "0.0.1",
-  "description": "CLI for Agentrace - Claude Code session tracker",
+  "version": "0.0.3",
+  "description": "CLI for AgenTrace - Claude Code session tracker",
   "type": "module",
   "bin": {
     "agentrace": "./dist/index.js"
@@ -35,7 +35,10 @@
     "url": "https://github.com/satetsu888/agentrace/issues"
   },
   "dependencies": {
-    "commander": "^12.0.0"
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "commander": "^12.0.0",
+    "diff-match-patch-es": "^1.0.0",
+    "zod": "^3.25.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",