Files Guide
Enable File to read, write, edit, and find files within your agent’s granted folders. Set its sandbox’s writable paths before asking it to change a document.
lnk agent startlnk agent tool add fileAsk it to change a file
Ask it to "add tomatoes to my garden list" and it reads
work/garden.md, edits the line, and answers with what it changed.
What it needs
You need the agents modules, which lnk up installs and which
bring Link File, and Link Harness. A new agent has file on, so asked
to change a file, its standing instructions or a skill, it does.
lnk agent tool add file turns it on again where a spec turned it
off, and each start then gives the agent its file.
What your agent can do
Your agent sees five tools, each over a path in its files folder, such
as work/garden.md. They take the names and arguments of Claude Code's
Read, Write, Edit, Glob and Grep, the file tools current models are
trained on, so a model calls them as it already knows how. Link Harness
also accepts the corresponding slash commands with a JSON object after
the name, using the running agent’s enabled provider and grants.
file__read
/file:read invokes file__read, for example
/file:read {"file_path":"work/garden.md"}. It gives a text file, at
most 24 KB a call, from line offset (the first, left out) and at most
limit lines, and says where it stopped so the next call reads on. An image (PNG, JPEG, GIF or WebP) or a PDF
of at most 2 MiB it gives whole, as MCP's image or resource content, so
a model that reads them sees it. A larger one is refused, since a
model's provider may refuse it too.
file__write and file__edit
/file:write invokes file__write to write a file whole (file_path
and its content), making it and its folders. /file:edit invokes
file__edit, which replaces old_string, given exactly as the file
holds it, with new_string, found once, or every time with
replace_all.
file__glob and file__grep
/file:glob invokes file__glob, which finds files by a glob
pattern of their name, any case (*.rs), or of their path below the
folder it looks in when the glob holds / (src/**/test_*.py, where
**/ is any folders or none). /file:grep invokes file__grep, which
finds the lines a regular expression pattern matches (fn \w+\(),
in the files its glob names when given one. With no path, or an
empty one, each looks in Home, never in the agent's own folder.
What file__glob and file__grep pass over
Each passes over hidden files and what a folder's .gitignore names
(as git does, so node_modules/ and target/ are usually skipped).
file__grep also passes over files over 1 MiB and files that aren't
text. The answer counts each (skipped). Each looks at 10,000 files
and folders at most, for 10 seconds at most, and finds 100 at most.
When one stops early the answer says why (stopped).
Its diffs
file__write and file__edit answer with the change as a unified
diff, as git diff shows one, so your agent sees what it changed. A
diff over 16 KB, or of a file that wasn't text, is left out: the answer
says so (diff_cut) and gives the new text's SHA-256 instead.
Marked as the files'
What file__read, file__glob and file__grep give, and a change's diff, comes inside a fence, an opening <untrusted ...> line and a closing line with the same random ID, which tells your agent's model that it's data to read and never your instructions, since anyone may have written it. An image's or a PDF's line comes in one too, before it. Untrusted Content explains the fence.
Turn it off
It is off until you add it. lnk agent tool remove file or the agent's
spec turns it off ([tool.file] enabled = false), or only
file__glob and file__grep (find = false), or the diffs (diffs = false): what it
turns off isn't listed to the model, and the answers carry no diff.
Choose what it may write
Your agent writes only the folders its sandbox file's [files] lets
it. Link's is work/, instructions/ and skills/, so it changes
its standing instructions and skills when asked, and chats/ is never
written but by its harness.
# ~/Link/Safe/Agents/main/sandbox.toml
schema = 1
[files]
write = ["skills", "work"] # it may add skills
read = ["instructions", "chats"] # nor may its memory note anythinglnk agent start --sandbox sandbox.tomlThe whole of Home
write = ["."] is the whole files folder, its Home: an agent whose
files folder is a repository (lnk agent start --run.files <repo>) changes
any file of it.
Its own folder
Its instructions/, skills/ and chats/ are in its own
folder beside Home (~/Link/Agents/<agent>/agent), named as Home's
folders are: beside ., "instructions" or "skills" lets it change
those, and chats/ is never written but by its harness.
Only its own conversation
Of chats/, each conversation reads only its own folder, as
chats/telegram-42/, never another conversation's. A stranger's
conversation reads none, nor does a call whose harness doesn't say
which conversation it's made in.
What it tells the model
At the start of each session the tool tells the model that paths are relative to the files folder, which folders it may write, and which teams' folders it reaches and how. These come from the same grants the sandbox holds to, so the model never has to guess an absolute path.
Its sandbox
Its calls run in a sandbox made from that file, with no network, so the
sandbox holds to [files] whatever the tool is asked. One sandbox
serves a session's calls, started at its first call, and runs nothing
but File itself.
Dot files a person's tools run
File never writes .git, .envrc, .vscode or .idea, at any depth
and in any case of their letters. Git, direnv and editors run what's in
them as you, outside any sandbox, so a write there is refused before
anything is made on the way. The sandbox keeps them read only too
(what runs outside from a project).
Links, sizes and pipes
File never follows a link, reads and writes text files up to 4 MiB,
and reads images and PDFs up to 2 MiB. An edit that would make a
file larger is refused before it's made, and a pipe is never read or
waited on. A write reaches the disk before it replaces the file, keeps
the file's mode, and never keeps a setuid, setgid or sticky bit.
A file changed since it was read
A write or an edit of a file the session read or wrote is refused
when the file has changed since, by you or by another of the agent's
conversations, even where the text an edit replaces is still there.
The model reads it again, then writes. A write of a file the session
never read replaces what's there, and an edit of one changes it. An
edit is also refused if the file changes before the new text is in
place.
Home in a bucket
Where your agent's files folder is kept in a bucket instead of on the
machine that runs it, on a cloud that runs agents only while they
answer, the same five tools reach it through the files bridge: a program
outside the sandbox that reaches the bucket and nothing else, each call
proved as your agent. The tool accesses Home remotely and can keep a
file’s text in session memory while paging a read.
The paths, the folders [files] lets it write and the sizes are the
same, held by the same check. A bucket holds no hidden files, so there
are none to read, write or skip.
Its instructions and skills there
Such a cloud keeps your agent's instructions/ and skills/ in its
store, apart from Home, so the tools reach them through the storage
bridge instead: the program outside the sandbox that already keeps its
conversations, each call proved as your agent, so it reads and writes
your agent's files alone. The paths are the same as on a machine, and
your agent changes them only where [files] names them, as it does
there. A glob or grep finds them when its path names one, as
skills; with no path it looks in Home alone.
Its teams' folders there
Its teams' folders are at teams/<team>/ as on a machine, reached
as the cloud says your agent is on each team at that call, and another
account's team at teams/<account>/<team>/, where your agent reaches
what that team's owner let it. A glob or grep with no path looks
in its own files folder alone.
A file changed meanwhile
A write uses the version that this session last read or wrote and
refuses a changed target. For a file the session has never seen, it
reads the current version first, or uses an absence condition for a new
file. An edit reads the current text and conditions its commit on
that read, preserving other text around the exact match. A concurrent
change between either operation’s read and commit is refused.
Reading on
A read that goes on from a later line (offset) gives the rest of the file as
your agent read it from its first line, so all its pages are of one
version and the bucket is read once for them. Reading from the first
line again reads the file anew, as does a read after your agent
changes the file.
Reach its team's folder
On a team, your agent's
paths reach the team's shared folder at teams/<team>/, as
teams/research/drafts/report.md. It reads and writes only the
folders of it its sandbox file grants, [teams.<team>], which
lnk agent team add writes.
lnk agent team add research --member writer --write drafts --read sourcesTerminal Actions
lnk agent file exposes File actions for the selected agent. Read an action’s JSON arguments from a file with --request <file>, or from standard input when the flag is omitted. The action uses the running agent’s configured tool and grants.
Choose an Action
lnk agent file read, lnk agent file write, lnk agent file edit, lnk agent file glob, and lnk agent file grep use the corresponding calls described above. Use --agent work to select another agent and --json for machine-readable output.
More about it
Agents Security has the guarantees and gaps, and Decisions why it works this way. To work on its code, see Developing Link File, and when it can't write or read a file, Troubleshooting.