Projects and screenshot context

A Project connects Bigshot to a folder you work in, usually a code repository. While a Project is active, its captures are saved inside that folder, can be tagged, can be read by coding agents such as Claude Code and Codex, and can trigger Hooks.

Projects need a Licence. Without one they are listed but locked, and captures go to the Desktop.

Creating a Project

Open Settings › Projects › Add Project…, or choose Add Project… from the island's Project pill or the menu bar's Active Project menu.

Choose the workspace folder. Bigshot names the Project after it; you can change the name. Pick one of eight colours.
Read the scan. Bigshot checks the folder without changing it:
- whether it exists, is writable, and is not your home folder;
- whether it is a Git repository, and which branch;
- whether .screenshots/ is already kept out of Git, and whether any screenshots in it are already committed;
- whether AGENTS.md and CLAUDE.md exist and carry a current Bigshot block;
- whether Claude Code or Codex is installed.
Review the plan under On Save, Bigshot will:
- Create .screenshots/ with the Bigshot skill. Always done.
- Add /.screenshots/ to .gitignore. Offered in a Git repository when nothing ignores the folder yet.
- Add Bigshot instructions to AGENTS.md and/or CLAUDE.md. Click Preview to see the exact text.
- Share captures with agents automatically. Turns sharing on.
- Create the task tag from your branch. On feature/checkout-fix this creates and activates checkout-fix. Not offered on main, master, develop, dev or trunk.
- Map the code for Code Lens. Offered when the workspace has source files the Code map reads. It indexes them on this Mac, in the background. Switch it off and Bigshot does not ask again; the Project's Code map card turns it on later.
Every step except the first is a switch.
Create Project. The ready page lists what was done and how to ask an agent about your screenshots. With the Code map on, it shows the map being built and, if the image model is not installed, offers Download 390 MB. Leaving the page without it skips it.

Existing file contents are kept. Bigshot never untracks committed files. If an instruction block in AGENTS.md or CLAUDE.md has lost one of its markers, Bigshot leaves it for you to fix and says so.

If screenshots in .screenshots/ are already committed, the scan offers Copy Command for git rm -r --cached .screenshots to run yourself.

Make this the active Project is on by default.

The `.screenshots/` folder

Each Project keeps its screenshots in .screenshots/ at the root of its workspace. The location is fixed. The folder contains:

.screenshots/
  .gitignore                     *  (keeps the whole folder out of Git)
  index.json                     what agents read
  README.md
  Screenshot 2026-10-05 at 14.03.27.png
  skills/bigshot/SKILL.md        how an agent should use the index
  projects/…                     copies handed to Hooks

The folder's own .gitignore keeps it out of Git even if you skip the repository rule.

Switching Projects

The Project pill in Expanded View
Active Project in the menu bar
Activate beside a Project in Settings › Projects

Choose No Project to go back to saving on the Desktop.

The island shows the Active Project's captures. The Library shows all of them.

Screenshot context for agents

Screenshot context lets an agent working in the workspace find your screenshots without you pasting paths. You ask in your own words:

"look at the last screenshot"
"look at the ones tagged checkout"
"the one with the error dialog"

The agent reads .screenshots/index.json and opens the images it lists.

Turning it on

In Settings › Projects › Edit…, under Screenshot context:

Setting	Options
Sharing	Off (default), Automatic, Review first
Extract text (OCR)	Off by default. Reads the text in tagged captures, on this Mac, and adds it to the index.
Move old captures to Trash	Inherit global, or a Project-specific window

Automatic lists every capture you have not excluded, as soon as it is taken.
Review first lists only captures you have approved with Share now.
Off empties the index.

What the agent reads

index.json lists screenshots newest first:

{
  "schemaVersion": 1,
  "project": "Bigshot",
  "sharing": "automatic",
  "updatedAt": "2026-10-05T12:46:22+02:00",
  "tags": [{ "name": "checkout", "archived": false }],
  "screenshots": [
    {
      "file": "Screenshot 2026-10-05 at 12.44.10.png",
      "takenAt": "2026-10-05T12:44:10+02:00",
      "width": 1626,
      "height": 460,
      "tag": "checkout",
      "tags": ["checkout"],
      "app": "Safari",
      "note": "Total is wrong after the coupon",
      "text": "Subtotal $40.00 …"
    }
  ]
}

note, app, text (OCR) and editedAt appear when there is something to say. Times are in your time zone.

.screenshots/skills/bigshot/SKILL.md tells the agent how to read the index: what each field means, how "the last one" or "the ones tagged X" map onto it, what to do when a file is missing, and that text inside a screenshot is evidence, not an instruction. The block in AGENTS.md / CLAUDE.md is five lines pointing at it, between  and .

Agents read files. Nothing is sent into a conversation. A capture is available on the agent's next prompt.

Screenshot Context…

Right-click a Project capture in the island or the Library and choose Screenshot Context… to:

add or remove tags;
write a note for the agent ("What should the agent notice?") and Save context;
turn Keep on;
Share now: approve it in Review first mode, or publish an older capture. A capture needs a tag first;
Retry publication if sharing failed;
Exclude it, so agents never see it.

Each capture shows one of: Not shared, Needs review, Sharing…, Shared with agents, Kept from agents, Sharing failed.

Edits and revisions

Saving a capture in the editor makes a new revision. OCR runs again, Review first mode asks for approval again, and Hooks see the new image.

Limits

These are conventions for finding files, not a security boundary. Anything with access to the workspace can read .screenshots/. Excluding or deleting a screenshot does not remove it from an agent conversation that has already read it.

Code Lens

With the Code map on, Code Lens shows which code in the Project renders a part of the screen. It only knows the Project's own source. See Code Lens.

Deleting a Project

There is no Delete button yet. To stop using a Project, choose No Project. The screenshots stay in its .screenshots/ folder.