Ask for a file
Ask for the thing you want to see, for example:
- "Mock up the new pricing page."
- "Investigate why the sprite is wrong and write it up."
- "Compare the two approaches."
The agent decides when a turn's result is worth a file of its own. Ordinary answers stay in the chat.
To change a file, ask for the change. The agent rewrites the same file and its version counts up.
The four kinds
| Kind | What it is | How Sensei shows it | Size limit |
|---|---|---|---|
| Document | Markdown the agent writes | Formatted text | 1 MB |
| Mockup | A self-contained HTML page the agent writes | The page itself, in an isolated frame | 1 MB |
| Image | A .png, .jpg, .jpeg, .gif or .webp file | The picture, with Open full size | 25 MB |
| Video | An .mp4 or .webm file | A player with controls | 25 MB |
A mockup runs in isolation. It has no access to your app or to Sensei. The Preview tab is where the real app runs.
SVG is not one of the image kinds. For a drawing that needs to move or respond, ask for a mockup.
The Files tab
The Files tab sits beside Preview and Desktop in every session. It lists the session's files, most recently changed first, then the files its ticket points at. A collapsible QA evidence group with a count sits at the bottom.
Each row shows the agent's title and a line about the file, such as "Document, v2". Files appear while the agent works, without waiting for its reply. Each file also leaves a card in the transcript, at the point in the turn where the agent wrote it. Press Open on the card to read it in the tab.
Anyone who can open the session can read its files. The tab stays readable when the sandbox is paused and after the session is Completed or Archived.
Opening a file shows its name in Files and a line such as "Version 2, Sam Lee, today at 09:14", with Copy link and Download. A document or a mockup also offers Copy. On a phone, the list and the file are two screens.
Folders in Files
The same files sit in Files under Sessions:
Files › Sessions › <repository> › <session title> › <name>.<ext>
The folders appear the first time the agent writes a file. The session folder follows the session's title and repository each time the agent writes.
- The QA Report sits directly in the session folder, as
qa-report.html. The tab calls it QA Report. - The Testing Checklist, the other QA files and the recordings QA uses sit in a QA evidence folder inside it.
- A session in your personal space writes to your Personal Files, never to a workspace.
Pages do not link to the folder. Open it from Files.
Who can change what
| What | Who can change it |
|---|---|
| A file the agent wrote | Any member can open, download, rename, move, replace or delete it in Files. |
| The QA Report and QA evidence | Nobody. They open and download only, with a lock icon that reads "Kept with the test run". Sensei updates them itself. |
| Sessions, a repository folder, a session folder, QA evidence | Nobody renames, moves or deletes them. You can upload or move files only into a session's own folder. |
The rules hold for every caller, in the app and through the API.
The tab keeps listing a file the agent wrote wherever it now is in Files, under the agent's title. A file you upload into the session folder yourself does not join the tab.
When the agent writes a name again, it revises the file wherever you moved it, and keeps your new name.
Deleted, replaced and expired files
Only delete asks you to confirm.
| State | The row says | Opening it |
|---|---|---|
| Deleted | "Deleted by Sam Lee" | Says who deleted it and when. Files keeps no earlier versions, so the text is gone. The transcript card reads "Deleted by Sam Lee, today at 09:14". |
| Replaced | "Document, v2. Replaced" | Shows the new file, says who replaced it, and says the version the agent wrote is not kept. A transcript card for an older version adds "Now version 2". |
| Expired | "Video expired on 12 Nov 2026" | Says the recording is gone. The QA Report keeps the result of the check. |
A deleted file leaves Files, and only its row stays on the tab. If the agent writes that name again, it starts a new file. A replaced file becomes the agent's again the next time it writes that name.
Only QA recordings expire. A closed session's recordings are deleted 30 days after it ended. In an open session, a recording a newer QA run stopped using is deleted once that run is 30 days old. The row and the QA Report stay, and an expired recording no longer returns to a sandbox.
Moving a session back to Backlog deletes the files its agent wrote and keeps the files its ticket points at. Deleting a session leaves its files and folders in Files as ordinary content that members can manage. A mockup from a deleted session keeps its text, but the images and videos it names stop loading.
Versions
Sensei keeps only the current version of each file. A card in the transcript records the version that turn wrote, such as "version 2". Opening any card shows the current version. Earlier versions are gone.
The QA Report and the review report are one file each per session, and each run or review writes over it at the next version.
Put a file on a ticket
A Backlog ticket can point at a file in Files, such as a prototype from Sensei. Its agent reads the current version when the session starts, so there is no copy to keep in step. Ask Sensei to attach it, or run the command yourself:
kosuke sessions files attach <projectId> <sessionId> --file prototypes/board/a-columns.html
--file is a path in the Files of the project's workspace, or in your Personal Files for a personal space. A path to a folder attaches each file directly inside it, so --file prototypes/board attaches every variant in the folder.
- Only a Backlog ticket accepts it. A session that has started refuses it.
- Only Markdown, HTML, PNG, JPEG, GIF, WebP, MP4 and WebM files can be attached. Text files are up to 1 MB and the rest up to 25 MB.
- Nothing is attached when one of the files is of another type or was written by this session's own agent, or when its name without the extension clashes with another attached file. The error names the files.
The ticket lists the file under Files. Deleting the file in Files removes it from the ticket. If the agent edits its copy in the sandbox, the edit publishes as the session's own file beside the original.
Files in a new sandbox
When the session gets a new sandbox, Sensei writes its files back where the agent wrote them, so the agent can read and revise them. The files its ticket points at arrive at their current version. Past 100 MB in all, the oldest images and videos stay only on the tab.
Link to a file
Copy link gives an address that opens that file on the tab, which suits a pull request description. Whoever follows the link needs to be a member of the workspace. Older links keep working: ?artifact=<id or name> still opens the file, and ?tab=artifacts still opens the tab.
Share files outside Sensei
A share link for a session's preview carries its files too. The shared page offers App and Files. A visitor with no Sensei account can read both, and can download a file.
The shared page shows the files the session's agent wrote, QA evidence included. It leaves out deleted files and the files a ticket points at.
If the session is Completed or Archived, the shared page still shows its files. If the sandbox is paused, a visitor can read them while the app wakes up. Revoking the link removes access to both.
Files and attachments
An attachment is a file you send to the agent with a message. A session's file is something the agent writes back to you. Nothing in it is committed. Ask the agent to put code in the repository.
Read files from a script
To read a session's files from a script or an agent, use kosuke sessions files list and kosuke sessions files get. See Session files and Sensei CLI.