> ## Documentation Index
> Fetch the complete documentation index at: https://termmate.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Basic Usage

> Choose your AI agent, control tool-use permissions, and enable Plan Mode for safe complex tasks.

## Selecting an Agent

TermMate supports three agent backends. Switch between them using the agent selector in the chat panel.

| Agent      | Backed by                                   | CLI binary |
| ---------- | ------------------------------------------- | ---------- |
| **Claude** | Anthropic Claude                            | `claude`   |
| **Codex**  | OpenAI                                      | `codex`    |
| **Pi**     | Pi Coding Agent by Earendil (Gemini models) | `pi`       |

### VS Code

Use the **AGENT** dropdown in the chat input panel. Your selection is remembered per workspace.

### Sublime Text

Switch agents by clicking the **Agent** tag above the chat input, or run `TermMate: Agent` from the Command Palette. Each entry shows the detected CLI path as an annotation so you can confirm which binary will be used. The choice is stored per window and persists with your project.

To set a model per agent, click the **Model** tag above the chat input or run `TermMate: Model`. Models are remembered separately for each agent (e.g. `gpt-5.4-mini` for Codex, `google/gemini-3.1-flash-lite` for Pi).

Pi Agent uses a `GEMINI_API_KEY` environment variable. Run `pi` in a terminal and use `/login` to authenticate before first use, or set the key via TermMate's `env` setting.

Common Pi Agent install locations TermMate searches automatically:

* `~/.local/bin/pi`
* `~/.npm-global/bin/pi`, `~/.yarn/bin/pi`, `~/.bun/bin/pi`
* `/usr/local/bin/pi`, `/opt/homebrew/bin/pi`

To override the detected binary path for any agent, set `<agent>_command` in your TermMate settings:

```json theme={null}
{
  "claude_command": "/path/to/claude",
  "codex_command":  "/path/to/codex",
  "pi_command":     "/path/to/pi"
}
```

***

## Tool Use Permissions

Agents are "agentic" because they call tools. Before any destructive action, TermMate asks for your approval:

* **File Edits** — review a diff before changes are written to disk.
* **Terminal Commands** — see the exact shell command before it runs.
* **Bash / MCP tools** — approve or deny individual tool calls inline.

You can reduce interruptions in two ways:

* **Approve Mode** (`TermMate: Approve Mode` in Sublime Text) — choose `default` (prompt before every tool action), `allow-edit` (auto-approve safe read/edit operations, still prompt for shell commands), or `accept-all` (auto-approve everything, including shell execution).
* **`allowed_tools` setting** — a list of tools the agent may always use without confirmation. The default is `["Read", "Glob", "Grep", "TodoWrite", "WebFetch", "WebSearch", "Skill"]`.

***

## Plan Mode

For complex tasks, enable **Plan Mode** so the agent reasons before it acts:

1. The agent analyzes the task and writes a detailed step-by-step plan.
2. You review the plan before anything is executed.
3. The agent carries out each step with your oversight.

This prevents the agent from going off-track on large refactors or multi-file changes.

**Pi Agent Plan Mode** uses a read-only exploration phase first — the agent is restricted to safe read/find/grep tools until you approve the proposed plan, then exits to full execution with `/plan implement`.

### VS Code

Use the plan mode selector in the chat panel: choose `planning` (make plan and to-do list before executing) or `fast` (execute directly).

### Sublime Text

Toggle Plan Mode per session by clicking the **PlanMode** tag above the chat input, or run `TermMate: Plan Mode` from the Command Palette: choose `planning` (make plan and todo-list before execute) or `fast` (execute directly, the default).