Pairwit

Pairwit

User guide

Section by section — how the desk is laid out, how to resize panes, chat, edit, approve, and keep sessions. Theme and fonts match the TUI (locked).

1. Getting started

  1. Install and launch from your project root: 
    pip install pairwit && pairwit
  2. Put a provider key in .env (project) or ~/.pairwit/.env (global). Moonshot default: MOONSHOT_API_KEY.
  3. Optional: /init scaffolds .pairwit.md — project notes injected into every session. /reload-context re-reads it.

2. The desk

Pairwit is a three-zone terminal desk, not a browser IDE. Top to bottom / left to right:

  • Header — product title, model · provider, menu, Files / Editor toggles, and a live stats strip (tokens, cost, turns, open file).
  • Files pane (optional) — project tree. Toggle with header Files or Ctrl+B.
  • Chat — transcript, tool cards, prompt. Always the main column.
  • Editor pane (optional) — tabs, syntax-highlighted buffers, find. Open a file from the tree, then use header Editor or Ctrl+E.

Plan mode shows a slim banner under the header so you always know analysis will not mutate by accident.

3. Panes & resizing

Between Files ↔ Chat and Chat ↔ Editor sits a vertical grip marked ┊.

  • Drag the grip horizontally to grow or shrink that side pane. Chat keeps a minimum width so the transcript stays readable.
  • Double-click the grip to reset that pane to its default width (you’ll see a brief “Pane width reset” notice).
  • Hover / drag highlights the grip in accent blue so you can find it in a dense terminal.
  • Close Files with Ctrl+B or the header toggle. Close the whole editor pane with Ctrl+E when focused there (or the header Editor button). Close one tab with Ctrl+W.

Tip

Mouse support depends on your terminal (iTerm2, Kitty, WezTerm, Windows Terminal, etc.). If drag feels dead, try another emulator or enable mouse reporting.

4. Plan / Build

Press Tab (or use the menu) to flip modes. Header subtitle shows Plan when active.

  • Plan — read, reason, propose. Mutating tools stay gated so you can explore without writing the repo.
  • Build — full agent loop. Writes and shell still go through approvals unless you’ve allowed them.

Typical flow: Plan the change → review the proposal in chat → switch to Build → approve concrete edits.

5. Chat

  • Type in the prompt and press Enter to send.
  • Type @ (or /mention) for a fuzzy file picker — mentions expand into file context for the model.
  • Ctrl+O or /attach attaches a file; /detach clears attachments.
  • Up / Down in the prompt recalls prior messages from this session.
  • Esc or Ctrl+C cancels a running turn. Ctrl+C when idle quits Pairwit.
  • Ctrl+L clears the chat (unsaved editor buffers still block clear).
  • /undo / /redo revert or restore the last turn.

6. File tree

  • Open with Ctrl+B or header Files.
  • Click a file to open it in the editor pane.
  • Right-click a node for a context menu. Keyboard on the cursor node: n new file, r rename, d delete.
  • Vendor / junk directories are filtered from the tree by default.
  • Source names are tinted lightly by language for scanability.

7. Editor

  • Multi-tab buffers with syntax highlighting. Dirty tabs show a marker; the stats bar shows the active file name.
  • Ctrl+S save · Ctrl+Shift+S save as · Ctrl+N new file · Ctrl+F find · Ctrl+W close tab · Ctrl+E close / focus the pane.
  • Select a region, then Ctrl+Shift+L (or the selection bar) to add those lines to the chat prompt as an @path:lines reference.
  • Delete the file open in the editor from the menu when you intend to remove it from disk (confirm prompts apply).

8. Approvals

Mutating tools — bash, write_file, edit_file — pause the loop until you decide. Set PAIRWIT_ASK_TOOLS=0 only if you want auto-allow (not recommended for shared or sensitive repos).

  • Once — allow this call only (1 / y).
  • Session — allow this tool for the rest of this Pairwit run (2).
  • Always — persist an allow rule to .pairwit.permissions (3).
  • Deny — block and continue (n / Esc).

Rules live in project .pairwit.permissions (allow: / deny: / ask:) or ~/.pairwit/permissions.json.

9. Sessions

  • Each run saves under the project’s Pairwit session directory as JSON. Stats and messages restore on resume.
  • /sessions — pick a past session (newest first).
  • /resume — load the latest session for this project.
  • Starting Pairwit again in the same project can pick up the last session so you don’t lose the thread.

10. Providers & models

  • /provider — Moonshot, OpenAI, Anthropic, OpenRouter, DeepSeek, Ollama, or custom. Missing keys get a clear message instead of a silent fail.
  • /model — switch model for the active provider.
  • Header subtitle always shows model · provider (plus Plan when active).

11. Slash commands

Command What it does
/helpIn-app help card
/modelPick model
/providerSwitch provider
/mention@ file picker
/sessionsLoad a past session
/resumeLatest session
/undo · /redoLast turn
/initScaffold .pairwit.md
/reload-contextRe-read .pairwit.md
/attach · /detachFile attachments

Ctrl+P opens the command palette — search Pairwit actions and Textual system commands. The header menu lists the same shortcuts.

12. Shortcut map

Keys Action
TabPlan / Build
@Mention file
Ctrl+BToggle Files
Ctrl+EFocus / close Editor pane
Ctrl+WClose editor tab
Ctrl+SSave
Ctrl+Shift+SSave as
Ctrl+NNew file
Ctrl+FFind in editor
Ctrl+Shift+LSelection → chat
Ctrl+OAttach file
Ctrl+LClear chat
Ctrl+PCommand palette
EscCancel turn
Ctrl+CCancel turn / quit if idle
Drag ┊Resize pane
Double-click ┊Reset pane width

← Back to Pairwit