diff --git a/MULTI_CC_WORKTREES.md b/MULTI_CC_WORKTREES.md
new file mode 100644
index 0000000..e1e88f7
--- /dev/null
+++ b/MULTI_CC_WORKTREES.md
@@ -0,0 +1,340 @@
+# Multiple Claude Code Instances with Git Worktrees Support
+
+## Overview
+
+This document outlines a comprehensive plan to upgrade claudecode.nvim to support multiple Claude Code instances, where each instance is connected to the Neovim instance that started it. This enables N git worktrees with N AI assistants working in parallel.
+
+## Current Architecture Analysis
+
+### Current Limitations
+
+1. **Single Server Instance**: The plugin maintains a single WebSocket server state in `M.state.server`
+2. **Single Port**: Only one port is tracked at a time in `M.state.port`
+3. **Single Lock File**: Creates one lock file at `~/.claude/ide/[port].lock`
+4. **Global State**: Uses module-level state that prevents multiple instances
+5. **Single Terminal**: Terminal module manages one Claude instance at a time
+
+### Key Components to Modify
+
+1. **Server Management** (`lua/claudecode/server/init.lua`)
+   - Currently uses singleton pattern with `M.state`
+   - Needs instance-based architecture
+
+2. **Lock File System** (`lua/claudecode/lockfile.lua`)
+   - Creates discovery files for Claude
+   - Needs to support multiple lock files with instance identification
+
+3. **Terminal Management** (`lua/claudecode/terminal.lua`)
+   - Manages Claude Code terminal windows
+   - Needs to track multiple terminals per instance
+
+4. **Main Plugin Module** (`lua/claudecode/init.lua`)
+   - Central coordination point
+   - Needs instance manager and routing logic
+
+## Proposed Architecture
+
+### 1. Instance-Based Design
+
+```lua
+-- New instance manager
+local InstanceManager = {
+  instances = {},  -- Map of instance_id -> instance_data
+  active_instance = nil,  -- Currently active instance
+}
+
+-- Instance data structure
+local Instance = {
+  id = "unique-id",  -- Generated UUID or worktree path hash
+  server = nil,      -- WebSocket server for this instance
+  port = nil,        -- Port for this instance
+  terminal = nil,    -- Terminal state for this instance
+  worktree_path = "/path/to/worktree",
+  neovim_pid = vim.fn.getpid(),
+  created_at = os.time(),
+}
+```
+
+### 2. Multi-Instance Server Architecture
+
+#### Server Modifications
+
+```lua
+-- lua/claudecode/server/instance.lua (NEW)
+local Instance = {}
+Instance.__index = Instance
+
+function Instance:new(config)
+  local instance = {
+    id = vim.fn.sha256(config.worktree_path .. os.time()),
+    config = config,
+    server = nil,
+    port = nil,
+    clients = {},
+    handlers = {},
+    ping_timer = nil,
+  }
+  setmetatable(instance, Instance)
+  return instance
+end
+
+function Instance:start()
+  -- Start WebSocket server for this instance
+  -- Return port
+end
+
+function Instance:stop()
+  -- Stop this instance's server
+end
+```
+
+### 3. Enhanced Lock File System
+
+#### Lock File Format Update
+
+```json
+{
+  "pid": 12345,
+  "neovimPid": 67890,  // NEW: Neovim process ID
+  "instanceId": "abc123",  // NEW: Unique instance identifier
+  "workspaceFolders": ["/path/to/worktree"],
+  "worktreePath": "/path/to/worktree",  // NEW: Git worktree path
+  "ideName": "Neovim",
+  "transport": "ws",
+  "createdAt": 1234567890,  // NEW: Timestamp
+  "parentPort": 10001  // NEW: Optional parent instance port
+}
+```
+
+### 4. Instance Discovery and Management
+
+#### Instance Manager Implementation
+
+```lua
+-- lua/claudecode/instance_manager.lua (NEW)
+local M = {}
+
+-- Get instance for current buffer/worktree
+function M.get_current_instance()
+  local worktree_path = M.detect_worktree_path()
+  return M.instances[worktree_path]
+end
+
+-- Create new instance for worktree
+function M.create_instance(worktree_path, config)
+  local instance = Instance:new({
+    worktree_path = worktree_path,
+    config = config,
+  })
+  
+  M.instances[worktree_path] = instance
+  return instance
+end
+
+-- Detect git worktree for current buffer
+function M.detect_worktree_path()
+  local current_file = vim.fn.expand("%:p")
+  -- Use git rev-parse to find worktree root
+  local handle = io.popen("git -C " .. vim.fn.shellescape(vim.fn.fnamemodify(current_file, ":h")) .. " rev-parse --show-toplevel 2>/dev/null")
+  local worktree_path = handle:read("*l")
+  handle:close()
+  return worktree_path
+end
+```
+
+### 5. Updated Command Structure
+
+#### New Commands
+
+```vim
+" Instance-aware commands
+:ClaudeCode                    " Opens Claude for current worktree
+:ClaudeCodeList               " List all active instances
+:ClaudeCodeSwitch <instance>  " Switch to specific instance
+:ClaudeCodeKill <instance>    " Stop specific instance
+:ClaudeCodeKillAll            " Stop all instances
+
+" Instance-specific operations
+:ClaudeCodeSend               " Sends to current worktree's Claude
+:ClaudeCodeAdd <file>         " Adds to current worktree's Claude
+```
+
+### 6. Terminal Management Updates
+
+#### Multi-Terminal Support
+
+```lua
+-- lua/claudecode/terminal/manager.lua (NEW)
+local TerminalManager = {}
+
+function TerminalManager:new()
+  return {
+    terminals = {},  -- Map of instance_id -> terminal
+  }
+end
+
+function TerminalManager:get_or_create(instance_id, cmd, env)
+  if not self.terminals[instance_id] then
+    self.terminals[instance_id] = self:create_terminal(instance_id, cmd, env)
+  end
+  return self.terminals[instance_id]
+end
+```
+
+### 7. Environment Variable Isolation
+
+Each Claude instance needs isolated environment variables:
+
+```lua
+function get_instance_env(instance)
+  return {
+    CLAUDE_CODE_SSE_PORT = tostring(instance.port),
+    ENABLE_IDE_INTEGRATION = "true",
+    CLAUDE_INSTANCE_ID = instance.id,  -- NEW
+    CLAUDE_WORKTREE_PATH = instance.worktree_path,  -- NEW
+  }
+end
+```
+
+## Implementation Plan
+
+### Phase 1: Core Infrastructure (Week 1)
+
+1. Create `Instance` class for managing individual Claude connections
+2. Implement `InstanceManager` for tracking multiple instances
+3. Update lock file format and creation logic
+4. Add worktree detection utilities
+
+### Phase 2: Server Modifications (Week 2)
+
+1. Refactor server module to support instance-based operation
+2. Update WebSocket handling for multiple concurrent servers
+3. Implement port allocation strategy (avoid conflicts)
+4. Add instance-specific message routing
+
+### Phase 3: Terminal Integration (Week 3)
+
+1. Create `TerminalManager` for multi-terminal support
+2. Update terminal providers (native & snacks) for instances
+3. Implement terminal-to-instance association
+4. Add visual indicators for instance identification
+
+### Phase 4: Command Updates (Week 4)
+
+1. Update existing commands to be instance-aware
+2. Implement new instance management commands
+3. Add instance switcher UI (telescope integration?)
+4. Create status indicators for active instances
+
+### Phase 5: Testing & Polish (Week 5)
+
+1. Comprehensive test suite for multi-instance scenarios
+2. Performance testing with multiple instances
+3. Memory leak detection and cleanup
+4. Documentation updates
+
+## Configuration Options
+
+```lua
+{
+  "coder/claudecode.nvim",
+  config = {
+    multi_instance = {
+      enabled = true,
+      max_instances = 5,  -- Limit concurrent instances
+      auto_start_for_worktree = true,  -- Auto-start when entering new worktree
+      instance_indicator = true,  -- Show instance in statusline
+      cleanup_on_exit = true,  -- Clean up instances on Neovim exit
+    },
+    instance_naming = {
+      -- How to name instances in UI
+      format = "worktree",  -- "worktree", "branch", "custom"
+      custom_formatter = nil,  -- Function to generate instance names
+    },
+  },
+}
+```
+
+## Usage Examples
+
+### Basic Multi-Instance Workflow
+
+```bash
+# Terminal 1: Main project
+cd ~/projects/myapp
+nvim src/main.lua
+:ClaudeCode  # Starts instance for main worktree
+
+# Terminal 2: Feature branch worktree
+cd ~/projects/myapp-feature-x
+nvim src/feature.lua
+:ClaudeCode  # Starts separate instance for this worktree
+
+# Both Claude instances run independently
+```
+
+### Advanced Scenarios
+
+```vim
+" List all active Claude instances
+:ClaudeCodeList
+" Output:
+" 1. [main] ~/projects/myapp (port: 10001)
+" 2. [feature-x] ~/projects/myapp-feature-x (port: 10002) *active*
+
+" Switch to different instance
+:ClaudeCodeSwitch 1
+
+" Send selection to specific instance
+:'<,'>ClaudeCodeSendTo feature-x
+
+" Kill instance for current worktree
+:ClaudeCodeKill
+```
+
+## Benefits
+
+1. **Parallel Development**: Work on multiple features simultaneously with separate AI assistants
+2. **Context Isolation**: Each Claude instance only sees its worktree's context
+3. **Resource Efficiency**: Start/stop instances as needed
+4. **Workflow Integration**: Seamless integration with git worktree workflows
+
+## Challenges & Solutions
+
+### Challenge 1: Resource Management
+- **Solution**: Implement instance limits and automatic cleanup
+- Monitor memory usage per instance
+- Provide cleanup commands and auto-cleanup options
+
+### Challenge 2: Instance Discovery
+- **Solution**: Use combination of worktree path and Neovim PID
+- Implement robust instance matching algorithm
+- Handle edge cases (submodules, nested worktrees)
+
+### Challenge 3: User Experience
+- **Solution**: Clear visual indicators for active instance
+- Statusline integration showing current instance
+- Telescope picker for instance switching
+
+### Challenge 4: Backward Compatibility
+- **Solution**: Default to single-instance mode
+- Detect multi-instance need automatically
+- Provide migration guide for existing users
+
+## Testing Strategy
+
+1. **Unit Tests**: Test each component in isolation
+2. **Integration Tests**: Test multi-instance scenarios
+3. **Performance Tests**: Measure overhead of multiple instances
+4. **User Acceptance**: Beta testing with power users
+
+## Migration Path
+
+1. **Version 1.x**: Current single-instance behavior (default)
+2. **Version 2.0**: Multi-instance support (opt-in)
+3. **Version 2.1**: Multi-instance by default with auto-detection
+4. **Version 3.0**: Full multi-instance with advanced features
+
+## Conclusion
+
+This upgrade will transform claudecode.nvim into a powerful multi-instance AI coding assistant, perfectly suited for modern development workflows using git worktrees. The architecture ensures scalability, maintainability, and excellent user experience while preserving backward compatibility.
\ No newline at end of file
diff --git a/docs/adr/001-websockets-vs-webtransport.md b/docs/adr/001-websockets-vs-webtransport.md
new file mode 100644
index 0000000..ddc154f
--- /dev/null
+++ b/docs/adr/001-websockets-vs-webtransport.md
@@ -0,0 +1,133 @@
+# ADR-001: Use WebSocket Protocol for Multi-Instance Support
+
+**Date**: 2025-01-15  
+**Status**: Accepted  
+**Authors**: vng  
+
+## Context
+
+As we plan to support multiple Claude Code instances (one per git worktree), we need to decide how to handle multiple concurrent connections between Neovim and Claude processes. Two options were considered:
+
+1. **Multiple WebSocket servers** (current approach) - Each instance gets its own port
+2. **WebTransport with multiplexing** - Single server with multiplexed streams
+
+## Decision
+
+We will continue using **WebSocket protocol** with multiple server instances, one per Claude Code instance.
+
+## Rationale
+
+### 1. Claude Code Compatibility
+- Claude Code CLI explicitly expects WebSocket connections
+- Lock files specify `"transport": "ws"`
+- No evidence of WebTransport support in Claude Code
+- Changing protocols would break compatibility
+
+### 2. Technical Constraints
+```lua
+-- Current implementation uses vim.loop (libuv)
+local server = vim.loop.new_tcp()
+server:bind("127.0.0.1", port)
+```
+- Neovim has no native HTTP/3 or QUIC support
+- WebTransport would require external C dependencies
+- Would significantly increase implementation complexity
+
+### 3. Simplicity Wins
+```lua
+-- Multiple servers approach is straightforward
+InstanceManager = {
+  instances = {
+    ["/worktree/main"] = { port = 10001, server = server1 },
+    ["/worktree/feature"] = { port = 10002, server = server2 },
+  }
+}
+```
+
+### 4. Process Isolation Benefits
+- Each Claude process connects to its dedicated server
+- Natural security boundary between instances
+- No risk of message routing errors
+- Simple debugging (can monitor specific ports)
+
+### 5. Resource Efficiency
+- WebSocket servers are lightweight (~5MB per instance)
+- Port range 10000-65535 provides 55,535 available ports
+- vim.loop efficiently handles multiple TCP servers
+- No practical limit for typical usage (5-10 instances)
+
+## Consequences
+
+### Positive
+- ✅ Zero changes needed to Claude Code protocol
+- ✅ Simple implementation (~300 lines vs ~1000+ for WebTransport)
+- ✅ Easy to debug with standard WebSocket tools
+- ✅ Each instance is fully isolated
+- ✅ Works with existing Neovim capabilities
+
+### Negative
+- ❌ Uses one port per instance (not really an issue)
+- ❌ Slightly more OS resources than multiplexing (negligible)
+- ❌ Must manage port allocation (simple with random selection)
+
+### Neutral
+- Each instance creates a separate lock file in `~/.claude/ide/`
+- Need to implement instance cleanup on Neovim exit
+- Status tracking becomes slightly more complex
+
+## Implementation Notes
+
+```lua
+-- Port allocation strategy
+function find_port_for_instance(instance_id)
+  local min, max = 10000, 65535
+  for i = 1, 100 do  -- Try up to 100 times
+    local port = math.random(min, max)
+    if try_bind(port) then
+      return port
+    end
+  end
+  error("Could not find available port")
+end
+
+-- Instance cleanup
+vim.api.nvim_create_autocmd("VimLeavePre", {
+  callback = function()
+    for _, instance in pairs(instances) do
+      instance:stop()
+    end
+  end
+})
+```
+
+## Alternatives Considered
+
+### WebTransport
+- **Pros**: Stream multiplexing, better performance, modern protocol
+- **Cons**: Not supported by Claude, requires external deps, complex implementation
+- **Verdict**: Over-engineering for this use case
+
+### Single Server with Message Routing
+- **Pros**: One port, centralized management
+- **Cons**: Complex routing logic, breaks Claude's assumption of dedicated connection
+- **Verdict**: Would require Claude-side changes
+
+### Unix Domain Sockets
+- **Pros**: No port management, faster than TCP
+- **Cons**: Not supported by Claude WebSocket client
+- **Verdict**: Incompatible with current protocol
+
+## References
+
+- [WebSocket Protocol RFC 6455](https://tools.ietf.org/html/rfc6455)
+- [Claude Code Protocol Documentation](../PROTOCOL.md)
+- [Current WebSocket Implementation](../../lua/claudecode/server/)
+- [Multi-Instance Plan](../../MULTI_CC_WORKTREES.md)
+
+## Review Notes
+
+This decision can be revisited if:
+- Claude Code adds WebTransport support
+- Neovim adds native HTTP/3 support
+- We encounter port exhaustion issues (unlikely)
+- Performance becomes a bottleneck (current latency <1ms)
\ No newline at end of file
diff --git a/docs/adr/002-agent-to-agent-protocol.md b/docs/adr/002-agent-to-agent-protocol.md
new file mode 100644
index 0000000..577ea84
--- /dev/null
+++ b/docs/adr/002-agent-to-agent-protocol.md
@@ -0,0 +1,269 @@
+# ADR-002: Agent-to-Agent Protocol as Separate Library
+
+**Date**: 2025-01-15  
+**Status**: Proposed  
+**Authors**: vng  
+
+## Context
+
+With multi-instance Claude Code support, we have the opportunity to enable agent-to-agent (A2A) communication. This would allow multiple Claude instances to collaborate, share context, and coordinate on complex tasks across different worktrees.
+
+## Decision
+
+**Create a separate library** (`claudecode-a2a` or `mcp-a2a`) to handle agent-to-agent communication, rather than building it into claudecode.nvim.
+
+## Rationale
+
+### 1. Separation of Concerns
+- **claudecode.nvim**: IDE integration (editor ↔ Claude)
+- **claudecode-a2a**: Agent coordination (Claude ↔ Claude)
+- Clean architectural boundaries
+
+### 2. Protocol Independence
+```lua
+-- claudecode.nvim focuses on MCP-WebSocket
+local ide_protocol = "mcp-over-websocket"
+
+-- a2a library can use different transports
+local a2a_protocols = {
+  "grpc",
+  "msgpack-rpc", 
+  "nats",
+  "redis-pubsub"
+}
+```
+
+### 3. Broader Applicability
+- A2A protocol could work with:
+  - Multiple Claude Code instances
+  - Different AI agents (GPT, Gemini, etc.)
+  - Custom agents and tools
+  - CI/CD automation agents
+
+## Proposed Architecture
+
+### A2A Library Design
+
+```lua
+-- claudecode-a2a/init.lua
+local A2A = {
+  -- Agent registry
+  agents = {},
+  
+  -- Message broker
+  broker = nil,
+  
+  -- Protocol handlers
+  protocols = {}
+}
+
+-- Register an agent
+function A2A:register_agent(agent_id, capabilities, endpoint)
+  self.agents[agent_id] = {
+    id = agent_id,
+    capabilities = capabilities,
+    endpoint = endpoint,
+    status = "online"
+  }
+end
+
+-- Send message between agents
+function A2A:send_message(from_agent, to_agent, message)
+  -- Route through broker
+  return self.broker:route(from_agent, to_agent, message)
+end
+```
+
+### Integration with claudecode.nvim
+
+```lua
+-- claudecode.nvim would expose hooks
+local claudecode = require("claudecode")
+
+-- Optional A2A integration
+claudecode.setup({
+  a2a = {
+    enabled = true,
+    library = "claudecode-a2a",
+    
+    -- Callback when A2A message received
+    on_message = function(from_agent, message)
+      -- Forward to Claude via existing WebSocket
+      claudecode.send_to_claude({
+        type = "a2a_message",
+        from = from_agent,
+        content = message
+      })
+    end
+  }
+})
+```
+
+### Message Flow Example
+
+```
+┌─────────────┐     ┌──────────────┐     ┌─────────────┐
+│   Claude    │     │              │     │   Claude    │
+│ Instance 1  │────▶│  A2A Broker  │────▶│ Instance 2  │
+│ (main)      │     │              │     │ (feature)   │
+└─────────────┘     └──────────────┘     └─────────────┘
+      ▲                                          ▲
+      │                                          │
+      │                                          │
+┌─────────────┐                          ┌─────────────┐
+│claudecode.  │                          │claudecode.  │
+│nvim (main)  │                          │nvim (feat)  │
+└─────────────┘                          └─────────────┘
+```
+
+## A2A Protocol Considerations
+
+### 1. Message Types
+```json
+{
+  "id": "msg-123",
+  "type": "request|response|notification|broadcast",
+  "from": "agent-main-worktree",
+  "to": "agent-feature-worktree",
+  "timestamp": 1234567890,
+  "payload": {
+    "action": "share_context",
+    "data": {
+      "files": ["src/main.lua"],
+      "summary": "Refactored the main loop"
+    }
+  }
+}
+```
+
+### 2. Capabilities Discovery
+```json
+{
+  "agent_id": "claude-main-worktree",
+  "capabilities": [
+    "code_analysis",
+    "test_generation",
+    "refactoring"
+  ],
+  "workspace": "/home/user/project",
+  "status": "busy|idle|thinking"
+}
+```
+
+### 3. Coordination Patterns
+- **Request/Response**: Direct agent queries
+- **Pub/Sub**: Broadcast updates to all agents
+- **Task Queue**: Distribute work across agents
+- **Consensus**: Multiple agents verify changes
+
+## Implementation Options
+
+### Option 1: Redis-based Broker
+```lua
+-- Simple, reliable, supports pub/sub
+local redis = require("redis")
+local broker = redis.connect("localhost", 6379)
+
+-- Publish to channel
+broker:publish("a2a:main-to-feature", message)
+```
+
+### Option 2: Built-in Lua Broker
+```lua
+-- No external dependencies
+local broker = {
+  channels = {},
+  
+  subscribe = function(self, channel, callback)
+    self.channels[channel] = self.channels[channel] or {}
+    table.insert(self.channels[channel], callback)
+  end
+}
+```
+
+### Option 3: Unix Domain Sockets
+```lua
+-- Fast, local-only communication
+local socket = vim.loop.new_pipe()
+socket:bind("/tmp/claudecode-a2a.sock")
+```
+
+## Benefits of Separate Library
+
+1. **Independent Development**
+   - A2A protocol can evolve separately
+   - Different release cycles
+   - Specialized maintainers
+
+2. **Flexible Integration**
+   - Other editors can use the A2A library
+   - Works with non-Neovim Claude instances
+   - Can bridge different AI systems
+
+3. **Testing Isolation**
+   - Test A2A logic without editor complexity
+   - Mock agents for testing
+   - Protocol compliance testing
+
+4. **Performance Optimization**
+   - A2A can use optimal transport (gRPC, etc.)
+   - No vim.loop constraints
+   - Can run in separate process
+
+## Example Use Cases
+
+### 1. Coordinated Refactoring
+```lua
+-- Agent 1 identifies refactoring opportunity
+a2a:broadcast({
+  type = "refactor_proposal",
+  changes = "Extract login logic to auth module"
+})
+
+-- Agent 2 analyzes impact
+a2a:respond({
+  type = "impact_analysis",
+  affected_files = 12,
+  test_coverage = "85%"
+})
+```
+
+### 2. Distributed Code Review
+```lua
+-- Multiple agents review different aspects
+agent1: "Security review complete - 2 issues found"
+agent2: "Performance review - suggests caching"
+agent3: "Style review - formatting needed"
+```
+
+### 3. Knowledge Sharing
+```lua
+-- Agent learns something new
+a2a:broadcast({
+  type = "knowledge_update",
+  learning = "Project uses custom error handling pattern"
+})
+```
+
+## Consequences
+
+### Positive
+- ✅ Clean separation of concerns
+- ✅ Reusable across different integrations
+- ✅ Protocol flexibility
+- ✅ Easier testing and maintenance
+- ✅ Can evolve independently
+
+### Negative
+- ❌ Additional dependency for A2A features
+- ❌ More complex deployment
+- ❌ Need to maintain protocol compatibility
+
+## Recommendation
+
+1. **Phase 1**: Complete multi-instance support in claudecode.nvim
+2. **Phase 2**: Design A2A protocol specification
+3. **Phase 3**: Implement claudecode-a2a as separate library
+4. **Phase 4**: Add optional A2A hooks to claudecode.nvim
+
+This approach keeps claudecode.nvim focused on IDE integration while enabling powerful agent coordination through a dedicated library.
\ No newline at end of file
diff --git a/docs/multi-instance-task-plan.md b/docs/multi-instance-task-plan.md
new file mode 100644
index 0000000..40f9fbe
--- /dev/null
+++ b/docs/multi-instance-task-plan.md
@@ -0,0 +1,306 @@
+# Multi-Instance Claude Code Task Plan
+
+## Overview
+Transform the single-instance claudecode.nvim plugin to support multiple concurrent Claude Code instances with different working directories, enabling worktree support and instance switching.
+
+## Time Estimates
+
+### Overall Project Timeline
+- **Total Development Hours**: 120-175 hours
+- **Working Days** (8 hours/day): 15-22 days
+- **Calendar Time**:
+  - **Focused full-time development**: 3-5 weeks
+  - **Part-time development**: 6-10 weeks
+
+### Phase-by-Phase Estimates
+
+| Phase | Description | Raw Hours | With Overhead (30-50%) |
+|-------|-------------|-----------|------------------------|
+| Phase 1 | Core Architecture Refactoring | 14-20 hours | 18-30 hours |
+| Phase 2 | Multi-Port Server Management | 10-13 hours | 13-20 hours |
+| Phase 3 | Terminal Management Enhancement | 14-18 hours | 18-27 hours |
+| Phase 4 | Command System Enhancement | 13-17 hours | 17-26 hours |
+| Phase 5 | UI and Notifications | 9-12 hours | 12-18 hours |
+| Phase 6 | Advanced Features | 15-19 hours | 20-29 hours |
+| Phase 7 | Testing and Documentation | 15-19 hours | 20-29 hours |
+| **Total** | | **90-118 hours** | **120-175 hours** |
+
+### Priority-Based Timeline
+
+#### High Priority (Core Functionality)
+- Phases 1, 2, 4.1-4.2
+- **Estimated time**: 37-50 hours → 5-8 working days
+- **Recommended timeline**: 2 weeks with buffer
+
+#### Medium Priority (Enhanced UX)
+- Phases 3, 5, 6.1
+- **Estimated time**: 28-37 hours → 4-6 working days
+- **Recommended timeline**: 1.5-2 weeks with buffer
+
+#### Low Priority (Nice to Have)
+- Phases 6.2, 6.3, 5.1
+- **Estimated time**: 25-32 hours → 3-5 working days
+- **Recommended timeline**: 1-1.5 weeks with buffer
+
+### Development Recommendations
+
+1. **Staged Deployment**: Implement and deploy high-priority features first to get early feedback
+2. **Buffer Time**: Include 25-35% buffer for unexpected complexity and edge cases
+3. **Parallel Development**: Some phases can be developed in parallel by multiple developers
+4. **Testing Time**: Allocate additional 2-3 weeks for production hardening and edge case handling
+5. **Code Review**: Add 10-15% additional time for thorough code reviews
+
+## Phase 1: Core Architecture Refactoring (Foundation)
+
+### 1.1 Instance Registry Module
+- [ ] Create `lua/claudecode/instance_registry.lua`
+  - [ ] Define instance data structure with fields: `id`, `port`, `cwd`, `name`, `state`, `created_at`
+  - [ ] Implement registry storage using table with instance IDs as keys
+  - [ ] Add methods: `register()`, `unregister()`, `get()`, `get_all()`, `get_active()`
+  - [ ] Add instance lifecycle tracking (starting, running, stopped, error)
+  - [ ] Write unit tests for all registry methods
+
+### 1.2 Instance Manager Module  
+- [ ] Create `lua/claudecode/instance_manager.lua`
+  - [ ] Implement `create_instance(opts)` that returns instance ID
+  - [ ] Implement `destroy_instance(id)` with cleanup
+  - [ ] Add `switch_active_instance(id)` method
+  - [ ] Add `get_instance_by_cwd(cwd)` for worktree detection
+  - [ ] Implement instance state validation
+  - [ ] Write unit tests for instance lifecycle
+
+### 1.3 Refactor Global State
+- [ ] Modify `lua/claudecode/init.lua` to remove singleton `M.state`
+- [ ] Replace with `M.instances = {}` table
+- [ ] Update all state access to use instance-specific state
+- [ ] Add `M.active_instance_id` for tracking current instance
+- [ ] Ensure backward compatibility with single-instance usage
+- [ ] Update all existing tests to work with new structure
+
+## Phase 2: Multi-Port Server Management
+
+### 2.1 Server Factory Pattern
+- [ ] Create `lua/claudecode/server/factory.lua`
+  - [ ] Implement `create_server(instance_id, port)` method
+  - [ ] Add server-to-instance mapping
+  - [ ] Handle port allocation per instance
+  - [ ] Implement server cleanup on instance destruction
+  - [ ] Write tests for concurrent server creation
+
+### 2.2 Port Management Enhancement
+- [ ] Modify `lua/claudecode/server/tcp.lua`
+  - [ ] Add port reservation system to prevent conflicts
+  - [ ] Track used ports across all instances
+  - [ ] Implement `release_port(port)` method
+  - [ ] Add port range partitioning for instances
+  - [ ] Test concurrent port allocation
+
+### 2.3 Lock File Per Instance
+- [ ] Update `lua/claudecode/lockfile.lua`
+  - [ ] Generate unique lock file per instance: `~/.claude/ide/[port]-[instance_id].lock`
+  - [ ] Add instance metadata to lock file content
+  - [ ] Implement lock file cleanup on instance destruction
+  - [ ] Add lock file discovery for existing instances
+  - [ ] Test multiple lock file scenarios
+
+## Phase 3: Terminal Management Enhancement
+
+### 3.1 Multi-Terminal Support
+- [ ] Refactor `lua/claudecode/terminal.lua`
+  - [ ] Remove global terminal state
+  - [ ] Add terminal-to-instance mapping
+  - [ ] Implement `get_terminal_for_instance(id)`
+  - [ ] Update toggle logic to work with active instance
+  - [ ] Preserve terminal state per instance
+
+### 3.2 Terminal Provider Updates
+- [ ] Update `lua/claudecode/terminal/native.lua`
+  - [ ] Support multiple terminal buffers
+  - [ ] Add instance ID to terminal buffer variables
+  - [ ] Implement terminal switching logic
+  - [ ] Handle concurrent terminal operations
+  
+- [ ] Update `lua/claudecode/terminal/snacks.lua`
+  - [ ] Adapt snacks integration for multiple terminals
+  - [ ] Ensure proper terminal identification
+  - [ ] Test with multiple snacks terminals
+
+### 3.3 Window Management
+- [ ] Create `lua/claudecode/windows.lua`
+  - [ ] Implement window layout for multiple instances
+  - [ ] Add tabbed interface option
+  - [ ] Add split window arrangement option
+  - [ ] Implement instance switcher UI
+  - [ ] Handle window cleanup on instance close
+
+## Phase 4: Command System Enhancement
+
+### 4.1 Instance-Aware Commands
+- [ ] Update all existing commands in `lua/claudecode/init.lua`
+  - [ ] Add optional `--instance-id` parameter to all commands
+  - [ ] Default to active instance when no ID specified
+  - [ ] Add instance validation to each command
+  - [ ] Update command completion to suggest instance IDs
+
+### 4.2 New Multi-Instance Commands
+- [ ] Implement `:ClaudeCodeNew [--cwd path] [--name name]`
+  - [ ] Create new instance with specified working directory
+  - [ ] Auto-generate instance name if not provided
+  - [ ] Return instance ID on creation
+  
+- [ ] Implement `:ClaudeCodeList`
+  - [ ] Show all instances with status, port, cwd
+  - [ ] Highlight active instance
+  - [ ] Add instance health indicators
+  
+- [ ] Implement `:ClaudeCodeSwitch <instance-id|name>`
+  - [ ] Switch active instance
+  - [ ] Update UI to reflect switch
+  - [ ] Trigger switch notification
+  
+- [ ] Implement `:ClaudeCodeKill <instance-id|name|all>`
+  - [ ] Gracefully shutdown specified instance(s)
+  - [ ] Clean up all resources
+  - [ ] Handle 'all' keyword for bulk operations
+
+### 4.3 Selection and Context Handling
+- [ ] Update `lua/claudecode/selection.lua`
+  - [ ] Track selections per instance
+  - [ ] Update selection sync to use active instance
+  - [ ] Handle instance switching during selection
+  
+- [ ] Update file sending logic
+  - [ ] Route file additions to correct instance
+  - [ ] Support sending files to specific instance
+  - [ ] Add cross-instance file sharing option
+
+## Phase 5: UI and Notifications
+
+### 5.1 Instance Switcher UI
+- [ ] Create `lua/claudecode/ui/switcher.lua`
+  - [ ] Implement floating window instance picker
+  - [ ] Show instance details (name, cwd, status)
+  - [ ] Add keyboard navigation
+  - [ ] Support mouse clicks
+  - [ ] Add instance preview
+
+### 5.2 Status Line Integration
+- [ ] Create `lua/claudecode/ui/statusline.lua`
+  - [ ] Provide statusline component showing active instance
+  - [ ] Add instance count indicator
+  - [ ] Show instance health status
+  - [ ] Support popular statusline plugins
+
+### 5.3 Notifications System
+- [ ] Enhance `lua/claudecode/logger.lua`
+  - [ ] Add instance-specific notifications
+  - [ ] Implement instance switch notifications
+  - [ ] Add instance error notifications
+  - [ ] Support notification routing to active instance
+
+## Phase 6: Advanced Features
+
+### 6.1 Worktree Integration
+- [ ] Create `lua/claudecode/worktree.lua`
+  - [ ] Auto-detect git worktrees
+  - [ ] Create instance per worktree automatically
+  - [ ] Map worktree to instance
+  - [ ] Handle worktree switching
+  - [ ] Clean up on worktree deletion
+
+### 6.2 Instance Persistence
+- [ ] Create `lua/claudecode/persistence.lua`
+  - [ ] Save instance state to disk
+  - [ ] Restore instances on Neovim restart
+  - [ ] Handle stale instance cleanup
+  - [ ] Implement session management
+
+### 6.3 Network Features
+- [ ] Implement fetch() proxy support
+  - [ ] Add fetch command routing through Claude
+  - [ ] Support both web and intranet (when available)
+  - [ ] Handle CORS and security
+  - [ ] Add request/response logging
+
+## Phase 7: Testing and Documentation
+
+### 7.1 Comprehensive Testing
+- [ ] Update all existing tests for multi-instance
+- [ ] Add integration tests for multiple instances
+- [ ] Test instance switching scenarios
+- [ ] Test resource cleanup
+- [ ] Add stress tests for many instances
+- [ ] Test worktree integration
+
+### 7.2 Documentation Updates
+- [ ] Update README.md with multi-instance usage
+- [ ] Document all new commands
+- [ ] Add multi-instance configuration examples
+- [ ] Create troubleshooting guide
+- [ ] Add architecture diagrams
+
+### 7.3 Migration Guide
+- [ ] Create migration guide for existing users
+- [ ] Document breaking changes
+- [ ] Provide configuration migration tool
+- [ ] Add compatibility layer for old commands
+
+## Success Metrics
+
+### Measurable Outcomes
+1. **Instance Management**
+   - Support minimum 10 concurrent instances
+   - Instance creation time < 500ms
+   - Instance switching time < 100ms
+   - Zero port conflicts in 1000 iterations
+
+2. **Resource Usage**
+   - Memory per instance < 50MB
+   - No memory leaks after 100 create/destroy cycles
+   - Clean process termination 100% of time
+
+3. **User Experience**
+   - All commands respond < 200ms
+   - Status updates within 50ms
+   - Smooth UI transitions
+   - No blocking operations
+
+4. **Compatibility**
+   - 100% backward compatibility for single instance
+   - All existing tests pass
+   - Works with Neovim 0.8+
+   - Works with both terminal providers
+
+## Implementation Priority
+
+1. **High Priority** (Core Functionality)
+   - Phase 1: Architecture Refactoring
+   - Phase 2: Multi-Port Management
+   - Phase 4.1-4.2: Basic Commands
+
+2. **Medium Priority** (Enhanced UX)
+   - Phase 3: Terminal Management
+   - Phase 5: UI and Notifications
+   - Phase 6.1: Worktree Integration
+
+3. **Low Priority** (Nice to Have)
+   - Phase 6.2: Persistence
+   - Phase 6.3: Network Features
+   - Phase 5.1: Advanced UI
+
+## Risk Mitigation
+
+1. **Breaking Changes**
+   - Maintain compatibility layer
+   - Deprecate gradually
+   - Provide migration tools
+
+2. **Performance Impact**
+   - Profile before/after
+   - Lazy load instances
+   - Implement resource limits
+
+3. **Complexity Growth**
+   - Modular architecture
+   - Clear separation of concerns
+   - Comprehensive documentation
\ No newline at end of file
