agent-watch-nvim: An AI Agent Workflow Management Plugin for Neovim

This article introduces the Neovim plugin agent-watch-nvim, which provides developers with the ability to manage multiple AI programming assistants (such as Codex, Claude) within the editor without leaving the Vim environment. Its core is the integration of the agent-watch CLI, supporting the launching, monitoring, and switching of Agent instances. It adapts to the habits of senior Vim users and fills the gap in AI Agent management in the Neovim ecosystem.

agent-watch-nvim is a Neovim frontend plugin for the agent-watch CLI, relying on the agent-watchd daemon to manage state. It solves the pain point where developers have to leave the editor to switch between multiple AI Agents, following the editor-centric design philosophy—similar to the relationship between Tmux and status bar plugins: the CLI handles core functions, while the plugin is responsible for interactive display.

The plugin provides various commands:

• AgentWatch: Open/refresh the bottom buffer to display all Agent lists (status, title, working directory);
• AgentWatchToggle: Toggle the visibility of the monitoring window;
• AgentWatchToggleLatest: Quickly switch to the most recently used Agent terminal;
• AgentWatchLaunch: Launch a specified Agent (codex, claude, etc.);
• AgentWatchLaunchWorktree: Create a Git worktree and launch an Agent;
• AgentWatchAttachWorktree: Launch an Agent in an existing worktree;
• AgentWatchRename: Rename an Agent.

Vim-style shortcuts are supported within the AgentWatch buffer:

• Enter: Jump to the selected Agent terminal;
• a: Enter title and type to launch a new Agent;
• w: Launch the default Agent in a Git worktree;
• r: Rename the selected Agent;
• t: Open the worktree of the selected Agent;
• dd: Force delete the Agent terminal;
• dw: Delete the Agent's Git worktree;
• q: Close the monitoring window;
• ?: Toggle the help window. Global default shortcut: Press Ctrl+\ twice to switch to the most recent Agent terminal (available in normal/terminal mode).

The plugin is configured via Lua, allowing customization of:

• CLI command name, agent-watchd URL;
• Default Agent, list of available Agents;
• Monitoring window height, fixed height (yes/no), refresh interval;
• Shortcut key mappings;
• Terminal layout (floating window, side split, new tab): Side layout can configure position/width, floating layout can configure size ratio.

Applicable Scenarios:

1. Multi-task parallelism: Launch Agents for feature development, refactoring, and documentation writing respectively;
2. Multi-branch development: Isolate Agent instances with Git worktree to avoid context confusion;
3. Vim closed-loop operation: No need to switch terminals, maintaining an in-editor workflow.

Technical Features:

• Layered design: Dependent on external CLI, making plugin code concise;
• Vim-native: Follows Vim conventions, low learning curve;
• Highly configurable: Adapts to different workflow preferences.

Usage Suggestions:

• Set descriptive titles for Agents;
• Delete unused Agents and worktrees in a timely manner;
• Adjust shortcuts to personal habits;
• Choose floating/side layout based on screen size.

Summary: agent-watch-nvim fills the gap in AI Agent management in the Neovim ecosystem, providing an efficient native interface for the existing CLI. It is a workflow enhancement tool for Neovim + AI assistant users.