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.