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 (vim.notify)
• 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. Inline Diff System (NEW - Major Feature)

4.1 Claude Code Hooks Integration

• Pre-tool-use hook for baseline creation
• Post-tool-use hook for diff detection
• Automatic inline diff display for open buffers
• Claude file edit tracking
• Git stash-based baseline management

4.2 Inline Diff Display

• Real-time diff visualization in buffers
• Syntax highlighting for additions/deletions
• Virtual text for removed lines
• Hunk navigation (]h, [h)
• Multi-file diff tracking

4.3 Diff Actions

• Accept hunk (ia)
• Reject hunk (ir)
• Accept all hunks (iA)
• Reject all hunks (iR)
• Close inline diff (iq)

4.4 Multi-File Navigation

• Navigate between files with diffs (]f, [f)
• List all files with diffs (ci)
• Telescope-like file picker
• Show diff status for unopened files
• Auto-show diffs when opening Claude-edited files

4.5 Persistence and State

• Save diff state across Neovim sessions
• Restore inline diffs on startup
• Track baseline references
• Clean state management

5. Diff Viewing and Review (Original git-based)

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

6. 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

7. 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

8. Safety and Convenience Features

8.1 Snapshot System

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

8.2 Quick Commands

• :ClaudeKill [agent] - Terminate agent
• :ClaudeClean - Clean up old agents
• :ClaudeSwitch [agent] - Switch to agent tmux
• :ClaudeAgents - List all agents
• :ClaudeResetBaseline - Reset inline diff baseline
• Test: Each command functions correctly

7.3 Keybindings

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

9. 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 Status

Completed Features

1. ✅ Core infrastructure - Plugin setup, config, utilities
2. ✅ Claude chat integration - All context sharing commands working
3. ✅ Background agent system - Full implementation with registry
4. ✅ Inline diff system - Major feature addition with full accept/reject workflow
5. ✅ Multi-file diff navigation - Complete with keybindings
6. ✅ Claude Code hooks - Automatic diff detection and display
7. ✅ Persistence - Diff state saved across sessions

In Progress

1. 🔄 Telescope integration for agents
2. 🔄 Status line integration
3. 🔄 Advanced diff viewing (git-based)

Future Work

1. 📋 Agent templates and behaviors
2. 📋 Multi-agent coordination
3. 📋 Deep plugin integrations
4. 📋 Snapshot system

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: 2025-01-10 Status: Feature Complete for v1.0

Recent Accomplishments

Inline Diff System (Major Feature)

• Complete implementation of inline diff visualization
• Real-time accept/reject functionality for individual hunks
• Multi-file navigation and management
• Persistence across Neovim sessions
• Integration with Claude Code hooks for automatic detection

Background Agents

• Full agent spawning and management system
• Git worktree integration
• Agent registry with persistence
• Mission logging and tracking

Next Steps for v1.1

• Polish Telescope integration for agent browsing
• Add status line components showing active diffs
• Improve documentation with examples
• Create demo videos showcasing inline diff system
• Add support for partial hunk acceptance
• TEST EDIT: Testing single file edit after accept all