Getting Started

Download Shoulders, open a folder, and start writing.

Install

Shoulders is a desktop application. Download the latest version from the download page for macOS, Windows, or Linux. It installs as a single native binary — no runtime dependencies.

On macOS, drag the app to your Applications folder and open it. On first launch, macOS may ask you to confirm since the app is downloaded from the internet. Right-click the app and select "Open" to bypass Gatekeeper.

Open a workspace

A workspace in Shoulders is just a folder. There is no proprietary project format, no database, no import step. Open any folder on your filesystem, and that folder becomes your workspace.

Launch Shoulders. You will see the launcher screen with an Open Folder button.

Click it and select any folder — an existing project, a new empty directory, whatever you like.

The folder opens as your workspace. Every file inside it appears in the sidebar.

You can also clone an existing repository from the launcher screen. Shoulders tracks version history automatically when you open a workspace — every change is versioned from the start.

The interface

The layout has three regions. All three are resizable and collapsible.

Left sidebar — file explorer and reference library. Toggle with Cmd/Ctrl+B.
Centre — the editor area. Supports multiple tabs and split panes.
Right sidebar — AI chat, terminals, comment threads, and backlinks. Toggle with Cmd/Ctrl+J.

The footer bar shows the current git branch, review/direct mode toggle, pending AI edit count, word and character counts, and cursor position. A zoom control sits in the centre. The header bar has a search field (Cmd/Ctrl+P) and a settings button.

Create your first file

Click the + button at the top of the file tree, or right-click inside the sidebar and choose "New Document." Shoulders creates a Markdown (.md) file by default. Type a filename and press Enter.

Start typing. Changes are saved to disk automatically — one second after you stop typing. Press Cmd/Ctrl+S to also create a version history checkpoint.

Set up AI features

AI features (inline suggestions, chat, comment threads) need access to an AI provider. Two options:

Shoulders account — create a free account at shoulde.rs (includes $5.00 free). No API keys to manage.
Your own API keys — add keys for Anthropic, OpenAI, or Google in Settings (Cmd/Ctrl+,) → Models.
Private or self-hosted models — connect to any OpenAI-compatible endpoint (local LLMs, institutional servers, private deployments) via custom URLs in .shoulders/models.json.

See AI Setup for detailed instructions.

Keyboard essentials

Five shortcuts cover most navigation:

Action	Shortcut
Quick open (files, content, references)	`Cmd/Ctrl`+`P`
Toggle left sidebar	`Cmd/Ctrl`+`B`
Toggle right sidebar	`Cmd/Ctrl`+`J`
Save and commit	`Cmd/Ctrl`+`S`
Open settings	`Cmd/Ctrl`+`,`

See the full keyboard shortcut reference for everything else.