File Links Plugin

Makes files the agent generates or modifies downloadable and previewable in the web UI, lets you browse the configured repositories, and runs static web apps the agent builds.

What you see

Transcript cards after a tracked write: filename, size, kind, Download and Open in browser — plus ▶ Preview app when the file is an HTML entry
A Files control in the chat header (labelled Browse files in the overflow menu)
A ▶ Preview control in the chat header, once a conversation has a pinned app
A repo browser at /plugins/file_links/repos with a This conversation / All files toggle

The agent is told when a Download card appears, its own or an editor's save card: the tool result it reads says "The user now sees a Download card for <name> in the chat." A scheduled or other unattended run is told instead that the card waits in the conversation until someone opens it in the web UI. The terminal UI, Telegram and Slack show no cards, so the agent is told nothing there.

This conversation lists files this conversation actually wrote or saved. Uncommitted files the agent never touched stay out of that view. All files lists the directory and annotates entries with git status.

With Workspace Isolation, files that exist only in the conversation sandbox still appear and can be downloaded while that conversation's sandbox is alive.

Once the sandbox expires, a file the agent committed and pushed keeps working: the browser reads it back from the pushed commit, so it stays in This conversation and stays downloadable — as long as that commit has reached the repository Codumentor has on disk (it does once the push has been ingested, or when it went to a branch this checkout already tracks). A sandbox-only file that was never committed has no copy left after expiry and will 404 — commit and push anything you want to keep.

Download is capped at 100 MB (?force=1 overrides). Inline preview is capped at 5 MB.

Old Document Editor download links in existing transcripts still work: they redirect to this plugin. If you disable File Links, those links 404.

Running an app the agent built

When the agent writes a static web app — index.html plus its scripts,
stylesheets and assets — the preview runs it instead of showing its source.
Clicking the entry file in the repo browser shows the working app in the right
pane with a Full screen button; Source and Diff stay one click away.

Four ways in, all of them the same preview:


Full screen in the browser pane	the exploratory path — "what is this file?"
▶ Preview app on a transcript card	right where the file was written
`/preview [path]`	the named path. Works while a turn is running, which is the point: you poke the app while the agent keeps building. With no argument it reopens the conversation's pinned app. Also available as `/app`.
the agent calling `preview_app`	the agent hands over a running app rather than a file path — it knows whether the entry is `webapp/index.html` or `webapp/dist/index.html`, and which directory to serve

In full screen a small floating bar — drag it by the handle, double-click to
reset, collapse it to a pill — carries Reload (with a count of files the agent
has changed since you opened it), viewport presets for checking a responsive
layout, a console badge that opens the app's console.* output and errors,
Set as default, Open in new tab and Close.

Open in new tab is the one control that steps outside the sandbox: the app
opens as an ordinary page rather than inside the framed preview, so it can
navigate itself anywhere — including off-origin with data in the URL, which
nothing in a browser prevents. It is still cookie-free and still read-only, but
prefer the overlay for an app you have not read.

Set as default pins that entry as the conversation's app. The chat header
then grows a ▶ Preview action that reopens it, and the pin is remembered for
that conversation — not for you, and not globally — so it is still there
tomorrow.

Console output from the previewed app is shown to you, never fed back to the
agent on its own. Ask the agent to fix this puts the text in the chat input and
shows you exactly what it will send; you press Send.

What the preview can and cannot do

A previewed app runs in a sandboxed frame on a second origin, so it holds no
session cookie, cannot touch the Codumentor page around it, and cannot make
network calls anywhere except back to its own files. It is served read-only from
one directory, and every request is re-checked against your access to that
repository — so a preview stops working the moment that access does.

A previewed app therefore cannot load anything from a CDN — no off-origin
script, stylesheet, font or image, and no fetch to a third-party API. That is
deliberate, not a bug: it is what stops repo bytes leaving through the app. The
console badge shows the blocked requests, so an app built against a CDN reads as
"these things were refused" rather than as a mystery blank page. Vendor the
assets, or point the app at files it serves itself.

Full fidelity — localStorage, history.pushState(), workers, root-absolute
asset paths like <script src="/assets/index.js"> — needs that second origin
configured: see api.app_preview.
Without it the preview still runs, and relative assets still load, but
localStorage and the app's own fetch() do not; the overlay says so in one
line. Building with a relative base (Vite's base: './') is the one-line fix on
the app side.

Shared and exported transcripts show no preview — a share viewer is not the
conversation's owner.

Configuration

plugins:
  - module: codumentor.plugins.file_links
    class: FileLinksPlugin
    args:
      enabled: true
      # tracked_tools: ["write_file", "replace_in_file", "doc_save", "client_fs_copy_from_repo"]
      # preview_tool: true

Parameters

Key	Type	Default	Description
`enabled`	bool	`true`	Master switch.
`tracked_tools`	list of strings	`write_file`, `replace_in_file`, `doc_save`, `client_fs_copy_from_repo`	Tool names whose writes produce cards and This conversation entries.
`preview_tool`	bool	`true`	Offer the `preview_app` tool to the agent. Its definition sits in every request, so set this to `false` on a deployment that wants the preview only from the UI and the `/preview` command. Withheld anyway when `api.app_preview.enabled` is `false`, and never offered to subagents.

The preview itself is configured under
api.app_preview, not here:
api.app_preview.enabled: false removes the preview, the /preview command and
the preview_app tool entirely, leaving the download / view / browse surface
untouched.

Most write-style tools work if the path is in file_path, path, or filename. client_fs_copy_from_repo is tracked by its server-side source_path (the repo file being copied to the user's folder).

The XLSX and PPTX editors show their own save cards. Add xlsx_save / pptx_save here if you also want those files in This conversation.

Disabling

plugins:
  - module: codumentor.plugins.file_links
    class: FileLinksPlugin
    args:
      enabled: false

Or disabled_plugins: [file_links].

Keep the plugin enabled if you retain old transcripts with Document Editor download links.