agent-term.nvim

At a Glance

The default agent is Codex. Presets are best-effort defaults for common terminal agents; any compatible interactive command can be configured directly.

Why agent-term.nvim?

Most Neovim AI plugins abstract agents behind a shared chat UI. agent-term.nvim takes the opposite approach: it keeps each agent's real terminal interface inside Neovim.

That means Codex, Claude, Gemini, Aider, Copilot, OpenCode, and other terminal agents keep their own slash commands, menus, model switching, permission flows, hooks, highlighting/autocomplete, and session behavior when supported by the agent TUI.

The plugin adds a Neovim bridge around that native UI: persistent per-agent terminal sessions, float/panel views, editor context capture, diagnostics/selection/buffer metadata, keymaps, runtime agent switching, startup/kill helpers, and optional native hook installation.

Requirements

• Neovim 0.12+
• A terminal coding agent installed and authenticated as needed

Install

With lazy.nvim:

{
  "alsi-lawr/agent-term.nvim",
  main = "agent_term",
  keys = {
    { "<leader>co", "<cmd>AgentTermToggle<cr>", desc = "Agent terminal" },
    { "<leader>cp", "<cmd>AgentTermPanelToggle<cr>", desc = "Agent panel" },
    { "<leader>ck", "<cmd>AgentTermKill<cr>", desc = "Agent kill" },
    { "<leader>cb", "<cmd>AgentTermSendBufferContext<cr>", desc = "Agent buffer context" },
    { "<leader>cs", "<cmd>AgentTermSendSelectionContext<cr>", mode = { "n", "x" }, desc = "Agent selection context" },
  },
  opts = {},
}

The keys block above is a lazy.nvim example. Plugin-managed keymaps are disabled by default.

Minimal Configuration

Configure one or more named agents. If no persisted active agent exists, the first configured agent by name is used. The selected agent is remembered globally in Neovim state.

require("agent_term").setup({
  agents = {
    "claude",
    "codex",
    gemini = {
      preset = "gemini",
      cmd = { "gemini" },
    },
    custom = {
      cmd = { "my-agent" },
    },
  },
  keymaps = false,
})

String list entries are shorthand for preset-only agents. The example above creates named claude and codex agents from their presets, while gemini and custom use explicit configuration.

Switch the active agent at runtime without editing config:

:AgentTermSwitch gemini
:AgentTermSwitch codex

:AgentTermSwitch with no arguments prints the current active agent. Completion includes configured agent names only. :AgentTermSwitch! <name> kills and recreates only the target agent session; normal switching never kills unrelated agents.

Per-agent preset, cmd, auto_resume, and context settings are applied when that agent creates its terminal session.

Agent Presets

Presets are convenience defaults, not a guarantee of feature parity across tools. Exact commands and caveats are documented in docs/agents.md.

Preset	Command	Hook installer support	Auto-resume picker	Auto-resume last
codex	codex	paste; native hook install supported	codex resume	codex resume --last
gemini	gemini	paste; native hook install supported	gemini -r	gemini -r latest
claude	claude	paste; native hook install supported	claude --resume	claude --continue
aider	aider	paste	unavailable	aider --restore-chat-history
copilot	copilot	paste	copilot --resume	copilot --continue
opencode	opencode	paste	unavailable	opencode --continue

agents.<name>.auto_resume accepts "picker", "last", false, or nil. The default is unset. When a preset command is overridden, the selected auto-resume arguments are appended to agents.<name>.cmd.

Supported enum values are available at require("agent_term.enums").agent.

Quick Reference

Context Behaviour

Context commands send lightweight editor metadata, not full buffer contents.

• Buffer context sends file path, filetype, cursor, and visible range.
• Selection context sends file path, filetype, and selected line range.
• Diagnostics context sends compact diagnostics for the current buffer.

Automatic Updates (Hook Integration)

When automatic hook updates are enabled (agents.<name>.context.hook.enabled = true), agent-term.nvim updates the hook context file in the background on buffer switch, diagnostics change, or after leaving visual/select mode. It uses a priority system to ensure the most relevant context is always available:

1. Diagnostics: If the buffer has diagnostics, they are sent as the primary context.
2. Selection: If no diagnostics are active but a selection exists, it is prioritized.
3. Buffer: Fallback to standard buffer metadata.

The plugin manages repo-level state in the .agent-term/ directory by default.

Context Transport

Manual context commands always paste context into the running terminal job.

Optional hook integration writes the latest context payload to agents.<name>.context.file_path (default: .agent-term/context.json) for native agent hooks to consume during prompt lifecycle events. Run :AgentTermInstallHooks to install supported native hooks for the active agent.

Hook installation is explicit. Normal setup does not modify project or user agent config files. Codex, Claude, and Gemini support native hook installation. Aider, Copilot, and Opencode stay paste-only unless you explicitly configure a verified native hook integration.

If the active agent is not running, context commands open the configured agents.<name>.context.target_view. The default target reuses an open panel when one exists, otherwise it opens a float.

Common Commands

• :AgentTermToggle: open or hide the default floating view.
• :AgentTermPanelToggle: open or hide the panel view.
• :AgentTermClose: close agent windows while keeping the process alive.
• :AgentTermKill: stop the active agent process, close its windows, delete its terminal buffer, and clear its state.
• :AgentTermSwitch [agent]: show or switch the active agent. Use ! to kill and recreate the target agent session.
• :AgentTermSendBufferContext: send lightweight metadata for the current buffer.
• :AgentTermSendSelectionContext: send lightweight metadata for the selected range.
• :AgentTermSendDiagnosticsContext: send compact diagnostics for the current buffer.
• :AgentTermInstallHooks: install global native hooks for supported agents.
• :AgentTermIgnore: add .agent-term/ to .gitignore (idempotent).

Float-specific commands are also available as :AgentTermFloatOpen, :AgentTermFloatClose, :AgentTermFloatToggle, and :AgentTermFloatFocus. Panel-specific commands use the same pattern with Panel.

Troubleshooting

• Agent command not found: check :echo executable('your-agent-command') or configure agents.<name>.cmd.
• No selection context: reselect text or run :'<,'>AgentTermSendSelectionContext.
• agents.<name>.auto_resume = "picker" or "last" starts known presets with that auto-resume mode. Custom commands start normally because there is no preset behavior to infer.
• To enable automatic native hook updates, install hooks and set agents.<name>.context.hook.enabled = true.

Advanced Docs

• Agent presets: exact preset commands, auto-resume behavior, context modes, and agent caveats.
• Contribution guide: development setup, project layout, agent-change expectations, testing commands, coverage notes, and PR guidance.