Skip to main content
Version: stable

AI agents

Proveasio installs opencode, a terminal AI coding agent, and wires it into the shell, tmux, lazygit and Neovim.

opencode​

Uses: opencode

Start it in a project directory:

cd ~/projects/myproject
opencode

On the first start, connect a model provider with /connect (for example GitHub Copilot, Anthropic or OpenAI). Then type what you want done. Useful commands inside opencode:

  • /models - choose the model
  • Shift+Tab or /agents - switch between agents, for example the build agent (makes changes) and the plan agent (read-only)
  • @ - attach a file to the prompt
  • /new, /sessions - start a new session, or pick one of this directory
  • /undo, /redo - revert or restore the last change
  • Ctrl+p - command palette with every action; type / to list the slash commands

latest installs opencode v2. To stay on v1, see opencode v1 and v2.

Find old sessions with ocs​

opencode lists only the sessions of the current directory. ocs searches the sessions of all directories and reopens the one you pick, see Browse opencode sessions with ocs.

Shared OpenCode config​

Uses: opencode-config

The opencode-config task clones this repository to ~/.local/share/opencode-config and runs its install.sh, which links the shared agents, skills and settings into ~/.config/opencode. It also updates package plugins such as superpowers with opencode plugin update. It runs unless opencode or opencode-config is excluded.

Add things for one machine in ~/.config/opencode itself: AGENTS.md, skills/, plugins/, opencode.local.json, cli.local.json, skill-repos.local.txt. For the layout and the merge rules, see the repository README. To use your own copy, see Own config files.

Update only this part with --tags opencode-config.

Track agents in tmux with ccmux​

ccmux shows which agents in your tmux panes are working, idle or waiting for you, and notifies you when one needs input. <C-b><C-p> (or Alt+p) opens its picker. See Track AI coding agents (ccmux).

Review changes with an agent​

Uses: revdiff, hunk

Two review tools, one for each direction:

  • revdiff: you annotate the diff or plan, and the notes go to opencode, which fixes them.
  • hunk: opencode walks you through its changes and leaves notes next to the code.

Both open as a popup over 90% of the screen, so run opencode inside tmux. revdiff also works in zellij, Kitty, WezTerm and Ghostty, but not in Windows Terminal on its own.

Send your notes with revdiff​

Type /revdiff in opencode:

/revdiff working tree changes
/revdiff HEAD~3 the last three commits
/revdiff --staged staged changes

Annotate lines (a), then quit with q. Your annotations are sent to the session, and the agent works on them. Quitting without annotations sends nothing. /revdiff also works on the opencode home screen; the annotations then start a new session.

/revdiff reviews the session's directory. The playbook sets untracked = true in ~/.config/revdiff/config, so new files the agent created are part of the review, and word-diff = true, which highlights the changed words within a changed line.

When the plan agent finishes a plan, revdiff opens it for review on its own. Annotate it to have the plan revised, or quit without annotations to keep it. This cannot be turned off.

revdiff keeps every review in ~/.config/revdiff/history/. The playbook installs the plugin in ~/.config/opencode/plugins/revdiff/; restart opencode after the first install.

Let the agent walk you through changes with hunk​

The playbook installs the hunk-review skill, which teaches opencode the hunk session commands. Each tmux session has one hunk window:

KeysAction
Alt+h, <C-b>HShow hunk in a popup (starts hunk diff --watch in the current pane's directory unless it already runs), or hide it again
Alt+Shift+hSave your notes, then quit hunk
q in hunkQuit hunk and discard the notes

Hiding keeps hunk running in a hidden tmux session named hunk-<session>, so opencode can still use it. While the popup is open you cannot type in opencode, so:

  1. Press Alt+h to start hunk, then Alt+h again to hide it.
  2. Ask opencode: Use the hunk-review skill to walk me through your changes.
  3. Press Alt+h to read its notes. { and } jump between them; a shows or hides them.

You can write your own notes with c, but opencode does not get them by itself: tell it to read your hunk notes. It reads them with hunk-popup notes. Hide hunk with Alt+h rather than quitting it: Alt+Shift+h saves your notes to ~/.local/state/hunk-popup/ before it quits hunk, where hunk-popup notes still finds them, but q in hunk discards them.

hunk-popup open <dir> [ref] starts hunk in another directory, or with a ref shows the changes since that ref, committed or not. It restarts hunk, so it refuses while you have notes in the old window. Run hunk-popup for the details.

Review changes the agent made in another directory​

Both tools look at one directory: /revdiff at the session's directory, Alt+h at the directory hunk was started in, which is the opencode pane's when the agent did not start it. When the agent works in a worktree or a separate clone, the review-handoff skill from opencode-config has it:

  1. Move the opencode session to that directory, so /revdiff reviews it.
  2. Run hunk-popup open <dir> [ref], so Alt+h shows it.
  3. Tell you the directory, what the diff is against, and the command to use, for example /revdiff develop when the changes are committed on a branch.
  4. Read your hunk notes when you say you are done, then move the session and hunk back to the directory it started from.

When you finish the review with no change requests left, it copies the changes into the checkout they came from, uncommitted, and removes the worktree or clone it created. It does not commit, merge or push unless you ask.

AI commits in lazygit​

In lazygit, Ctrl+a writes a commit message for the staged changes, and Alt+s splits the changes into several commits. See AI commits in lazygit.

AI in Neovim​

The default Neovim config has three AI integrations. All of them need a provider login: opencode its own, CodeCompanion and Copilot a GitHub Copilot subscription (run :Copilot auth once).

opencode.nvim​

Uses: opencode.nvim

opencode runs in a tmux pane next to Neovim (outside tmux, in a Neovim terminal), so ccmux tracks it like any other agent. Neovim sends it prompts with context from the editor.

KeysAction
Ctrl+., <Space>OtShow or hide the opencode pane (starts opencode if needed)
<Space>ONOpen another opencode pane for this project
<Space>OSBrowse the sessions of all directories (ocs) in a floating window and open the one you pick in a new opencode pane
<Space>OaAsk about the code under the cursor (in visual mode: the selection)
<Space>OeExplain the code under the cursor
<Space>O+Start a prompt with the current buffer (in visual mode: the selection) as context
<Space>OsPick a predefined prompt (review, fix diagnostics, document, ...)

The prompts go to the most recent opencode session of Neovim's working directory. opencode asks for permissions in its own pane.

CodeCompanion​

Uses: CodeCompanion

A chat and inline assistant inside Neovim, using GitHub Copilot models.

KeysAction
<Space>AcToggle the chat buffer
<Space>Aa(visual) Add the selection to the chat
<Space>AqInline assistant: describe a change to the buffer or selection
<Space>ApAction palette

Copilot completions​

Uses: copilot.lua, blink-copilot

Copilot suggestions appear in the normal completion menu, next to the language server's.