# Performance and Context Management

## Model Selection

Choose from the models actually configured in Pi. Match model capability, latency, and cost to the task rather than assuming provider-specific model tiers.

- Use a fast, lower-cost model for routine edits and focused checks.
- Use a stronger reasoning model for architecture, difficult debugging, and broad refactors.
- Confirm model availability with `/model`, `/scoped-models`, or `pi --list-models`.

Configure the default with `defaultModel` and `defaultThinkingLevel` in `~/.pi/agent/settings.json` or `.pi/settings.json`. In interactive mode, cycle thinking level with Shift+Tab. Supported levels depend on the selected model.

## Context Window Management

- Keep tasks scoped and avoid loading unrelated files.
- Use Pi's context-usage display to notice pressure early.
- For long sessions, use `/compact` to summarize older messages.
- Use `/tree`, `/fork`, or `/clone` when a separate branch or session provides cleaner context.
- Preserve critical decisions and verification state in project files when compaction could lose detail.

Avoid beginning a large refactor when the remaining context is too small to implement and verify it safely.

## Parallelism

Run independent reads, searches, or checks concurrently only when the current harness exposes parallel tool execution. Keep dependent steps sequential. Pi core has no background bash; use foreground commands or an observable external tool such as tmux.

## Build Troubleshooting

If a build fails:

1. Read the first actionable error and reproduce it with the narrowest command.
2. Inspect the affected code and configuration.
3. Fix one cause at a time.
4. Re-run the narrow check, then the broader verification suite.
5. Use a matching skill or extension-provided specialist only when available.