simplefiles
Public
README.md
README.md
simpleFiles lets a local model in LM Studio find your files, read the ones in folders you grant, and propose changes to them. Nothing is changed until you approve it, every change is backed up first, and the last change can always be undone.
It is built for models that make mistakes. The model can only propose; a change needs a message you typed. Edits replace an exact passage of a file instead of rewriting the whole file, so a model that loses track cannot silently drop the rest of it. After every write the file is read back and checked.
/files grant <folder> in a chat. A whole drive or your whole home folder is not accepted; grant the project folders inside them.The first time the plugin runs, it builds an index of file names in your home folder in the background. That takes a few minutes and continues across replies, so find_files may report that the index is still being built.
| Tool | What it does |
|---|---|
find_files | Finds files and folders anywhere in the indexed folders by name. Returns paths only and reads nothing. Paths outside the granted folders are marked (not granted), and the model is told to ask you to grant the folder. |
list_folder | Lists a folder inside the granted folders. |
read_file | Reads a text file inside the granted folders, 300 numbered lines at a time, or fewer, or the end of the file, or only the lines containing some text. |
search_in_files | Searches the text of the files in a granted folder and returns the matching lines. |
propose_edit | Proposes replacing one exact passage of a file. The passage must appear exactly once, or the proposal is refused. |
propose_new_file | Proposes a new file. It cannot replace an existing one, and it turns away a file that copies one the model read (exactly or nearly), pointing to copy_files instead. |
copy_files | Proposes copying files or folders to another place in the granted folders, byte for byte, without passing their contents through the model. For archiving, duplicating or backing up. |
read_form | Reads a fillable PDF form as its printed text with each field marked and numbered where it sits, for example Name [#1 text] Surname [#2 text] or Married [#8 â—‹] yes [#9 â—‹] no. |
fill_form | Proposes a filled copy of a PDF form from field numbers and answers. See below. |
The model cannot delete, move or rename files, and cannot run programs of its choosing.
read_form and fill_form let the model work through a fillable PDF form with you in your own language: it reads the form, tells you in a few lines what it asks, and asks for all the answers in one message (a long form a section at a time, or one question at a time if you say so). Answers it already knows from the chat or from memory come as drafts for you to confirm. It then fills your answers in the form's language.
-filled in its name (or where says); later fills add to that copy, keeping earlier answers. Every fill is a proposal you apply with , and takes it back.You can also attach a document to the chat. LM Studio keeps attachments in its own folder, which simpleFiles never opens, so each attached document is copied into an attachments folder (Documents\simpleFiles attachments unless you set another in the plugin's settings, or off), and the model is told where the copy is. That folder is granted once something is in it. An attached PDF with fillable fields is also taken off the message, so LM Studio's document reader does not paste its text into the chat as well; the model reads it with read_form. If the document reader runs first (it comes before simpleFiles in the chat's plugin list), simpleFiles finds the attached file in LM Studio's folder by the name the reader wrote, and takes a form's pasted text back out. Attaching the same file twice keeps one copy; images are left with the message.
When a granted folder holds a project, the model also gets run_script, which runs the commands the project declares for itself:
package.json (test, , and so on);The model picks a command by name and never writes one. Without a name, run_script lists them, with what each runs. How each one runs:
A long check keeps running in the background, and the model collects the result with its next call. In chats where no granted folder holds a project, run_script is not offered at all. Turn Project commands off in the settings to never offer it.
Send these as chat messages in a chat with the plugin on. The plugin answers them itself; the model only shows the result.
A command can also come after other words, as in done, /files apply 3, and one message can hold several, as in /files apply 4 5 /files reject 6; each command takes only its own numbers, and the rest of the message goes to the model as usual, so in /files apply 3 and then run the tests the model is asked to run the tests. A message that both applies and rejects the same change does neither. Anything without /files goes to the model, which cannot apply changes. Within a command, numbers can be written as 4, #4 or 4 and 5, and extra words are fine (/files apply all please). An exception such as all except 4 is refused rather than guessed at; name the numbers instead.
A change is applied only if its passage is still in the file exactly once, so a proposal made before you edited the file yourself is refused rather than applied in the wrong place. Undo restores the backup only if the file is still exactly as simpleFiles left it; if you changed it since, undo tells you where the backup is instead of overwriting your work.
A task that changes many files otherwise stops after every batch to ask, and the approvals pile up. /files autoapply <folder> lets the model's edits, new files, copies and the project's own build (a script named build, compile or bundle) take effect in that folder without /files apply, for two hours or the time you add, up to 60 changes. Each change is still backed up and logged, /files status lists them, and /files undo reverses the last one. Plugin installs and every other command still ask. It ends by itself when the time or the changes run out, or when you send /files autoapply off. Use it on a project that is in git or otherwise backed up, for a task you have agreed on.
A long session's view of its own work drifts as the chat is compacted: it starts to misremember what was applied, what it ruled out, and what broke. When that happens, it is better to hand the work to a new chat than to push on.
With a project granted, the model gets write_handoff: it records the goal, what was tried and ruled out, and the next step. The handoff belongs to a folder: a project, or a repository root holding several projects. simpleFiles adds the verified state itself (waiting and applied changes, the last test result of each project and whether its code changed since, the recent change log, and a plugin's log) and recomputes it every time the handoff is read, so the facts never go stale in the saved file. The handoff lives in simpleFiles' data folder, never in the project, so it cannot end up in a commit or an upload.
Your commands:
In the new chat, /files resume prints the previous session's judgment with the state gathered fresh, and the model is told to confirm it with its own tools before changing anything. Naming a folder inside the one the handoff belongs to finds it too. If the context compressor is on, it suggests a handoff on its own once a chat has been compacted several times.
After simpleFiles is updated, the next message in a chat with granted folders tells the model, once, what its tools can now do, since a model in the middle of a long chat otherwise carries on with the tools it remembers.
Everything is kept in .lmstudio\simplefiles in your home folder:
The name index lists the names of the files in your home folder, so it stays on your computer like the rest. Delete the names folder to remove it; it is rebuilt when needed.
A model that has read a file can repeat it elsewhere, for example in a web search if a search plugin is on in the same chat. simpleFiles records fingerprints (short hashes, not the text) of the email addresses, phone and account numbers, and keys and IDs in what it shows the model, in .lmstudio\local-only in your home folder, and marks its output with a privacy: local line. simpleSearch uses them to block any search containing those details, and can also be set to ask before every search in a chat with your files in it. A search plugin that does not check for this can still send what the model read, so grant only folders whose contents you are comfortable having the model see.
PolyForm Noncommercial 1.0.0: free for personal and other noncommercial use. Selling it, or using it in a paid product or service, needs permission from attitudejacket. See LICENSE.txt.
simpleFiles lets a local model in LM Studio find your files, read the ones in folders you grant, and propose changes to them. Nothing is changed until you approve it, every change is backed up first, and the last change can always be undone.
It is built for models that make mistakes. The model can only propose; a change needs a message you typed. Edits replace an exact passage of a file instead of rewriting the whole file, so a model that loses track cannot silently drop the rest of it. After every write the file is read back and checked.
/files grant <folder> in a chat. A whole drive or your whole home folder is not accepted; grant the project folders inside them.The first time the plugin runs, it builds an index of file names in your home folder in the background. That takes a few minutes and continues across replies, so find_files may report that the index is still being built.
| Tool | What it does |
|---|---|
find_files | Finds files and folders anywhere in the indexed folders by name. Returns paths only and reads nothing. Paths outside the granted folders are marked (not granted), and the model is told to ask you to grant the folder. |
list_folder | Lists a folder inside the granted folders. |
read_file | Reads a text file inside the granted folders, 300 numbered lines at a time, or fewer, or the end of the file, or only the lines containing some text. |
search_in_files | Searches the text of the files in a granted folder and returns the matching lines. |
propose_edit | Proposes replacing one exact passage of a file. The passage must appear exactly once, or the proposal is refused. |
propose_new_file | Proposes a new file. It cannot replace an existing one, and it turns away a file that copies one the model read (exactly or nearly), pointing to copy_files instead. |
copy_files | Proposes copying files or folders to another place in the granted folders, byte for byte, without passing their contents through the model. For archiving, duplicating or backing up. |
read_form | Reads a fillable PDF form as its printed text with each field marked and numbered where it sits, for example Name [#1 text] Surname [#2 text] or Married [#8 â—‹] yes [#9 â—‹] no. |
fill_form | Proposes a filled copy of a PDF form from field numbers and answers. See below. |
The model cannot delete, move or rename files, and cannot run programs of its choosing.
read_form and fill_form let the model work through a fillable PDF form with you in your own language: it reads the form, tells you in a few lines what it asks, and asks for all the answers in one message (a long form a section at a time, or one question at a time if you say so). Answers it already knows from the chat or from memory come as drafts for you to confirm. It then fills your answers in the form's language.
-filled in its name (or where says); later fills add to that copy, keeping earlier answers. Every fill is a proposal you apply with , and takes it back.You can also attach a document to the chat. LM Studio keeps attachments in its own folder, which simpleFiles never opens, so each attached document is copied into an attachments folder (Documents\simpleFiles attachments unless you set another in the plugin's settings, or off), and the model is told where the copy is. That folder is granted once something is in it. An attached PDF with fillable fields is also taken off the message, so LM Studio's document reader does not paste its text into the chat as well; the model reads it with read_form. If the document reader runs first (it comes before simpleFiles in the chat's plugin list), simpleFiles finds the attached file in LM Studio's folder by the name the reader wrote, and takes a form's pasted text back out. Attaching the same file twice keeps one copy; images are left with the message.
When a granted folder holds a project, the model also gets run_script, which runs the commands the project declares for itself:
package.json (test, , and so on);The model picks a command by name and never writes one. Without a name, run_script lists them, with what each runs. How each one runs:
A long check keeps running in the background, and the model collects the result with its next call. In chats where no granted folder holds a project, run_script is not offered at all. Turn Project commands off in the settings to never offer it.
Send these as chat messages in a chat with the plugin on. The plugin answers them itself; the model only shows the result.
A command can also come after other words, as in done, /files apply 3, and one message can hold several, as in /files apply 4 5 /files reject 6; each command takes only its own numbers, and the rest of the message goes to the model as usual, so in /files apply 3 and then run the tests the model is asked to run the tests. A message that both applies and rejects the same change does neither. Anything without /files goes to the model, which cannot apply changes. Within a command, numbers can be written as 4, #4 or 4 and 5, and extra words are fine (/files apply all please). An exception such as all except 4 is refused rather than guessed at; name the numbers instead.
A change is applied only if its passage is still in the file exactly once, so a proposal made before you edited the file yourself is refused rather than applied in the wrong place. Undo restores the backup only if the file is still exactly as simpleFiles left it; if you changed it since, undo tells you where the backup is instead of overwriting your work.
A task that changes many files otherwise stops after every batch to ask, and the approvals pile up. /files autoapply <folder> lets the model's edits, new files, copies and the project's own build (a script named build, compile or bundle) take effect in that folder without /files apply, for two hours or the time you add, up to 60 changes. Each change is still backed up and logged, /files status lists them, and /files undo reverses the last one. Plugin installs and every other command still ask. It ends by itself when the time or the changes run out, or when you send /files autoapply off. Use it on a project that is in git or otherwise backed up, for a task you have agreed on.
A long session's view of its own work drifts as the chat is compacted: it starts to misremember what was applied, what it ruled out, and what broke. When that happens, it is better to hand the work to a new chat than to push on.
With a project granted, the model gets write_handoff: it records the goal, what was tried and ruled out, and the next step. The handoff belongs to a folder: a project, or a repository root holding several projects. simpleFiles adds the verified state itself (waiting and applied changes, the last test result of each project and whether its code changed since, the recent change log, and a plugin's log) and recomputes it every time the handoff is read, so the facts never go stale in the saved file. The handoff lives in simpleFiles' data folder, never in the project, so it cannot end up in a commit or an upload.
Your commands:
In the new chat, /files resume prints the previous session's judgment with the state gathered fresh, and the model is told to confirm it with its own tools before changing anything. Naming a folder inside the one the handoff belongs to finds it too. If the context compressor is on, it suggests a handoff on its own once a chat has been compacted several times.
After simpleFiles is updated, the next message in a chat with granted folders tells the model, once, what its tools can now do, since a model in the middle of a long chat otherwise carries on with the tools it remembers.
Everything is kept in .lmstudio\simplefiles in your home folder:
The name index lists the names of the files in your home folder, so it stays on your computer like the rest. Delete the names folder to remove it; it is rebuilt when needed.
A model that has read a file can repeat it elsewhere, for example in a web search if a search plugin is on in the same chat. simpleFiles records fingerprints (short hashes, not the text) of the email addresses, phone and account numbers, and keys and IDs in what it shows the model, in .lmstudio\local-only in your home folder, and marks its output with a privacy: local line. simpleSearch uses them to block any search containing those details, and can also be set to ask before every search in a chat with your files in it. A search plugin that does not check for this can still send what the model read, so grant only folders whose contents you are comfortable having the model see.
PolyForm Noncommercial 1.0.0: free for personal and other noncommercial use. Selling it, or using it in a paid product or service, needs permission from attitudejacket. See LICENSE.txt.
list_proposals | Lists the changes waiting for your approval and the ones applied recently, so the model checks instead of remembering. |
save_as/files apply/files undobuildlintpytest, for a Python project that uses it;Makefile, when make is installed;lmstudio-install (install its current code into LM Studio) and lmstudio-log (what the plugin wrote to LM Studio's log today: its messages and errors, and when it started and stopped, nothing from other plugins)./files trust <folder>/files apply, every time. A command cannot be undone, except an LM Studio install.lms dev --install first), builds it the way LM Studio's installer does, replaces the installed src folder as a whole, and keeps the previous version, so /files undo puts it back. LM Studio uses the new version the next time it starts the plugin; to be sure, turn the plugin off and on again, or restart LM Studio... or a link, is refused..env files, SSH and other private keys, certificates, password databases, credential files) are never read or changed, even in a granted folder..git and node_modules can be read but never changed..lmstudio in your home folder) is never granted: it holds your chats, your memory file and saved credentials. Plugin installs and plugin logs have their own tools.node_modules, or the folders under Never look in. It holds names only, never contents.backups\: the original of every file before each change, by project and time, with a note of the changechanges.md: a readable log of every change and undopending.json, applied.json, grants.json: waiting changes, made changes, and folders granted from chatsnames\: the file name indexinstalls\: the last few versions of each plugin installed through lmstudio-install, for undotests\: the result of each project's last test runtrusted.json: the folders trusted for checks/files status granted folders, waiting changes, recent changes, the name index
/files pending show each waiting change with the lines it removes and adds
/files apply 3 make change #3 (with one change waiting, /files apply is enough)
/files apply all make every waiting change, in the order they were proposed
/files reject 3 drop change #3 (or /files reject all)
/files keep 3 leave change #3 waiting
/files undo reverse the last change that was made
/files grant <folder> let the model read that folder and propose changes in it
/files revoke <folder> take a chat grant back
/files reindex rebuild the file name index now
/files trust <folder> let checks (tests, lint, type checks) in projects there run without asking
/files untrust <folder> make them ask first again
/files autoapply <folder> [time] let changes there take effect without asking, for 2 hours or the time given (such as 4h)
/files autoapply turn it on for the folder the waiting changes are in, or show what is on
/files autoapply off end it
/files handoff [folder] show the handoff and the current state; without a folder, for the folder of the latest changes
/files resume [folder] in a new chat, load the handoff and the current state; without a folder, the newest handoff
list_proposals | Lists the changes waiting for your approval and the ones applied recently, so the model checks instead of remembering. |
save_as/files apply/files undobuildlintpytest, for a Python project that uses it;Makefile, when make is installed;lmstudio-install (install its current code into LM Studio) and lmstudio-log (what the plugin wrote to LM Studio's log today: its messages and errors, and when it started and stopped, nothing from other plugins)./files trust <folder>/files apply, every time. A command cannot be undone, except an LM Studio install.lms dev --install first), builds it the way LM Studio's installer does, replaces the installed src folder as a whole, and keeps the previous version, so /files undo puts it back. LM Studio uses the new version the next time it starts the plugin; to be sure, turn the plugin off and on again, or restart LM Studio... or a link, is refused..env files, SSH and other private keys, certificates, password databases, credential files) are never read or changed, even in a granted folder..git and node_modules can be read but never changed..lmstudio in your home folder) is never granted: it holds your chats, your memory file and saved credentials. Plugin installs and plugin logs have their own tools.node_modules, or the folders under Never look in. It holds names only, never contents.backups\: the original of every file before each change, by project and time, with a note of the changechanges.md: a readable log of every change and undopending.json, applied.json, grants.json: waiting changes, made changes, and folders granted from chatsnames\: the file name indexinstalls\: the last few versions of each plugin installed through lmstudio-install, for undotests\: the result of each project's last test runtrusted.json: the folders trusted for checks/files status granted folders, waiting changes, recent changes, the name index
/files pending show each waiting change with the lines it removes and adds
/files apply 3 make change #3 (with one change waiting, /files apply is enough)
/files apply all make every waiting change, in the order they were proposed
/files reject 3 drop change #3 (or /files reject all)
/files keep 3 leave change #3 waiting
/files undo reverse the last change that was made
/files grant <folder> let the model read that folder and propose changes in it
/files revoke <folder> take a chat grant back
/files reindex rebuild the file name index now
/files trust <folder> let checks (tests, lint, type checks) in projects there run without asking
/files untrust <folder> make them ask first again
/files autoapply <folder> [time] let changes there take effect without asking, for 2 hours or the time given (such as 4h)
/files autoapply turn it on for the folder the waiting changes are in, or show what is on
/files autoapply off end it
/files handoff [folder] show the handoff and the current state; without a folder, for the folder of the latest changes
/files resume [folder] in a new chat, load the handoff and the current state; without a folder, the newest handoff