kickstart.nvim/tasks.md

Neovim Claude Integration - Task Tracking

Project Overview

Building a Claude Code integration for Neovim that works seamlessly with a tmux-based workflow. The integration will support both interactive Claude sessions and autonomous "background agents" that can work on tasks independently.

Core Principles

• Tmux-first: All Claude interactions happen in tmux panes/windows
• Non-intrusive: Doesn't change existing nvim/tmux workflow
• Git-aware: Leverages git worktrees for safe parallel development
• Observable: Easy to monitor what agents are doing

Feature Breakdown

1. Core Plugin Infrastructure

1.1 Plugin Setup

• Create plugin directory structure (lua/nvim-claude/)
• Set up basic plugin module with setup() function
• Add configuration options table
• Create plugin entry in lua/colinzhao/lazy/claude.lua
• Test: Plugin loads without errors

1.2 Configuration Management

• Define default configuration schema
• Implement config validation
• Support user config overrides
• Add config options for:
  • Tmux pane split direction and size
  • Agent work directory name
  • Git worktree vs full clone preference
  • Auto-gitignore behavior
• Test: Config changes apply correctly

1.3 Utility Functions

• Create tmux interaction module
• Add git operations wrapper (worktree, status, diff)
• Implement filesystem utilities (create dirs, check paths)
• Add logging/debugging functions
• Test: Each utility function in isolation

2. Basic Claude Chat Integration

2.1 Tmux Pane Management

• Function to create new tmux pane
• Function to find existing Claude panes
• Pane naming/identification system
• Handle pane closing/cleanup
• Test: Can spawn and track tmux panes

2.2 Claude Chat Command

• Implement :ClaudeChat command
• Open Claude in configured tmux split
• Reuse existing pane if available
• Pass current file context if requested
• Test: Command opens Claude reliably

2.3 Context Sharing

• :ClaudeSendBuffer - Send current buffer
• :ClaudeSendSelection - Send visual selection
• :ClaudeSendHunk - Send git hunk under cursor
• Add appropriate context headers
• Test: Each send command works correctly

3. Background Agent System

3.1 Agent Work Directory Management

• Create .agent-work/ in project root
• Auto-add to .gitignore if not present
• Generate timestamped subdirectories
• Clean up old agent directories (configurable)
• Test: Directory creation and gitignore updates

3.2 Git Worktree Integration

• Function to create worktree for agent
• Handle worktree naming (avoid conflicts)
• Support fallback to full clone if worktrees unavailable
• Track worktree <-> agent mapping
• Test: Worktree creation and tracking

3.3 Agent Spawning

• Implement :ClaudeBg <task> command
• Create agent work directory
• Set up git worktree
• Spawn tmux window/session for agent
• Initialize Claude with task context
• Create mission log file
• Test: Full agent spawn workflow

3.4 Agent Tracking

• Maintain registry of active agents
• Store agent metadata (task, start time, status)
• Persist registry across nvim sessions
• Auto-detect terminated agents
• Test: Registry operations and persistence

4. Diff Viewing and Review

4.1 Fugitive Integration

• Function to diff agent worktree against main
• :ClaudeDiff [agent] command
• Support for three-way diffs
• Quick diff preview in floating window
• Test: Diff viewing with fugitive

4.2 Alternative Diff Viewers

• Optional diffview.nvim integration
• Built-in diff visualization for quick preview
• Multi-file diff summary
• Test: Each diff viewer works correctly

4.3 Change Review Workflow

• List changed files from agent
• Preview individual file changes
• Cherry-pick specific changes
• Bulk apply agent changes
• Test: Full review workflow

5. Telescope Integration

5.1 Agent Browser

• Custom Telescope picker for agents
• Show agent status, task, runtime
• Preview agent mission log
• Actions: open, diff, terminate
• Test: Telescope picker functionality

5.2 Agent Work Browser

• Browse files in agent worktrees
• Quick diff against main branch
• Open files from agent in main nvim
• Test: File browsing and operations

6. Status and Monitoring

6.1 Status Line Integration

• Component showing active agent count
• Quick status of current agent
• Click to open agent picker
• Test: Status line updates correctly

6.2 Mission Logs

• Structured log format for agents
• Log Claude interactions
• Track file changes
• Command history
• Test: Logging functionality

6.3 Notifications

• Agent completion notifications
• Error/failure alerts
• Optional progress notifications
• Test: Notification system

7. Safety and Convenience Features

7.1 Snapshot System

• Auto-snapshot before applying changes
• Named snapshots for important states
• Snapshot browser/restore
• Test: Snapshot and restore

7.2 Quick Commands

• :ClaudeKill [agent] - Terminate agent
• :ClaudeClean - Clean up old agents
• :ClaudeSwitch [agent] - Switch to agent tmux
• Test: Each command functions correctly

7.3 Keybindings

• Default keybinding set
• Which-key integration
• User-customizable bindings
• Test: Keybindings work as expected

8. Advanced Features (Phase 2)

8.1 Agent Templates

• Predefined agent configurations
• Task-specific prompts
• Custom agent behaviors
• Test: Template system

8.2 Multi-Agent Coordination

• Agent communication system
• Shared context between agents
• Agent task dependencies
• Test: Multi-agent scenarios

8.3 Integration with Other Plugins

• Harpoon-style agent switching
• Trouble.nvim for agent issues
• Oil.nvim for agent file management
• Test: Each integration

Implementation Phases

Phase 1: MVP (Week 1-2)

1. Core infrastructure (1.1-1.3)
2. Basic Claude chat (2.1-2.3)
3. Simple agent spawning (3.1-3.3)
4. Basic diff viewing (4.1)

Phase 2: Core Features (Week 3-4)

1. Agent tracking (3.4)
2. Full diff/review workflow (4.2-4.3)
3. Telescope integration (5.1-5.2)
4. Basic monitoring (6.1-6.2)

Phase 3: Polish (Week 5-6)

1. Safety features (7.1-7.2)
2. Keybindings and UX (7.3)
3. Notifications (6.3)
4. Documentation and tests

Phase 4: Advanced (Future)

1. Agent templates (8.1)
2. Multi-agent features (8.2)
3. Deep plugin integrations (8.3)

Technical Decisions

Git Strategy

• Primary: Git worktrees for speed and efficiency
• Fallback: Full clones for compatibility
• Safety: Never modify main working directory

Tmux Integration

• Use tmux send-keys for Claude interaction
• Session/window naming for organization
• Preserve user's tmux workflow

State Management

• Agent registry in ~/.local/share/nvim/claude-agents/
• Per-project state in .agent-work/.state/
• JSON for serialization

Error Handling

• Graceful degradation (worktree → clone)
• Clear error messages
• Recovery procedures for common issues

Success Metrics

• Can spawn background agent in < 3 seconds
• Agent changes reviewable in < 5 keystrokes
• Zero interference with normal nvim workflow
• Works on macOS and Linux
• Clear documentation for all features

Next Steps

1. Review and refine task list
2. Set up development environment
3. Create plugin skeleton
4. Begin Phase 1 implementation

---

Last Updated: [Current Date] Status: Planning Phase