Setup

Configure AI access, models, privacy controls, and project-specific instructions.

Two ways to use AI

Shoulders needs access to an AI provider. There are two options — use whichever suits you, or both:

Shoulders account

You can sign up for a Shoulders account directly within the app (or at shoulde.rs) to use AI features without managing API keys. New accounts include free AI usage. Requests are routed through the Shoulders proxy, which forwards them to AI providers on your behalf. During the research preview, additional balance is available on request.

Bring your own API keys

Alternatively, supply your own API keys from one or more providers. Open Settings (Cmd/Ctrl+,) → Models:

Keys are stored securely on your computer. They are sent only to the provider's API — nowhere else. You pay the provider at their standard rates.

You can use both methods simultaneously. The model picker in the chat input shows all available models from your API keys and your Shoulders account.

Models

Seven models are available by default: Opus 4.6, Sonnet 4.6, and Haiku 4.5 from Anthropic; GPT-5.2 and GPT-5 Mini from OpenAI; Gemini 3 Pro and Gemini 3 Flash from Google. Which models appear depends on your configured keys and account.

The model list is defined in .shoulders/models.json. You can add custom endpoints by editing this file — private or self-hosted models, institutional AI servers, or local language models running on your machine. Any service that exposes an OpenAI-compatible, Anthropic, or Google API can be added with a URL and API key variable.

Usage and costs

Shoulders tracks every AI request and its estimated cost. The footer bar shows your monthly total — click it to open Settings → Usage for a detailed breakdown.

• Monthly breakdown — cost, token count, and call count per feature (chat, suggestions, comments, references) and per model.
• Trend — a bar chart showing the last 12 months of usage.
• Budget — set a monthly soft limit. The cost display turns amber when you approach it. It never blocks you from working.

If you use a Shoulders account, costs are deducted per request at real model-specific rates. Your balance can be viewed in the app via Settings (Cmd/Ctrl+,) → Account, or at shoulde.rs/account.

Privacy controls

Shoulders provides 28 AI tools across five categories (workspace, references, feedback, notebooks, web research). Each tool can be individually enabled or disabled in Settings → Tools.

Four tools transmit data to third-party services beyond your AI provider: web_search and fetch_url (via Exa), search_papers (via OpenAlex, with Exa and CrossRef fallbacks), and add_reference (via CrossRef for DOI lookup). These are clearly labelled as external. A single "Disable all external tools" toggle removes all four at once.

Disabled tools are removed from the AI's definitions entirely — the model does not know they exist and cannot attempt to use them.

Project instructions

Create a file called _instructions.md at the root of your workspace. Its contents are included in every AI interaction — chat, comments, and inline suggestions. Use it to set tone, define terminology, specify citation conventions, or provide project-specific context.

Changes take effect immediately — no restart needed. Access the file quickly from the model picker dropdown in the chat input.

System prompt

The file .shoulders/system.md contains the base system prompt used by all AI features. It is loaded when the workspace opens. You can edit it to adjust the AI's default behaviour. For project-specific context, _instructions.md is usually the better choice.