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
• :ClaudeAgents - Interactive agent manager (switch, diff, kill)
• :ClaudeDiffAgent - Review agent changes with diffview
• :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

Background Agent Features (v1.0 Complete)

Key Improvements

1. Hook Isolation: Background agents always run without hooks (no inline diffs)
2. ClaudeSwitch: Switch to agent's worktree to chat/give follow-ups (hooks remain disabled)
3. ClaudeDiffAgent: Review agent changes using diffview.nvim
4. Progress Tracking: Agents can update progress.txt for real-time status updates
5. Statusline Integration: Shows active agent count and latest progress
6. Enhanced Agent Creation UI: Interactive popup for mission description with fork options

Usage

• ClaudeBg - Opens interactive UI for creating agents with:
  • Multi-line mission description editor
  • Fork options: current branch, main, stash, or any branch
  • Shows what the agent will be based on
• ClaudeBg <task> - Quick creation (backwards compatible)
• ClaudeSwitch [agent] - Switch to agent's worktree to chat (no inline diffs)
• ClaudeDiffAgent [agent] - Review agent changes with diffview
• ClaudeAgents - List all agents with progress
• Agents update progress: echo 'status' > progress.txt

Agent Creation Options

• Fork from current branch: Default, uses your current branch state
• Fork from default branch: Start fresh from your default branch (auto-detects main/master)
• Stash current changes: Creates stash of current work, then applies to agent
• Fork from other branch: Choose any branch to base agent on

Smart Branch Detection

The plugin automatically detects your repository's default branch (main, master, etc.) instead of assuming "main", making it compatible with older repositories that use "master".

Design Philosophy

Background agents are kept simple - they're always background agents with hooks disabled. This avoids complexity around state transitions and keeps the workflow predictable. Use regular :ClaudeChat in your main workspace for inline diff functionality.