# Files extension The [Python files plugin](../priv/python/albedo_plugins/files.py) provides bounded reads, exact edits, directory listings, and searches in the kernel's environment. Relative paths resolve in that environment's working directory. See [workspaces](workspaces.md). A file attached to a chat message reaches the model as a saved path under the daemon home. The model can read that absolute path with `files.read` or other kernel code. Attaching adds no plugin API and no sandbox. See [saved pastes and uploads](kernel-state.md#saved-pastes-and-uploads). ## Read `files.read(path, start_line=1, end_line=None, limit=None, max_chars=16000)` returns numbered lines. `limit` counts lines and `max_chars` bounds output. The maximum character budget is 200,000. If the budget stops the read, the result identifies where to resume. `files.ls` lists one directory and excludes hidden entries by default. The implementation is in [`Files.read` and `Files.ls`](../priv/python/albedo_plugins/files.py). ## Uploaded images `await files.image(index=0, entry=None)` returns the original bytes of an image uploaded in the calling session. Indices start at zero. Without `entry`, it uses the latest user message containing images, looking past later text-only messages. Pass a user message's transcript position to read an older upload explicitly. An unavailable image, another session's entry, or an out-of-range index raises `FilesError` with code `image_unavailable`. Invalid Python arguments raise `ValueError`. Assign the bytes before using an image library, for example: ```python import io from PIL import Image original = await files.image() picture = Image.open(io.BytesIO(original)) ``` The call uses the session's host connection, so the kernel does not need a path on the daemon's filesystem. Images stay in the existing image store; fetching one creates no extracted file or additional image-store entry. User-upload bytes remain separate from provider-sized image fits and tool screenshots. The transcript reader in [conversation.gleam](../src/albedo/daemon/conversation.gleam) owns the selection, and the files extension exposes it through its existing host routes. The default search pages row identities through an upload-candidate index, then reads one payload at a time. The candidate tag also covers legacy inline images; prose containing it is decoded and skipped. The search resumes between Python awaits, so cancellation stops the look-back between pages. ## Edit `files.edit` replaces an exact string or applies an ordered list of replacement pairs. A missing or ambiguous match fails before publication. A list is evaluated in memory before the file is replaced. `line_hint` can select among occurrences for a single edit. `files.write` creates or replaces the entire file and creates parent directories. [`_snapshot` and `_replace`](../priv/python/albedo_plugins/files.py) compare the file before replacement and refuse a detected concurrent change. The comparison and `os.replace` are separate operations, so another writer can still change the file between them. The temporary file is synced and retains the original mode. ## Search `files.find` searches contents and `files.paths` searches names. Both return work that must be awaited. The plugin uses ripgrep when available and has a Python fallback. `find` excludes hidden and ignored files by default, accepts literal or regular-expression searches, and returns bounded results. External search commands run as supervised [jobs](kernel.md) with a 30-second timeout. See [`Files.find`, `Files.paths`, and `_run`](../priv/python/albedo_plugins/files.py). ## Credential boundary `files.read` and content search refuse the configured credentials file, and search filters that path from results. This is a boundary of those operations, not a filesystem sandbox. Other processes and operations have their own permissions. See [`_secret` and `_refuse_secrets`](../priv/python/albedo_plugins/files.py) and [settings](settings.md). ## Related pages - [All topics](README.md) - [Change guidance](contributing.md) - [The detached kernel](kernel.md) - [Workspaces](workspaces.md)