---
name: agentreel
description: Where generated media goes. Use whenever you generate, render, download or export an image, video, audio file, screenshot or working document, so it lands in the AgentReel library instead of the repository and the person can see it.
---

# AgentReel

The person you work for keeps everything agents make in AgentReel: a library folder outside
their repositories, one project folder per repository, shown live in the AgentReel app.

## Where to save

Ask for the folder; don't build the path yourself. If `agentreel` isn't found, it is at
`~/.local/bin/agentreel` (or `/Applications/AgentReel.app/Contents/MacOS/agentreel`).

    agentreel dir videos             # this repository's videos folder, created if missing
    agentreel dir images/promo-v3    # a batch subfolder
    agentreel dir --project NAME files   # outside a repository

Inside a repository, `agentreel dir` prints the project folder linked to it. The link lives in
the repository's own `.git/config` (`agentreel.folder`, never committed) and in the folder's
`.agentreel.json`, so it survives the person renaming the project in the app, and every
worktree of a repository maps to the same folder. A repository that isn't linked yet gets a
folder named after it, linked on the spot.

    images/   stills, thumbnails, screenshots, image generations
    videos/   renders, clips, avatar output
    files/    audio, documents, exports and working files

Put a batch of related output (a render run, a set of variations, extracted frames) in its own
dated subfolder, such as `$(agentreel dir videos)/promo-v3-2026-09-30/`, so it arrives as one
folder instead of hundreds of loose files. Give files names a person can recognise
(`hero-dark-1080x1920.png`, not `out.png`). Render straight to the final path:
`--output "$(agentreel dir videos)/<name>.mp4"`. If the person has made their own subfolders,
save into one when it plainly fits.

## Say how it was made

Record what produced each file you save, so the person (and AgentReel's organizer) knows what it
is without opening it. Either save through AgentReel, which moves the file into this repository's
folder and records the note in one step:

    agentreel save out.mp4 videos/promo-v3 --prompt "<the prompt>" --model "<model>" --task "<what it's for>"

or, when you rendered straight to the final path, add the note afterwards:

    agentreel note "$(agentreel dir videos)/promo-v3/hero.mp4" --prompt "..." --tool hyperframes --task "..."

The note is stored on the file itself and follows it through moves. The repository, commit and
agent are filled in for you.

## Rules

Never write generated media into the repository. When the code needs an asset at a path, copy
it there and ignore that path in git; the original stays in the library.

Never delete, rename, reorganise or re-link anything in the library unless asked. The person
sorts, stars, groups and renames things in the app, and nothing may depend on a file staying
where it was saved.

Build trees, dependency folders, virtualenvs and caches don't belong in the library. The app
ignores folders like `node_modules`, `build` and `.venv`, so media left inside them is invisible.

## Showing the result

When you've made something the person should look at:

    agentreel reveal "$(agentreel dir videos)/<name>.mp4"   # select it in the app
    agentreel play "$(agentreel dir videos)/<name>.mp4"     # play it full-window

Also give the path in your reply.