*vibing.txt*  Claude AI integration for Neovim

==============================================================================
CONTENTS                                                     *vibing-contents*

    1. Introduction ............................ |vibing-introduction|
    2. Requirements ............................ |vibing-requirements|
    3. Installation ............................ |vibing-installation|
    4. Configuration ........................... |vibing-configuration|
    5. Commands ................................ |vibing-commands|
    6. Chat Commands ........................... |vibing-chat-commands|
    7. Inline Actions .......................... |vibing-inline-actions|
    8. Mappings ................................ |vibing-mappings|
    9. API ..................................... |vibing-api|
   10. Adapters ................................ |vibing-adapters|
   11. Troubleshooting ......................... |vibing-troubleshooting|
   12. License ................................. |vibing-license|

==============================================================================
1. INTRODUCTION                                          *vibing-introduction*

vibing.nvim is a Neovim plugin that integrates Claude AI through the Agent
SDK, providing intelligent chat and inline code actions directly within your
editor.

Features:~
  • Interactive chat window with Claude AI
  • Quick inline code actions (fix, explain, refactor, test)
  • Natural language instructions for code transformations
  • Session persistence with context management
  • Configurable permissions and execution modes
  • Remote Neovim control via socket

==============================================================================
2. REQUIREMENTS                                          *vibing-requirements*

• Neovim >= 0.8.0
• Node.js >= 16.0.0
• npm or yarn
• Claude API access (via Agent SDK)

==============================================================================
3. INSTALLATION                                          *vibing-installation*

Using lazy.nvim: >lua
    {
      "shabaraba/vibing.nvim",
      build = "npm install",
      config = function()
        require("vibing").setup()
      end,
    }
<

Using packer.nvim: >lua
    use {
      "shabaraba/vibing.nvim",
      run = "npm install",
      config = function()
        require("vibing").setup()
      end,
    }
<

==============================================================================
4. CONFIGURATION                                        *vibing-configuration*

Default configuration: >lua
    require("vibing").setup({
      adapter = "agent_sdk",  -- "agent_sdk" | "claude" | "claude_acp"
      chat = {
        window = {
          position = "right",  -- "right" | "left" | "float"
          width = 0.4,
          border = "rounded",
        },
        auto_context = true,
        save_location_type = "project",  -- "project" | "user" | "custom"
        context_position = "append",  -- "prepend" | "append"
      },
      agent = {
        default_mode = "code",  -- "code" | "plan" | "explore"
        default_model = "sonnet",  -- "sonnet" | "opus" | "haiku"
      },
      permissions = {
        allow = { "Read", "Edit", "Write", "Glob", "Grep" },
        deny = { "Bash" },
      },
      keymaps = {
        send = "<CR>",
        cancel = "<C-c>",
        add_context = "<C-a>",
      },
    })
<

Configuration options:~

adapter                 Which backend to use for Claude AI
chat.window.position    Where to open chat window
chat.window.width       Chat window width (0.0-1.0 or absolute)
chat.window.border      Window border style
chat.auto_context       Automatically add open buffers to context
chat.save_location_type Where to save chat files
chat.context_position   Where to place context in prompt
agent.default_mode      Default execution mode
agent.default_model     Default AI model to use
permissions.allow       Tools AI can use
permissions.deny        Tools AI cannot use
keymaps.send           Key to send message in chat
keymaps.cancel         Key to cancel current request
keymaps.add_context    Key to add file to context

==============================================================================
5. COMMANDS                                                  *vibing-commands*

                                                              *:VibingChat*
:VibingChat
    Open the chat window.

                                                           *:VibingContext*
:VibingContext [path]
    Add file to context. If no path provided, adds current buffer.

                                                      *:VibingClearContext*
:VibingClearContext
    Clear all context files.

                                                            *:VibingInline*
:VibingInline [action|instruction]
    Run predefined action or custom instruction on visual selection.
    Actions: fix, feat, explain, refactor, test
    Or use natural language: "Convert to TypeScript"

                                                           *:VibingExplain*
:VibingExplain
    Explain selected code.

                                                               *:VibingFix*
:VibingFix
    Fix issues in selected code.

                                                           *:VibingFeature*
:VibingFeature
    Implement a feature in selected code.

                                                          *:VibingRefactor*
:VibingRefactor
    Refactor selected code.

                                                              *:VibingTest*
:VibingTest
    Generate tests for selected code.

                                                            *:VibingCustom*
:VibingCustom <instruction>
    Execute custom natural language instruction on selected code.
    Example: >
    :'<,'>VibingCustom "Add error handling"
<

                                                            *:VibingCancel*
:VibingCancel
    Cancel the current AI request.

==============================================================================
6. CHAT COMMANDS                                        *vibing-chat-commands*

These commands are available within the chat buffer:

/context <file>         Add file to context
/clear                  Clear context
/save                   Save current chat
/summarize              Summarize conversation
/mode <mode>            Set execution mode (auto/plan/code)
/model <model>          Set AI model (opus/sonnet/haiku)

==============================================================================
7. INLINE ACTIONS                                      *vibing-inline-actions*

Predefined actions:~
>
    :'<,'>VibingInline fix       " Fix code issues
    :'<,'>VibingInline feat      " Implement feature
    :'<,'>VibingInline explain   " Explain code
    :'<,'>VibingInline refactor  " Refactor code
    :'<,'>VibingInline test      " Generate tests
<

Natural language instructions:~
>
    :'<,'>VibingInline "Convert this to async/await"
    :'<,'>VibingInline "Add comprehensive error handling"
    :'<,'>VibingCustom "Optimize for performance"
<

==============================================================================
8. MAPPINGS                                                  *vibing-mappings*

Default keymaps in chat buffer:~

<CR>        Send message
<C-c>       Cancel current request
<C-a>       Add current file to context

You can customize these in setup(): >lua
    require("vibing").setup({
      keymaps = {
        send = "<C-CR>",
        cancel = "<Esc>",
        add_context = "<C-f>",
      },
    })
<

==============================================================================
9. API                                                              *vibing-api*

For detailed API documentation, see: doc/api-reference.md

Core functions:~

require("vibing").setup({opts})                              *vibing.setup()*
    Initialize the plugin
    Parameters:~
        {opts} Configuration table (optional)

require("vibing").get_adapter()                        *vibing.get_adapter()*
    Get current adapter instance
    Returns:~
        Adapter instance or nil

require("vibing").get_config()                          *vibing.get_config()*
    Get current configuration
    Returns:~
        Configuration table

==============================================================================
10. ADAPTERS                                                    *vibing-adapters*

agent_sdk                                                      *vibing-agent_sdk*
    Claude Agent SDK adapter (recommended)
    Features:~
        • Streaming responses
        • Tool usage support
        • Model selection
        • Context management
        • Session persistence

    Requirements:~
        • Node.js >= 18
        • npm install (run automatically)

    Configuration:~
>lua
        require("vibing").setup({
          adapter = "agent_sdk",
          agent = {
            mode = "command",
            model = "claude-sonnet-4-5",
          },
        })
<

claude                                                              *vibing-claude*
    Official Claude CLI adapter
    Features:~
        • Streaming responses
        • Tool usage support
        • Model selection
        • Context management

    Requirements:~
        • Claude Code CLI installed

    Configuration:~
>lua
        require("vibing").setup({
          adapter = "claude",
          cli_path = "claude",
        })
<

claude_acp                                                        *vibing-claude_acp*
    Claude ACP (Agent Communication Protocol) adapter
    Features:~
        • Streaming responses
        • Tool usage support
        • Context management
        • Session persistence

    Requirements:~
        • claude-code-acp installed

    Configuration:~
>lua
        require("vibing").setup({
          adapter = "claude_acp",
        })
<

==============================================================================
11. TROUBLESHOOTING                                      *vibing-troubleshooting*

Chat not responding:~
    1. Check Claude CLI installation: >
        $ claude --version
<
    2. Verify API key is configured
    3. Check network connection
    4. View error messages: >
        :messages
<

Adapter not found error:~
    Error: Adapter 'agent_sdk' not found

    Solution:~
        • Ensure Node.js is installed (>= 18)
        • Run npm install in plugin directory
        • Try different adapter: >lua
            require("vibing").setup({ adapter = "claude" })
<

Performance issues:~
    • Disable auto_context if not needed
    • Close unused buffers to reduce context
    • Use smaller context when possible
    • Consider using "command" mode instead of "agentic"

Session persistence not working:~
    • Check save location configuration
    • Ensure directory exists and is writable
    • Verify frontmatter format in chat file

Enable debug logging:~
>lua
    vim.g.vibing_debug = true
<

Report issues:~
    https://github.com/shabaraba/vibing.nvim/issues

Include in bug reports:~
    • Neovim version (`:version`)
    • Plugin configuration
    • Error messages (`:messages`)
    • Steps to reproduce

==============================================================================
12. LICENSE                                                    *vibing-license*

MIT License

Copyright (c) 2025 shabaraba

==============================================================================
vim:tw=78:ts=8:ft=help:norl:
