---
title: "Projects and screenshot context"
description: "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."
url: https://www.bigshot.pics/docs/projects
---
# 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](https://www.bigshot.pics/docs/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.

1. **Choose the workspace folder.** Bigshot names the Project after it; you
   can change the name. Pick one of eight colours.
2. **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.
3. **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.
4. **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:

```text
.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.

## Tags

A **task tag** names a piece of work. Each Project has its own tags, and a
capture can carry several. The **active tag**, picked in the island's tag
pill, is put on every new capture. Create one by typing in the pill's **New
tag** field and pressing Return; it becomes the active tag.

See [The Library](https://www.bigshot.pics/docs/library#tags) for adding, removing and archiving tags.

## 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:

```json
{
  "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
`<!-- Bigshot context: begin -->` and `<!-- Bigshot context: end -->`.

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](https://www.bigshot.pics/docs/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.