User guide

01 Getting started

From any project root: install, set a key, open the desk. Under a minute if pip is ready.

1. Install and launch

   pip install pairwit && pairwit

2. Add a provider key

   Project .env or ~/.pairwit/.env. Default path is Moonshot: MOONSHOT_API_KEY. Other providers use their usual env names.

3. Optional project context

   /init scaffolds .pairwit.md (injected every session). /reload-context re-reads it after edits.

02 The desk

Pairwit is a terminal desk — chat stays center stage; Files, Editor, and Schedule open beside it when you need them.

Header

Model · provider, menu, and toggles for Files / Editor / Schedule.

Files

Project tree. Header Files or Ctrl+B.

Editor

Syntax-highlighted buffers. Open from the tree, then Editor or Ctrl+E.

Schedule

Later agent jobs. /schedule or header Schedule.

Chat

Transcript, tool cards, and the prompt — always the main column.

03 Panes & resizing

Side panes share space with chat through a vertical grip (┊). Chat never shrinks below a readable minimum.

Drag

Move ┊ horizontally to grow or shrink that pane.

Double-click

Reset that pane to its default width.

Close

Files: Ctrl+B. Editor pane: Ctrl+E. One tab: Ctrl+W.

04 Plan / Build

Press Tab to flip modes. Explore safely, then mutate on purpose.

Plan

Read, reason, propose. Mutating tools stay gated.

Build

Full agent loop. Writes and shell still ask unless you’ve allowed them.

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

05 Chat

The prompt is where work starts. Mentions and attachments pull the repo into context.

• Enter sends. Up / Down recall prior prompts in this session.
• @ or /mention — fuzzy file picker into context.
• Ctrl+O / /attach attach a file; /detach clears.
• Esc or Ctrl+C cancels a running turn. Idle Ctrl+C quits.
• Ctrl+L clears chat (blocked if editor buffers are dirty).
• /undo · /redo — last turn.

06 File tree

Browse the project without leaving the desk. Click a file to open it in the editor.

• Toggle with Ctrl+B or header Files.
• On the cursor node: n new · r rename · d delete (or right-click).
• Vendor / junk dirs are filtered; source names are lightly tinted by language.

07 Editor

Multi-tab buffers with syntax highlighting. Save without leaving the agent.

• Ctrl+S save · Ctrl+Shift+S save as · Ctrl+N new · Ctrl+F find · Ctrl+W close tab · Ctrl+E focus / close pane.
• Select lines, then Ctrl+Shift+L to send @path:lines into the chat prompt.
• Dirty tabs show a marker; the stats strip names the active file.

09 Approvals

bash, write_file, and edit_file pause until you decide (default on). Prefer keeping approvals on for shared or sensitive repos.

Once

This call only — 1 / y.

Session

This tool for the rest of the run — 2.

Always

Persist allow in .pairwit.permissions — 3.

Deny

Block and continue — n / Esc.

Rules: project .pairwit.permissions (allow: / deny: / ask:) or ~/.pairwit/permissions.json. Set PAIRWIT_ASK_TOOLS=0 only if you intentionally want auto-allow.

10 Sessions

Each run saves under the project’s Pairwit session directory. Resume when you return.

• /sessions — pick a past session (newest first).
• /resume — load the latest for this project.
• Starting Pairwit again in the same project can pick up the last thread.

11 Providers & models

Bring your own keys. The header always shows model · provider (and Plan when active).

• /provider — Moonshot, OpenAI, Anthropic, OpenRouter, DeepSeek, Ollama, or custom. Missing keys get a clear message — not a silent fail.
• /model — switch model for the active provider.

12 Slash commands

Type a slash in the prompt, or open the palette with Ctrl+P.

13 Shortcut map

The muscle-memory map. Same keys as the header menu and palette.