Skip to content

getting-started.md

Latest commit

 

History

History
106 lines (79 loc) · 4.78 KB

getting-started.md

File metadata and controls

106 lines (79 loc) · 4.78 KB
Raw

Getting started

From nothing to your first session in about five minutes. Each step links to the page with the details. To have your AI coding agent do the setup, point it at INSTALL.md. For the same steps as a tutorial, with pictures of what you should see, read the first ten minutes.

What you need

  • Node.js 22.19 or newer, and Neovim 0.11 or newer.
  • A model: a local OpenAI-compatible server (llama.cpp, Ollama, vLLM, LM Studio), an API key for a provider, or a subscription login where the provider allows it (Models and providers).
  • Optional: herdr (the older herdr, or herdr-core with the Herdr window), or Rex for a chat split and watched terminals. Without either, everything runs inside Neovim and tmux (Workflows).
  • For Scout: bash and ripgrep (rg); bubblewrap (bwrap) if you want its commands in a sandbox.

1. Install the daemon

npm install -g github:makefunstuff/pairing-buddy   # puts `pair` on your PATH
pair setup

pair setup writes a commented config to ~/.config/pairing-buddy/config.json, offers a login to a model provider (Enter skips it), installs the daemon as a user service that starts at login (systemd or launchd), starts it, and prints the next steps. Without systemd or launchd, pair starts the daemon itself (install.md).

2. Add the Neovim plugin

With lazy.nvim:

{
  'makefunstuff/pairing-buddy',
  dependencies = {'makefunstuff/semantic-grep.nvim'}, -- its picker for search by meaning (Alt-s)
  main = 'pair',
  lazy = false,
  opts = {auto_connect = true},
}

With auto_connect, every Neovim connects to the daemon at startup. All options are in the Neovim plugin reference.

3. Set your model

Open ~/.config/pairing-buddy/config.json and set one model for both roles:

{
  "level": "normal",
  // A local OpenAI-compatible server...
  "model": {"api": "openai", "baseUrl": "http://localhost:8080/v1", "model": "your-model"}
  // ...or a provider you logged in to with `pair auth login PROVIDER`:
  // "model": {"provider": "openai", "model": "your-cloud-model"}
}

The daemon takes the change as you save; no restart. Two models, logins and keys are in Models and providers; every field is in the configuration reference.

4. Check it

pair doctor

One line per part (config, service, daemon, plugin, Neovim, herdr, Pair's panel in the Herdr window, the board, logins and keys, Pair's pane, voice, search by meaning and its reranker, the models and the decision model), each with the fix when something is wrong. See Troubleshooting for what each line means.

Optional: add the shell hook to your shell's rc file, so Pair gets every command you run in your terminals with its exit code from the shell itself, and in zsh your typing at the prompt too (pair shell-hook):

eval "$(pair shell-hook bash)"   # or zsh
pair shell-hook fish | source    # fish, in config.fish

5. Pair

Open Neovim in your project. In herdr or a Rex terminal, run pair beside it: a narrow chat pane opens on the right. Without either, run :Pair chat in Neovim, or skip the chat: a Neovim alone is a whole session. In the chat, type a question and Enter; / lists the commands, ? the keys, and the row above the input says what Pair is doing.

The chat pane on the right of Neovim, before anything is said: what Pair is and the keys to talk to it

The session takes its goal from the work board's (Shepherdr's) task for your branch, or from the branch name, and asks in the chat only when there is neither (on main, say); :Pair goal <what> sets it from Neovim. Then work as usual. Pair stays quiet until something is worth a word, and shows it under your line:

  • Alt-j goes where Pair points; Ctrl-O comes back.
  • Alt-y takes a suggested change.
  • Alt-u / Alt-n tell Pair a remark was useful or noise, and tune when it talks.
  • :Pair ask <question> asks something; :Pair drive <what> hands over the keyboard for one change.

The session ends by itself after 45 minutes without you, or a minute after its last Neovim and chat pane closed, with a short note the next session starts from. :Pair end ends it at once, with a debrief.

Next