Talk about a note

Talk about a note with the people you share the notebook with, beside the note itself. Every message is a GitHub Discussion in the notebook’s own repository, so nothing about it lives anywhere but GitHub.

Open it

The column beside the note has three tabs — Note, Chat and Assistant — and one click switches between them. You can also use the speech bubble in the editor header, or ⌘K → Talk about this note. When someone replies while you are looking at something else, the Chat tab shows how many messages you have not read, and the header button gets a dot.

How it works

The first message about a note starts a discussion in the repository’s General category, titled after the note and linking to its file. Every message after that is a comment on it, and a reply is a reply on GitHub.
Collaborators can answer here or on github.com and in GitHub’s phone app. Both places show the same conversation.
New messages are checked for every fifteen seconds while the Chat tab is open, every minute while it is not, and not at all while the browser tab is in the background. Coming back to the tab checks at once.
Messages are Markdown. Enter starts a new line and ⌘↵ sends.
This device remembers which messages you have seen, so the unread count is per device.

Turn on Discussions

Discussions is a repository setting, off by default. ForkLeaf does not change repository settings for you, so the Chat tab links to the right page: on GitHub, open the repository’s Settings, tick Discussions under Features, then press Check again.

The Lounge: every conversation at once

⌘K → Open the Lounge, or the Lounge button in the Chat tab, shows every conversation in the notebook: the ones about notes and the ones people started on github.com.

Channels are the repository’s Discussions categories, each with an unread count. Unanswered lists questions in Q&A-style categories that nobody has answered yet.
Threads show which are unread, answered, about a note, or locked.
A thread opens with its first post and a line marking what is new since you were last here. From there you can reply, mark an answer, open the note it is about, or save it as a note.
New thread starts one in any channel except Polls, which GitHub does not let apps create.

The first time you open the Lounge on a device sets a starting point. Threads that were quiet before then are not shown as unread, so a busy repository doesn’t open with hundreds of old threads marked new.

Answers

In a category that takes answers, such as Q&A, the person who asked and the repository’s maintainers see Mark as answer under each reply. This works in the Chat tab and the Lounge, and it is the same answer GitHub shows.

Save a conversation as a note

Save as note writes the conversation into conversations/: every message in order, who said it and when, the answer marked, and a link back to the discussion. Messages a maintainer hid are left out.

If the assistant is set up, you can tick Add a summary to put decisions, to-dos and open questions at the top. This sends the conversation to your model provider with your own key, and it appears in Receipts. It is off unless you tick it.

Who can take part, and who can read it

Repository	Who can read	Who can write
Private	Its collaborators	Its collaborators
Public	Anyone	Anyone signed in to GitHub

The Chat tab says so when a repository is public. A maintainer can lock a conversation or hide a message on GitHub, and the Chat tab respects both.

Encrypted notes never get a conversation. Anyone who can read the repository can read a discussion’s title and messages, and those are exactly the people an encrypted note is kept from.

Talk about a passage

Select some words in a note and press Discuss, the button that appears under the selection. The Chat tab opens with the passage quoted, and your first message starts a thread about those words alone.

The Chat tab lists a note’s passage threads above its own messages, marking new and answered ones. Click one to read it in the Lounge.
Show in note selects the passage on the page. If the words have since been rewritten, the thread says Passage changed since instead of pointing at the wrong place.
A passage is matched by its words, ignoring spacing, so it is found in rich text, in the source view and after a paragraph is re-wrapped.

[[Links]] in any message, in the Chat tab or the Lounge, open the note they name.

Comments on published books and gardens

In Publish as a book…, tick Comments on every page. Readers sign in with GitHub to comment, through giscus, an open-source comments widget built on GitHub Discussions. Each page’s comments are the same conversation as its note’s Chat tab, whichever side starts it.

The notes repository must be public, so readers can see the comments.
Discussions must be switched on.
The giscus app must be installed on the repository. The dialog links to it.

The comments load giscus’s script on the published page, and only when a reader scrolls down to them. Pages published without the box ticked load nothing extra.

AI assistants

An assistant connected over MCP can read a note’s conversation, list every conversation or only the unanswered questions, and read one in full. It can reply too, under your name. It is told to do that only when you ask, after showing you the text, and it cannot reply on a read-only connection.

Live updates and notifications

On forkleaf.in, new messages arrive as they are posted: a reply shows up in the Chat tab and the Lounge within a few seconds, without a refresh. The dot on the bell (🔔, in the Chat tab and the Lounge) is filled while that is working. When it is hollow, ForkLeaf checks for new messages every 15 seconds instead.

The bell also turns on notifications, per repository and per device:

Setting	You are told about
Off (the default)	Nothing
Threads I'm in	New messages in threads you have opened or written in on this device, and messages that @mention you
Everything	Every new message in the notebook

You are only notified while ForkLeaf is not the window in front, and never about your own messages, edits or deletions.
A busy thread updates one notification instead of stacking many. Clicking it opens the thread.
The tab’s title also counts new messages, for example (2) Editor. This works even if your browser blocks notifications, and clears when you look at the tab.
With notifications on, ForkLeaf stays connected while the tab is in the background, because that is when they matter. With them off, it disconnects until you come back.

Running your own ForkLeaf

ForkLeaf signs in as a GitHub App, and a GitHub App can only do what its permissions allow. To use conversations, give the App the Discussions: Read and write repository permission. Accounts that already installed it must then approve the new permission, which GitHub asks them to do. Until they do, the Chat tab explains that ForkLeaf is not yet allowed to use Discussions in that repository.

Live updates

In the GitHub App’s settings, turn on Webhook. Set the URL to https://<your host>/api/gh/webhook and choose a secret (openssl rand -hex 32).
Under Subscribe to events, tick Discussion and Discussion comment.
Set GITHUB_WEBHOOK_SECRET to the same secret, and set UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN. A webhook and a reader’s live stream can run on different server instances, and the shared store is what connects them.

Each delivery’s signature is checked before anything is read, and a delivery GitHub sends twice is recorded once. ForkLeaf keeps a short log per repository for a day: the discussion number, what happened, who did it, and the first 140 characters of a new message. Only people who can read the repository can open that repository’s live stream. The stream checks for news every 3 seconds with a single store read, which comes to about 29,000 Upstash commands per day for a tab left open all day.