Vigent

A lightweight terminal AI agent using Neovim as the frontend.

Status: Work in progress

Features

• Neovim-based UI with split layout
• Session management (auto-save, load, search)
• Multiple LLM providers (OpenAI, Ollama, etc.)
• Agent system with customizable system prompts
• Subagent delegation for specialized tasks
• Tool system (shell exec, file read/write, find, delegate)
• MCP support for extensibility
• Permission prompts for sensitive operations
• Custom commands (prompts and Lua actions)
• Visual selection to link/code block
• Statusline integration
• Automatic retry with exponential backoff for API errors

Requirements

• Neovim 0.9+ (recommended: NvChad, LazyVim, or similar distribution)
• Go 1.24+

Getting Started

1. Build

make build

This builds both bin/vig and bin/vig-server.

2. Run

./bin/vig

Or use make run to build and run in one step.

3. Configure

Create a config file at ~/.config/vig/config.yaml (global) or ./.vig.yaml (project):

models:
  - name: gpt-4
    provider: openai
    model: gpt-4
    api_key: $OPENAI_API_KEY
    default: true

  - name: ollama
    provider: ollama
    model: llama3.2
    base_url: http://localhost:11434

  - name: local
    provider: openai
    model: local-model
    base_url: http://localhost:1234/v1

default_agent: coding

permissions:
  sandbox:
    paths:
      - "."
    auto_deny_outside: true
    deny_patterns:
      - "**/.env"
      - "**/.env.*"
      - "**/id_rsa"
      - "**/.ssh/**"
    deny_exec:
      - ssh
      - scp
  require_approval:
    - write
    - exec

Keybindings

All keybindings are configurable in your config file:

keybindings:
  send: "<S-CR>"           # Send message
  interrupt: "<C-S-x>"     # Interrupt agent
  dequeue: "<C-S-z>"       # Dequeue pending message
  session: "<leader>gs"    # List sessions
  model: "<leader>gm"      # Select model
  agent: "<leader>ga"      # Select agent
  command: "<leader>gc"    # Command palette
  confirm_accept: "<leader>a"   # Accept permission (fallback)
  confirm_decline: "<leader>x"  # Decline permission (fallback)
  enter: "<CR>"            # Confirm/submit
  visual_link: "<C-g>"     # Link visual selection
  visual_link_code: "<C-S-g>"   # Link with code block
  toggle: "<C-\\"          # Toggle focus between vig and main buffer
  toggle_panel: "<C-S-\\"  # Show/hide vig panel

Default Keybindings

Key	Mode	Action
Shift+Enter	Insert	Send message
Ctrl+Shift+X	Insert/Normal	Interrupt agent
Ctrl+Shift+Z	Insert/Normal	Dequeue pending message
Enter	Normal	Follow file link
Ctrl+\	Normal/Insert/Visual	Toggle between vig and main buffer
Ctrl+Shift+\	Normal/Insert	Show/hide vig panel
Leader+gs	Normal	List sessions
Leader+gm	Normal	Select model
Leader+ga	Normal	Select agent
Leader+gc	Normal	Command palette
Ctrl+G	Visual	Insert file link
Ctrl+Shift+G	Visual	Insert file link with code block

Permission Dialog Keybindings

When a permission prompt appears:

Key	Action
Enter or a	Accept (allow once)
A (Shift+a)	Accept All (allow for entire session)
Esc or c or q	Cancel (deny)

Commands

Access command palette with <leader>gc or run directly:

Command	Description
:Vig	Command palette
:VigSession	List sessions for current directory
:VigSessionSearch [query]	Search all sessions
:VigSessionNew	Start fresh session
:VigModel	Select model
:VigAgent	Select agent
:VigPanel	Toggle vig panel (show/hide)
:VigPanelShow	Show vig panel (reopen if closed)
:VigPanelHide	Hide vig panel

Layout

┌─────────────────────┬─────────────────────┐
│                     │  Output buffer      │
│   Main buffer       │  (readonly, chat)   │
│   (open files)      │                     │
│                     ├─────────────────────┤
│                     │  Input buffer       │
└─────────────────────┴─────────────────────┘

Panel Management

If you accidentally close the input or output window, you can:

1. Press Ctrl+Shift+\ to toggle the panel back
2. Run :VigPanelShow to reopen the panel
3. Run :VigPanel to toggle visibility

Agents

Agents are specialized AI assistants with custom system prompts and settings.

Defining Agents

Agents can be defined in three ways:

1. YAML Config

Define agents in .vig.yaml or ~/.config/vig/config.yaml:

agents:
  reviewer:
    name: "Code Reviewer"
    description: "Reviews code for quality"
    model: gpt-4
    temperature: 0.3
    mode: subagent
    hidden: true
    system_prompt: |
      You are a code reviewer...

2. Markdown Files

Create .md files in .agents/ directories:

Global: ~/.config/vig/.agents/reviewer.md Project: <project>/.agents/reviewer.md

---
name: Code Reviewer
description: Reviews code for quality and security
mode: subagent
temperature: 0.1
hidden: true
---

You are a code reviewer. Focus on:
- Security vulnerabilities
- Code quality
- Best practices

The filename (without .md) becomes the agent ID.

3. Rules (AGENTS.md)

Global and project AGENTS.md files contain rules that are prepended to all agent system prompts:

• Global: ~/.config/vig/AGENTS.md
• Project: <project>/AGENTS.md

Both are merged (global first, then project).

Agent Options

Option	Description
name	Display name
description	When to use this agent (required for picker)
system_prompt	System prompt text
model	Override default model
temperature	Randomness (0.0-1.0)
top_p	Alternative to temperature
mode	primary (shown in picker) or subagent (delegation only)
hidden	Hide from UI (for system agents)
disabled	Disable the agent
max_tokens	Max response tokens
rules	List of rule files to include (default: ["AGENTS.md"])
permissions	Per-agent permission overrides

Built-in Agents

ID	Mode	Hidden	Description
coding	primary	false	General coding assistant for implementing features and fixing bugs
planning	primary	false	Analyzes requirements and creates detailed implementation plans
explorer	primary	false	Explores and explains how features are implemented in the codebase
reviewer	subagent	false	Reviews code for quality, security, and best practices
title	subagent	true	Generates concise session titles
summary	subagent	true	Compacts long context into concise summaries
story	subagent	true	Creates detailed narrative summaries of conversation history

Agent Usage

Primary agents are selectable via :VigAgent or <leader>ga:

• coding - Use for implementing features, fixing bugs, refactoring
• planning - Use before coding to create detailed implementation plans
• explorer - Use to understand how existing code works

Subagents are invoked via the delegate tool:

delegate(agent="reviewer", task="Review the changes in src/auth.go")
delegate(agent="story", task="Summarize this conversation")

Agent Loading Order

Agents are loaded in this order (later overrides earlier):

1. Built-in defaults (embedded in binary)
2. Global YAML config
3. Global .agents/*.md
4. Project YAML config
5. Project .agents/*.md

Permissions

Permission Model

Tool Permission Rules:
├── read
│   ├── Inside sandbox: Auto-allow
│   └── Outside sandbox: Require approval (or deny if auto_deny_outside)
├── write
│   ├── Inside sandbox: Require approval
│   └── Outside sandbox: Deny (or require approval)
├── exec
│   ├── In deny_exec list: Deny
│   └── Otherwise: Require approval
└── find
    └── Auto-allow (read-only)

Sandbox Configuration

Sandbox paths define where operations are allowed:

permissions:
  sandbox:
    paths:                    # Auto-allow these paths
      - "."
      - "/workspace/project"
    auto_deny_outside: true   # Deny operations outside sandbox
    deny_patterns:            # Glob patterns to always deny
      - "**/.env"
      - "**/.env.*"
      - "**/id_rsa"
      - "**/.ssh/**"
    deny_exec:                # Commands to always deny
      - ssh
      - scp

Confirmation Dialog

When a tool requires approval:

1. Agent pauses execution
2. Floating dialog appears showing tool name and path
3. User can accept, accept all, or cancel
4. Agent resumes or reports error based on response

Session Storage

Sessions are stored in ~/.local/share/vig/sessions/ as JSON files.

Session format:

{
  "id": "a1b2c3d4",
  "name": "First user message (capped at 50 chars)",
  "directory": "/Users/user/Projects/myapp",
  "agent_id": "coding",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T11:45:00Z",
  "messages": [
    {"role": "user", "content": "..."},
    {"role": "assistant", "content": "..."}
  ],
  "awaiting_input": {
    "permission_id": "tool_123_0",
    "tool_call_id": "call_abc",
    "tool_name": "write",
    "tool_input": {"path": "file.txt", "content": "..."}
  }
}

Tools

Tool	Description	Approval Required
read	Read file with pagination (offset/limit)	Only outside sandbox
write	Write to file (must read first)	Yes
exec	Execute shell command	Yes
find	Find files by glob pattern	No
delegate	Spawn a sub-agent for a specific task	No
delegate_message	Send follow-up message to sub-agent	No

Read tool features:

• offset - Start line (1-indexed)
• limit - Max lines (default 2000)
• Lines truncated at 2000 chars
• Line numbers prefixed: 1: content

Write tool integrity:

• Must read file before writing
• Checks file wasn't modified externally since last read
• Updates read time after successful write

Subagent Tools

The delegate tool allows agents to spawn sub-agents for specialized tasks:

delegate(agent="reviewer", task="Review the changes in src/auth.go", context="...")

Parameters:

• agent (optional) - Agent ID to use, defaults to current agent
• task (required) - Task description for the sub-agent
• context (optional) - Additional context from parent session

Returns:

• session_id - ID of the sub-agent session
• status - "completed", "error", or "cancelled"
• response - Final response from sub-agent

The delegate_message tool sends follow-up messages to a sub-agent:

delegate_message(session_id="abc123", message="Focus on security issues")

Sub-agents inherit permissions from their parent agent and run synchronously (blocking until completion).

Building

make build       # Build both vig and vig-server
make build-vig   # Build vig only
make run         # Build and run vig
make test        # Run tests
make install     # Install to ~/.local/bin/

Logs

• Go backend: /tmp/vig.log
• Lua frontend: /tmp/vig_lua.log