Coding Tools & @Files

Pia can read, search, and edit text files for you — but only inside a folder you pick. Everything stays limited to that folder, so Pia can’t touch files anywhere else on your computer.

Choose a Folder

First, tell Pia which folder it’s allowed to work in.

1. Open Settings → Assistant → General
2. Find Assistant files folder
3. Click Browse… and pick a folder

That’s it — Pia can now work with files in that folder. It’s also where your memory vault lives.

Two switches sit underneath:

• Allow the assistant to read and write files in this folder — the master switch for the file tools. Turn it off (or leave the folder empty) and Pia has no file access at all.
• Allow the assistant to run git commands in this folder — see Git Commands below. It’s greyed out with Git is not installed if git isn’t on your machine.

Where New Chats Start

Default working directory for new chats points at a subfolder of your files folder — Playground out of the box. Every new chat starts there rather than at the top level, which keeps casual work away from anything that matters.

Pick an existing folder or type a new name and Pia creates it for you. Leave it empty to start new chats at the files folder root.

Scope a Single Chat

Each chat can work in a subfolder of your main folder, which keeps things focused.

1. In the Assistant, click the chat title chip at the top
2. A flyout opens with a folder picker
3. Drill into a subfolder to scope that chat to it
4. Need one that doesn’t exist yet? Click New folder and type a name, right there in the picker — creating a folder moves you into it
5. Click the home icon to return to the top folder

The two folder pickers mean different things, and each says which on hover:

• In the chat title chip — “Working folder for the next new chat.” It always sets what the next chat starts in, never the one you are in.
• On the empty state, under Start a conversation with Pia — “Working folder for this chat.” Click the folder shown there to change it before you send. Once the first message is sent, a chat keeps the folder it has.

Reference Files with @Files

You can point Pia at one particular file instead of describing where it is.

1. In the message box, type @Files followed by a file name
2. An autocomplete list shows matching files in the chat’s folder
3. Pick one to tag its path into your message

Tagging does two things: Pia gets the file’s exact path, so it reads it directly with no searching around, and the turn is narrowed to the file tools only. Handy for asking questions about a document or having Pia rewrite part of it. See @ commands for the other domains.

Note

@Files disappears from the picker if you turn off Allow the assistant to read and write files in this folder (Settings → Assistant → General) — the domain follows the file tools, so with them switched off there is nothing to tag.

What Pia can do with your files

Tool	What it does
list_files	List what’s in a folder.
find_files	Find files by name or pattern — “every spreadsheet under reports” matches directly instead of listing folder by folder.
search_files	Search file contents.
read_file	Read one file.
edit_file	Change part of a file.
write_file	Write a whole file.
delete_file	Delete a file.

Reading, searching and listing need no approval. Writing, editing and deleting always ask.

Pia is told which folder it is working in, so it stops guessing at relative paths, and a mistyped name suggests the near-matching file next to it.

Editing a file doesn’t rewrite it

When Pia changes a file, it sends just the piece that changes, so a one-word correction cannot garble the rest of a long document on the way through. You still see and approve the same diff.

Word documents and Excel workbooks are edited in place. Only the paragraphs or cells that change are touched; everything else in the file is left exactly as it was, including formatting Pia never saw.

Searching inside documents

Searching a folder’s contents covers Word documents, Excel workbooks and saved Outlook mail, not just plain text. A file Pia genuinely cannot read is named in the result, so an unsearchable document doesn’t look like an absent answer.

Saved mail is read-only: Pia will not write over a .msg or .eml. Writing text into an image file is refused rather than corrupting it.

Search ignores capitalisation by default, so a search for “cookie” finds “Cookies” and the other way round. Pia can be asked to match capitals exactly, for the times you want the marker TODO rather than every mention of the word.

Images in your files folder

read_file shows Pia the picture when the file is an image, rather than refusing it — so you can ask about a screenshot by name without attaching it. Pia sees the image for one reply, so ask what you need from it in the same message. Looking at an image needs the Pia Cloud provider, like any other image attachment.

search_files counts images separately instead of listing every PNG in the tree as a file it failed to read.

Review Changes Before They Happen

When Pia wants to change a file, it doesn’t just go ahead. An action card appears showing:

• The file path
• A colour-coded diff — green for added lines, red for removed lines

You then choose Decline, Allow once, Allow this session, or Always allow. See Tool Permissions for what each one commits you to.

Caution

Read the diff before you allow it. And keep in mind that Allow this session and Always allow cover later calls whose arguments you never see.

If a file changes on disk after Pia previewed it but before you approve, the change is blocked to keep things safe. Just ask Pia to read the file again and try once more.

Git Commands

If your folder is a git repository, Pia can work with it directly. Turn on Allow the assistant to run git commands in this folder in Settings → Assistant → General.

Read-only — no approval needed	Changes something — always asks
git_status, git_log, git_diff, git_branch, git_show	git_init, git_add, git_commit, git_switch, git_restore, git_stash

The approval card shows the exact command before anything runs. A few things Pia deliberately won’t do:

• Nothing goes over the network. There’s no push, pull, fetch, or clone. Publishing is yours to do.
• Everything stays inside your folder. Pia can’t reach a repository outside it.
• Branch switching uses git switch, so it won’t quietly discard changes the way a stray checkout can.

Caution

git_restore and git_stash can throw away uncommitted work. Pia says so when you grant them a standing approval — think twice before ticking Always allow on those two.

Tool Permissions

Reading, searching, and listing files are safe, so they don’t need approval. For any standing permissions you’ve granted:

1. Open Settings → Assistant → Tool access
2. Review what’s allowed until Pia closes and what’s allowed always
3. Click Forget or Revoke on anything you want to be asked about again

The full guide is at Tool Permissions.

Good to Know

• File tools work on text — plain text, Word, Excel and saved mail. An image is shown to Pia as a picture rather than read as text; other binary files are skipped.
• Very large files may be skipped or trimmed.
• Your file contents stay on your computer. They aren’t uploaded anywhere unless you ask Pia to do so. See the Privacy guide for more on how Pia handles your data.
• An agent run doesn’t edit this folder while it works — it uses its own copy (or its own git branch) and moves the result back when it’s done.

Next Steps

• Tool Permissions — what runs without asking
• Assistant Chats & History — chatting with Pia