This tutorial walks you through one Agent edit, end to end. By the time you finish, you'll have used Ask mode, switched to Agent mode, watched an inline diff appear, accepted a hunk, and rejected another. That's the whole loop.
Time required: about 10 minutes. You need Pearl installed and a real project handy.
Step 1 — Sign in
Open Pearl. In the chat panel on the right, click Sign in to Pearl Scout.
A browser tab opens, you confirm with PearlFibers SSO, and the tab hands you back into the
IDE via the pearl:// protocol handler. You'll see your avatar in the bottom-left
corner.
If the browser tab doesn't hand back: the pearl:// handler
isn't registered. Re-run the installer, then try again. Loopback fallback (RFC 8252) is also
supported as a backup.
Step 2 — Open a project you know
File → Open Folder, pick a real project. Scout is more useful on code you can sanity-check the answers against — your own project, even a small one, beats a sample repo.
Step 3 — Ask, before you write
Make sure the mode selector above the chat input says Ask. Type:
What does this codebase do?Send. Scout will read a few key files and summarize. Notice it doesn't write anything — Ask mode literally has no write tools. This is your "safe to poke around" mode.
Read the answer. If it got something wrong, that's useful — it tells you whether the project has enough surface for Scout to work with, and where memory might help (we'll get there).
Step 4 — Pick something small to change
Look at your project. Find a function or file that needs one small thing — a missing docstring, an inconsistent name, a TODO that's been there too long. Don't pick anything big for the first run.
Now switch the mode selector to Agent. Pearl will show a one-time confirmation explaining that Agent mode is autonomous (full tools, no per-step confirmations). Click Continue with Agent Mode.
Step 5 — Ask for the edit
Attach the file you want to change with #file:path/to/your/file.ext (or
#_f for the active file). Type a clear request:
Add a docstring to the `register` method explaining what it
takes and what it throws.Send. Scout will read the file, then propose an edit. Watch the editor — not the chat panel. The edit appears as inline hunks: green for added lines, red ghost text for removed lines.
Step 6 — Accept or reject
Hover over a hunk. You'll see Keep and Undo buttons inline, plus prev/next arrows to jump between hunks. Keep writes the change. Undo rejects it.
Don't accept everything yet. Reject one hunk on purpose just to see the flow. The change disappears from the editor; the chat panel still shows it as a rejected hunk.
Now accept the rest. The changes write to your file. Yellow dots in the file tree clear (the session resolved). You're done.
Step 7 — Undo the whole thing if you want
One Ctrl+Z reverts every accepted hunk in that response — across files, in one keystroke. Useful when you accepted something and then realized you didn't want it after all.
What you just learned
- Ask before Agent — the safer default for exploring.
- Switch modes with one click — no need to start a new chat.
- Edits appear as diffs, not file writes — you control what lands.
- One Ctrl+Z reverts the whole response — your escape hatch.
Next
Try seeding project memory next — three lines
in .pearl/memory/project.md will sharpen every subsequent Scout interaction in
this project.