---
title: "Hooks and LLM connections"
description: "A Hook is an instruction a Project gives to an LLM for every new capture. Bigshot runs it with the screenshot attached: Claude Code or Codex on your Mac, or the Anthropic or OpenAI API. Hooks need a Licence."
url: https://www.bigshot.pics/docs/hooks
---
# Hooks and LLM connections

A **Hook** is an instruction a Project gives to an LLM for every new capture.
Bigshot runs it with the screenshot attached: Claude Code or Codex on your
Mac, or the Anthropic or OpenAI API. Hooks need a Licence.

## Connections

Connections are set once, in Settings › General › **LLM Connections**, and
shared by every Project.

| Connection | Setup | Status |
|---|---|---|
| Claude Code | Found in `~/.local/bin`, `~/.bun/bin`, `~/.npm-global/bin`, `/opt/homebrew/bin` or `/usr/local/bin`. **Choose Binary…** to point at another. | *Not installed*, *Connected*, or *Sign in required* |
| Codex CLI | As above | As above |
| Anthropic API | Paste a key and **Save** | *Credential saved in Keychain* |
| OpenAI API | Paste a key and **Save** | *Credential saved in Keychain* |

The CLIs use their own sign-in. Sign in with `claude` or `codex` in Terminal
first. API keys are stored in the macOS Keychain.

## Adding a Hook

Settings › Projects › **Edit…** › **Add Hook**. Each Hook has:

| Field | Notes |
|---|---|
| Enabled | Off skips it |
| Name | Shown in Hook Runs |
| Connection | Claude Code, Codex CLI, Anthropic API or OpenAI API |
| Access | **Read only** or **Workspace edits**. CLIs only; APIs are always read only. |
| Model | Optional for CLIs (their default is used). Required for APIs. |
| Timeout | 1 to 60 minutes. 15 by default. |
| Prompt | What to do with the screenshot |

Use the arrows to order Hooks, and the trash button to remove one.

### What a Hook receives

Your prompt, followed by:

- the Project name and workspace path;
- the screenshot: a file path for Claude Code, an attached image for Codex,
  image data for the APIs;
- what Bigshot knows about it — source app, web address, your note and OCR
  text — marked as evidence, not instructions;
- a request for a short structured description: summary, title, detected
  text and tags.

There are no placeholders to fill in the prompt.

### Access

- **Read only** runs Claude Code in plan mode and Codex in its read-only
  sandbox.
- **Workspace edits** lets Claude Code accept edits and gives Codex its
  workspace-write sandbox.

Both run in the Project's workspace, without saving a session.

## When Hooks run

- Hooks run on new captures in the Project, in order, one at a time. Captures
  in different Projects run in parallel.
- If the Project has **never** turned screenshot sharing on, every capture
  runs its Hooks.
- Once sharing has been on, only tagged captures that have been shared run
  Hooks. In Review first mode, that means after **Share now**.
- Moving a capture into a Project does not run that Project's Hooks.
- Excluding a capture, retagging it, or turning sharing off cancels runs
  that have not finished.
- **Pause Hooks** in the menu bar stops new runs from starting. **Resume
  Hooks** starts them again. With the pointer on the island, `H` does the
  same and shows a short notice saying which.

## Hook Runs

Right-click a Project capture and choose **View Hook Runs…**. Each run is
listed with its status: *queued*, *running*, *succeeded*, *failed*,
*interrupted* (Bigshot quit during it) or *cancelled*.

The detail pane shows the summary, title, detected text and tags the model
returned, its raw reply, and a diagnostic log. **Cancel** stops a queued or
running run. **Retry** runs a failed one again.

What a Hook produces is shown here. It is not written to the workspace or the
index; a Hook with **Workspace edits** access changes files itself.

Logs are kept in `~/Library/Application Support/Bigshot/Hook Runs/` and are
removed with their capture.

## Examples

Each example is a Hook prompt. Ones that write a file need **Workspace
edits** access on a CLI connection, because a Hook's reply is only shown in
Hook Runs. The paths are relative to the Project's workspace.

### Collect the people and contact details in screenshots into a CSV

*Read this screenshot. For every person, company, email address, phone number
or username visible, add one row to `data/contacts.csv` with the columns
`captured_at,name,email,phone,company,source_app,notes`. Create the file with
that header if it does not exist. Leave a cell empty when it is not on screen,
never guess, and skip the screenshot if it shows none.* (Claude Code or
Codex, Workspace edits)

The source app and OCR text Bigshot passes along help fill `source_app` and
catch small text. Keep this Hook on a Project whose captures you are happy to
send to the connection you chose. Personal data in a screenshot goes wherever
that connection sends it.

### Keep an error log

*If this screenshot shows an error, a stack trace or a failed request, append
a line to `notes/errors.md`: the message, the app or URL, and the file in
`src/` most likely responsible. Do nothing otherwise.* (Claude Code,
Workspace edits)

### Pull out numbers

*Add each figure in the screenshot to `data/metrics.csv` as
`captured_at,label,value,unit`. Ignore decoration and axis ticks.* (Codex,
Workspace edits)

### Name and tag, with no file changes

*Give the screenshot a short title and tags for the product area, the screen
and anything that looks broken.* (Anthropic or OpenAI API, Read only)

The title and tags appear in Hook Runs for the capture.

### Review against a spec

*Check this screenshot against the design tokens in `src/theme.ts` and list
any colour or spacing that does not match.* (Codex, Read only)

Tips: say what to do when there is nothing to extract, ask for exact column
names, and give one Hook one job. Add another Hook rather than a longer
prompt.