Service connectors

A service connector turns a third-party service into a read-only file tree, so the same browse, preview, and search you use over your local disk work over a service like GitHub — no browser tab required. Open a repository, drill into Issues/42/, read issue.md, scroll the comment thread, all inside Sheru.

Sheru ships connectors for GitHub, Linear, and Notion. This page walks through GitHub as the worked example — connecting it, what the file tree looks like, and the commands you can run on what you're browsing; Linear and Notion have their own short guides linked below.

What a connector is#

The sidebar mixes your local disk with everything you connect — remote filesystems and service connectors. A service connector is the kind that projects an outside service as a read-only set of folders and files. It can't modify your Mac — it only shows you the service's data as files, and runs the specific service actions described below.

Connecting GitHub#

GitHub sign-in rides the official GitHub CLI, so Sheru stores no tokens of its own — it uses the login you already have.

First, install and sign in to the GitHub CLI:

• Install it (for example with brew install gh).
• Sign in by running gh auth login.

Then connect it in Sheru:

1. Open Settings (⌘,) ▸ Connectors.
2. Choose GitHub ▸ Connect.

If the GitHub CLI isn't installed or you haven't signed in, the Connect button stays disabled with a reminder to set it up first. Once connected, a GitHub connector appears in the sidebar.

By default the connector lists every repository your GitHub account can see; you can narrow it to specific repositories in Settings.

How the file tree is laid out#

The GitHub connector maps repositories, issues, and pull requests onto folders and files:

• The top level lists one folder per repository, as owner/repo/.
• Inside a repository: Issues/ and Pull Requests/.
• Inside those: one numbered folder per issue or PR.
• Inside an issue or PR: an issue.md with the full text, and a comments/ folder.
• Inside comments/: one markdown file per comment, numbered in order.

So browsing into octocat/hello-world/Issues/42/ gives you issue.md plus a comments/ folder, with each comment as its own readable markdown file. issue.md opens as formatted markdown, with the issue's title, state, author, labels, and links at the top.

Long lists of issues and pull requests load a page at a time — scroll to the bottom and use the load more bar to fetch the next page.

Read-only, with actions#

A service connector is a read-only view — you can't rename, move, trash, edit, or upload to it. The terminal (⌘J) is also unavailable on the GitHub connector, since there's no shell to attach to a remote service. (This is stricter than a remote filesystem, which accepts uploads — and, on SFTP, full in-place edits.)

Browsing isn't the whole story, though. On a GitHub issue you can run service actions right from Sheru:

• Add comment — post a comment on the issue.
• Close — close the issue.

These run through your GitHub sign-in against the service itself; after one completes, the affected folder refreshes so you see the result immediately.

Managing connectors#

• Show in sidebar. Each connector has its own visibility toggle. Hiding it keeps it connected but removes it from the sidebar.
• Add or remove. Connect and disconnect from Settings ▸ Connectors.
• Restored on launch. A connector you've already set up is reconnected automatically the next time you open Sheru. If it can't reconnect — for example, you've signed out of the GitHub CLI — it's quietly skipped rather than blocking launch.

Connecting other services#

Beyond GitHub, Sheru connects to a couple of services with a personal access token you generate in your own account and paste into Sheru — stored locally, never sent anywhere but the service. Each has a short setup guide:

• Connect Linear — teams, issues, and comments.
• Connect Notion — pages and databases.

You start each from Settings ▸ Connectors ▸ Add Connector, where the same guide link is one click away.

Building your own#

Want to project a different service? Connectors are an extension point. See Extensions for the model and how to author one.