Help center
Common questions, straight answers.
Use Ctrl+F to find what you need fast. If it's not here, the support page tells you how to reach a human, and the docs have the long-form material.
I just installed Pearl. What do I do first? ＋
Open Pearl, click Sign in to Pearl Scout in the chat panel, finish the browser handoff. Then open a real project (File → Open Folder) and ask Ask mode "what does this codebase do?" — the five-minute path is here.
Do I need a Pearl account? ＋
Yes — for any AI feature, including the Codex / Claude Code / Copilot providers. The non-AI editor (file editing, terminal, search) works without sign-in. More on the sign-in gate.
Which mode should I start with? ＋
Ask. It's read-only — Pearl literally can't write to your files in Ask mode. Use it to poke around. Switch to Agent once you know what you want to change.
Where do I download Pearl? ＋
/download auto-detects your platform. Stable, Preview, and Next channels are selectable on that page.
What's the difference between Ask, Plan, and Agent? ＋
They're three different agents. Ask is read-only research. Plan emits an interactive checklist before writing anything. Agent has full tools — read, write, edit, run, sub-agent delegation. Full breakdown.
How do I switch agents without switching modes? ＋
Type
@Pearl-Ask, @Pearl-Plan, or @Pearl-Agent in the chat input to route one message to a specific agent without changing the toolbar mode. Why did Pearl show a confirmation when I switched to Agent mode? ＋
Agent mode runs autonomously — reads, writes, executes commands. The one-time confirmation is an opt-in to that behavior. After you accept, it never asks again unless you clear the
ai-features.pearl.agentModeAcknowledged preference. Can I cancel an Agent run in progress? ＋
Yes. The chat panel surfaces a Stop button while a turn is streaming. Pearl propagates the cancellation to the upstream provider within about a second — you stop paying for tokens you cancelled.
What if Plan mode's plan is wrong? ＋
Edit it. The interactive plan is yours — you can delete phases, reorder them, or rewrite the prompts. When you Run a phase, Pearl uses your edited version.
Can I use my own OpenAI / Anthropic key? ＋
Yes. The provider picker has Codex (your OpenAI key) and Claude Code (your Anthropic key). Paste once — keys go in the OS keychain. Per-provider details.
Where are my BYO keys stored? ＋
In the OS keychain: Windows Credential Manager on Windows, Keychain on macOS, libsecret on Linux. Pearl never sees a non-Pearl provider key in plaintext beyond the keychain handoff.
Do BYO keys count against my Pearl quota? ＋
No. Pearl Scout (native) quota only applies to Scout requests. Codex and Claude Code billing goes directly through your OpenAI / Anthropic account. Copilot counts against your Copilot subscription.
Can I switch providers mid-conversation? ＋
Yes — one click in the model picker. The conversation thread stays; only the model changes for the next turn.
An Agent edit looks wrong — how do I undo it? ＋
One Ctrl+Z reverts the entire response (every hunk in every file). Or use the inline Undo button on a specific hunk to back out one change without losing the others.
What do the yellow dots on file tabs mean? ＋
ChangeSet markers. Pearl marks every file the agent touched so you can see the blast radius of one response. They auto-clear when the session resolves.
Why aren't my changes saving? ＋
Pearl stages Agent edits as inline hunks — nothing is written until you Keep the hunk (per-hunk button) or accept the response. This is by design; see the blog post on why.
Can I edit a hunk before accepting it? ＋
Yes. Click directly into the staged hunk in the editor, edit normally, then Keep. Your edit replaces the agent's.
What is .pearl/memory/project.md?
＋
Scout's per-project memory file. Conventions, prior decisions, where things live — anything you wouldn't get from re-reading the code. More on memory.
Should I commit project memory to git? ＋
Depends. Project-level entries (conventions, architecture) → commit. Developer-specific entries (your individual preferences) → gitignore the file or split entries. Pearl doesn't gitignore it by default; you decide.
How do I delete a memory entry? ＋
Open
.pearl/memory/project.md directly (click the memory chip in the chat input) and delete the entry. Save the file. Done. What does the green/orange/red ring in the chat input mean? ＋
The context-usage ring — real-time token usage against the active model's context window. Click it to
/compact: Scout summarizes older turns into a rolling summary and frees the budget. How do I change my plan? ＋
Plan changes are sales-driven — contact sales or email your account contact. There's no self-serve upgrade button.
Why isn't there a free tier? ＋
Because every Scout request hits a frontier provider that costs us real money. A meaningful free tier would lose us money on every user; a tokenized free tier would teach the wrong lesson. More on pricing.
How do I see my current usage? ＋
Dashboard at /account/usage shows current period usage by model and by week. Business+ accounts also see per-seat breakdown.
I hit my quota mid-month. What now? ＋
Email your sales contact — quota raises are quick. You can also swap to a BYO provider (Codex, Claude Code) for the rest of the month if you have those keys.
My subscription expired — what happens? ＋
AI gateway access is disabled. The IDE keeps working for non-AI editing. The dashboard surfaces a renewal CTA.
Does Pearl train on my code? ＋
No. Scout reads your code at request time as context. It is not used to fine-tune any model — ours or anyone else's.
How do I turn on zero-retention privacy mode? ＋
Available on every paid plan. Toggle from /account → Privacy. Default-on for Enterprise. Full security page.
Where is my data stored? ＋
On PearlFibers infrastructure in our primary region. Backups are encrypted and kept in the same region. Sovereign-region deployment is available on Enterprise.
How do I report a security issue? ＋
Email security@pearlfibers.com. We acknowledge within one business day. Please don't disclose publicly until we've shipped the fix.
How do I delete my account? ＋
Account deletion is handled at auth.pearlfibers.com. Pearl-side data is purged within 30 days via the back-channel logout — including backup cascades.
Sign-in tab opens but Pearl never picks it up ＋
Likely the
pearl:// protocol handler isn't registered. Re-run the installer, or restart Pearl as administrator once. As a fallback, Pearl supports the loopback redirect (RFC 8252) — sign-in will land on a local 127.0.0.1 port instead. The model picker is empty ＋
Usually a sign-in issue. Click Sign in to Pearl Scout. If that doesn't fix it, your account may not have any active entitlements — email sales or check /account.
Chat says "rate limit exceeded" ＋
Either you're sending requests faster than the per-key rate limit, or you've hit the monthly cap. Wait a minute (rate) or contact sales (cap).
Agent mode hangs on a tool call ＋
Click Stop in the chat panel. Pearl cancels the upstream provider and frees the session. If the same tool hangs repeatedly, file feedback with the tool name and what triggered it.
Update notification keeps reappearing after I install ＋
Restart Pearl after an update. If the prompt still shows the old version, manually trigger Check for updates from Help and let it complete a full cycle.
My VS Code extension doesn't work in Pearl ＋
Extensions should run unchanged. If one doesn't, file feedback with the extension name and what fails — extension-host quirks are a hotspot we actively triage.
Didn't find your answer?
Three options:
- Long-form material — keybindings, advanced settings, deep integration notes — lives in the docs.
- Talk to a human — the support page tells you which channel matches the question (general, security, sales).
- File feedback — if the help center should have answered and didn't, tell us and we'll add it.