Workspace and files
The folder Aldwin works in, what it can do with your files, and what it will not touch.
On this page
Aldwin works inside one folder at a time, called the workspace. Pointing it at the right folder is the best way to get useful help with your files, and to keep everything else out of reach.
Which folder is the workspace#
The workspace is the folder your terminal was in when you started Aldwin. If you started it from your home folder, which is what a new terminal window opens in, Aldwin uses a folder called aldwin_workspace in your home folder instead, and creates it if needed.
To see it, ask Aldwin:
Which folder are you working in?
Choose a different folder#
Web app: stop Aldwin with Ctrl-C, then start it with the folder you want:
aldwin web --workspace ~/Documents/notesTerminal: type /workspace to see the current folder, or /workspace ~/Documents/notes to switch.
What Aldwin can do with files#
| You ask | What happens | Asks first? |
|---|---|---|
| "What's in this folder?" | Lists and searches files | No |
| "Summarise report.pdf" | Reads the file | No |
| "Fix the typos in notes.md" | Shows you the exact change, then edits | Yes |
| "Write a packing list to trip.md" | Shows you the new file, then creates it | Yes |
| "Download this PDF" | Saves it into a downloads folder in the workspace | Yes |
Aldwin reads text files, PDF, CSV, and HTML out of the box.
Office documents#
Office files need two small add-ons: one to read them, and one to create Word documents, spreadsheets, and PDFs. Install both by running this in a terminal, then start Aldwin again:
uv tool install "aldwin[office,docs]"Your conversations and settings are not affected.
Before Aldwin edits a file, it reads the current version. If the file changed after you saw the proposed edit, Aldwin shows you the new change and asks again.
Files outside the workspace#
Aldwin can work with files elsewhere on your computer, but it asks more often:
- Reading outside the workspace asks once per folder in each conversation.
- Changing anything outside the workspace asks every time.
What Aldwin never touches#
Some files are off limits whatever you or the model say. Aldwin will not read or change:
- Passwords and keys, such as
.envfiles, SSH keys, and cloud sign-in folders. - Its own home folder,
~/.aldwin, where your keys and sign-ins are kept. - The hidden
.gitfolder inside a project, which it can read but never change.
These are hidden from folder listings and searches too. Aldwin tells you how many files it hid.
Tips#
- Keep one folder per project and start Aldwin there.
- For notes, point Aldwin at your notes folder or Obsidian vault.
- Keep backups of anything important. Aldwin asks before every change, but an approved edit is a real edit.
More on approvals: Safety.