[codex] add codemap plugin install flow (#60)

* add codemap plugin install flow

* address plugin review feedback

Author: JordanCoin

.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "codemap-local",
+  "interface": {
+    "displayName": "Codemap Local"
+  },
+  "plugins": [
+    {
+      "name": "codemap",
+      "source": {
+        "source": "local",
+        "path": "./plugins/codemap"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Coding"
+    }
+  ]
+}

.gitignore

@@ -2,16 +2,16 @@ venv/
 __pycache__/
 
 # Built binaries
-codemap
-codemap-mcp
-codemap-test
-mcp-test
-hub-check
+/codemap
+/codemap-mcp
+/codemap-test
+/mcp-test
+/hub-check
 
 # Runtime state
 .codemap/
-codemap-dev
-dev_codemap
+/codemap-dev
+/dev_codemap
 firebase-debug.log
 firebalse-debug.log
 coverage.out

Makefile

@@ -6,7 +6,7 @@ build:
 	go build -o codemap .
 
 build-mcp:
-	go build -o codemap-mcp ./mcp/
+	go build -o codemap-mcp ./cmd/codemap-mcp/
 
 DIR ?= .
 ABS_DIR := $(shell cd "$(DIR)" && pwd)

README.md

@@ -76,6 +76,8 @@ codemap handoff .  # Save layered handoff for cross-agent continuation
 codemap --deps .   # Dependency flow (requires ast-grep)
 codemap skill list # Show available skills
 codemap context    # Universal JSON context for any AI tool
+codemap mcp        # Run Codemap MCP server on stdio
+codemap plugin install # Install the Codemap Codex plugin
 codemap serve      # HTTP API for non-MCP integrations
 ```
 

cmd/codemap-mcp/main.go

@@ -0,0 +1,16 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	codemapmcp "codemap/mcp"
+)
+
+func main() {
+	if err := codemapmcp.Run(context.Background()); err != nil {
+		fmt.Fprintf(os.Stderr, "MCP server error: %v\n", err)
+		os.Exit(1)
+	}
+}

cmd/plugin.go

@@ -0,0 +1,85 @@
+package cmd
+
+import (
+	"errors"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+
+	pluginbundle "codemap/plugins"
+)
+
+// RunPlugin handles the "codemap plugin" subcommand.
+func RunPlugin(args []string) {
+	subCmd := ""
+	if len(args) > 0 {
+		subCmd = args[0]
+	}
+
+	switch subCmd {
+	case "install":
+		runPluginInstall(args[1:])
+	default:
+		fmt.Println("Usage: codemap plugin install")
+		fmt.Println()
+		fmt.Println("Commands:")
+		fmt.Println("  install       Install the Codemap plugin into ~/.agents/plugins and ~/plugins")
+	}
+}
+
+func runPluginInstall(args []string) {
+	fs := flag.NewFlagSet("plugin install", flag.ContinueOnError)
+	fs.SetOutput(io.Discard)
+	homeDir := fs.String("home", "", "Override the home directory used for plugin installation")
+	pluginPath := fs.String("plugin-path", "", "Override the installed plugin path")
+	marketplacePath := fs.String("marketplace-path", "", "Override the marketplace manifest path")
+	if err := fs.Parse(args); err != nil {
+		if errors.Is(err, flag.ErrHelp) {
+			fmt.Println("Usage: codemap plugin install [--home <dir>] [--plugin-path <dir>] [--marketplace-path <file>]")
+			return
+		}
+		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+		fmt.Fprintln(os.Stderr, "Usage: codemap plugin install [--home <dir>] [--plugin-path <dir>] [--marketplace-path <file>]")
+		os.Exit(2)
+	}
+	if fs.NArg() != 0 {
+		fmt.Fprintln(os.Stderr, "Usage: codemap plugin install [--home <dir>] [--plugin-path <dir>] [--marketplace-path <file>]")
+		os.Exit(1)
+	}
+
+	result, err := pluginbundle.InstallCodemapPlugin(pluginbundle.InstallOptions{
+		HomeDir:         *homeDir,
+		PluginPath:      *pluginPath,
+		MarketplacePath: *marketplacePath,
+	})
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Plugin install failed: %v\n", err)
+		os.Exit(1)
+	}
+
+	absPluginPath, _ := filepath.Abs(result.PluginPath)
+	absMarketplacePath, _ := filepath.Abs(result.MarketplacePath)
+
+	fmt.Println("codemap plugin install")
+	fmt.Printf("Plugin: %s\n", absPluginPath)
+	fmt.Printf("Marketplace: %s\n", absMarketplacePath)
+	fmt.Printf("Files written: %d\n", result.FilesWritten)
+	if result.FilesUnchanged > 0 {
+		fmt.Printf("Files unchanged: %d\n", result.FilesUnchanged)
+	}
+	switch {
+	case result.CreatedMarketplace:
+		fmt.Println("Marketplace entry: created")
+	case result.UpdatedMarketplace:
+		fmt.Println("Marketplace entry: updated")
+	default:
+		fmt.Println("Marketplace entry: already configured")
+	}
+	fmt.Println()
+	fmt.Println("Next:")
+	fmt.Println("  1. Restart Codex or reload plugins.")
+	fmt.Println("  2. Verify the Codemap plugin appears in your plugin list.")
+	fmt.Println("  3. If Codemap was installed before this release, update it so `codemap mcp` is available.")
+}

cmd/plugin_test.go

@@ -0,0 +1,33 @@
+package cmd
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestRunPluginInstall(t *testing.T) {
+	home := t.TempDir()
+
+	out := captureOutput(func() {
+		RunPlugin([]string{"install", "--home", home})
+	})
+
+	checks := []string{
+		"codemap plugin install",
+		"Plugin:",
+		"Marketplace:",
+		"Marketplace entry: created",
+	}
+	for _, check := range checks {
+		if !strings.Contains(out, check) {
+			t.Fatalf("expected output to contain %q, got:\n%s", check, out)
+		}
+	}
+
+	pluginJSON := filepath.Join(home, "plugins", "codemap", ".codex-plugin", "plugin.json")
+	if _, err := os.Stat(pluginJSON); err != nil {
+		t.Fatalf("expected installed plugin manifest to exist: %v", err)
+	}
+}

docs/MCP.md

@@ -4,6 +4,12 @@ Run codemap as an MCP (Model Context Protocol) server for deep Claude integratio
 
 ## Setup
 
+Preferred when `codemap` is already installed:
+
+```bash
+claude mcp add --transport stdio codemap -- codemap mcp
+```
+
 ### Build
 
 ```bash
@@ -22,8 +28,8 @@ Or add to your project's `.mcp.json`:
 {
   "mcpServers": {
     "codemap": {
-      "command": "/path/to/codemap-mcp",
-      "args": []
+      "command": "codemap",
+      "args": ["mcp"]
     }
   }
 }
@@ -39,12 +45,15 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 {
   "mcpServers": {
     "codemap": {
-      "command": "/path/to/codemap-mcp"
+      "command": "codemap",
+      "args": ["mcp"]
     }
   }
 }
 ```
 
+If you prefer a standalone MCP binary, keep using `/path/to/codemap-mcp`.
+
 ## Available Tools (17)
 
 ### Project Analysis

main.go

@@ -1,6 +1,7 @@
 package main
 
 import (
+	"context"
 	"encoding/json"
 	"errors"
 	"flag"
@@ -17,6 +18,7 @@ import (
 	"codemap/config"
 	"codemap/handoff"
 	"codemap/limits"
+	codemapmcp "codemap/mcp"
 	"codemap/render"
 	"codemap/scanner"
 	"codemap/watch"
@@ -104,13 +106,28 @@ func main() {
 		return
 	}
 
+	// Handle "mcp" subcommand before global flag parsing
+	if len(os.Args) >= 2 && os.Args[1] == "mcp" {
+		if err := codemapmcp.Run(context.Background()); err != nil {
+			fmt.Fprintf(os.Stderr, "MCP server error: %v\n", err)
+			os.Exit(1)
+		}
+		return
+	}
+
 	// Handle "skill" subcommand before global flag parsing
 	if len(os.Args) >= 2 && os.Args[1] == "skill" {
 		root, _ := os.Getwd()
 		cmd.RunSkill(os.Args[2:], root)
 		return
 	}
 
+	// Handle "plugin" subcommand before global flag parsing
+	if len(os.Args) >= 2 && os.Args[1] == "plugin" {
+		cmd.RunPlugin(os.Args[2:])
+		return
+	}
+
 	// Handle "context" subcommand before global flag parsing
 	if len(os.Args) >= 2 && os.Args[1] == "context" {
 		root, _ := os.Getwd()
@@ -197,6 +214,12 @@ func main() {
 		fmt.Println("  codemap config init             # Create .codemap/config.json (auto-detects extensions)")
 		fmt.Println("  codemap config show             # Show current project config")
 		fmt.Println()
+		fmt.Println("Plugin management:")
+		fmt.Println("  codemap plugin install          # Install the Codemap plugin into your home plugin marketplace")
+		fmt.Println()
+		fmt.Println("MCP server:")
+		fmt.Println("  codemap mcp                     # Run Codemap MCP server on stdio")
+		fmt.Println()
 		fmt.Println("Recommended onboarding:")
 		fmt.Println("  codemap setup                   # Configure project config + Claude hooks")
 		fmt.Println("  codemap setup --global          # Write hooks to ~/.claude/settings.json")

mcp/main.go

@@ -1,12 +1,11 @@
 // MCP Server for codemap - provides codebase analysis tools to LLMs
-package main
+package codemapmcp
 
 import (
 	"bytes"
 	"context"
 	"encoding/json"
 	"fmt"
-	"log"
 	"os"
 	"path/filepath"
 	"regexp"
@@ -83,7 +82,7 @@ type HandoffInput struct {
 	File   string `json:"file,omitempty" jsonschema:"Load detailed context for one changed file path from handoff delta"`
 }
 
-func main() {
+func NewServer() *mcp.Server {
 	server := mcp.NewServer(&mcp.Implementation{
 		Name:    "codemap",
 		Version: "2.0.0",
@@ -191,10 +190,11 @@ func main() {
 		Description: "Load the full instructions for a specific skill by name. Returns the complete markdown body with step-by-step guidance. Use after list_skills to get detailed guidance for a task.",
 	}, handleGetSkill)
 
-	// Run server on stdio
-	if err := server.Run(context.Background(), &mcp.StdioTransport{}); err != nil {
-		log.Printf("Server error: %v", err)
-	}
+	return server
+}
+
+func Run(ctx context.Context) error {
+	return NewServer().Run(ctx, &mcp.StdioTransport{})
 }
 
 func textResult(text string) *mcp.CallToolResult {