aiwaku.nvim: Instructions file for GitHub Copilot

Copilot instructions for aiwaku.nvim

Build, test, and lint

This repository does not define dedicated build, test, or lint commands today. There is no Makefile, test directory, CI workflow, or formatter/linter configuration in the repo.

• There is currently no automated full test command.
• There is currently no single-test command.
• There is currently no dedicated lint command.

Runtime requirements still matter for code changes:

• tmux >= 3.0 is required for session persistence and management.
• Neovim >= 0.10 is required by the documented plugin API and runtime usage.

High-level architecture

aiwaku.nvim is a Neovim plugin that runs a user-chosen CLI AI tool inside a tmux session and shows that session in a persistent sidebar terminal.

• lua/aiwaku/init.lua is the public module surface. It re-exports the user API, deep-merges user options with config.defaults, registers configured keymaps, and installs the BufEnter autocmd that re-enters insert mode only for buffers marked with vim.b[bufnr].aiwaku and buftype == "terminal".
• lua/aiwaku/state.lua is the shared runtime singleton. It stores resolved config, the active tmux session name, the visible sidebar window id, cached terminal buffers keyed by session name, and the busy re-entrancy guard.
• lua/aiwaku/session.lua is the lifecycle orchestrator. It owns toggle/create/open/select/rename/clear behavior, decides when to reuse a cached terminal buffer versus creating a new one, and coordinates tmux.lua, window.lua, and terminal.lua. select_session() and rename_session() are plenary.async UI flows; the rest of the session lifecycle is synchronous.
• lua/aiwaku/tmux.lua is the tmux boundary. Keep tmux shelling-out, shell escaping, and session parsing here rather than spreading tmux command construction across other modules.
• lua/aiwaku/window.lua owns sidebar split creation and sets winfixwidth so the sidebar does not get squashed by other splits.
• lua/aiwaku/terminal.lua owns terminal buffer creation and setup. It starts jobs with vim.fn.jobstart(..., { term = true }), stores the job id in vim.b[bufnr].terminal_job_id, marks buffers with vim.b[bufnr].aiwaku = true, applies state.config.terminal_keymaps, disables line numbers, and names buffers as aiwaku://<cmd_basename>-<bufnr>.
• lua/aiwaku/send.lua is the path from visual selections or whole buffers to the running terminal job. It extracts the exact visual range or current buffer, optionally prepends a prompt, ensures the target session exists, auto-opens the sidebar if needed, and sends text over the terminal channel.
• lua/aiwaku/lsp-code-actions.lua is optional null-ls/none-ls integration layered on top of the public require("aiwaku").send_selection() and require("aiwaku").send_buffer() API. It does a guarded pcall(require, "null-ls") at module load time and returns {} when null-ls is unavailable.