Merenda is a desktop GUI toolkit written in Nim, inspired by Cocoa and OpenStep.
It gives you buttons, text editors, tables, menus, and layouts for building desktop
apps, with themes you can change to suit your app. Its public module is called
NimKit: import merenda/nimkit.
The project is under active development, targeting macOS, Linux, FreeBSD, and Windows. Kosmo, a code editor built with Merenda, is a way to try it without writing any code.
Merenda draws its own controls, so you can use the same theme across platforms. Choose a familiar macOS look, glossy Aqua buttons, or something more colorful. DarkBSD is the default.
You'll need Nim 2.2.6 or newer, a C compiler, Git, and Atlas to install the Nim dependencies. On Linux and FreeBSD, you'll also need the system libraries for your windowing and graphics backend; Merenda uses Siwin for windows and FigDraw for rendering.
To try the examples, clone the repository and run the controls showcase:
git clone https://github.com/elcritch/merenda.git
cd merenda
atlas install -tuk
nim r examples/controls_showcase.nimThe showcase lets you try the controls together in one window. To see another
theme, run it with NIMKIT_THEME set (in a POSIX shell):
NIMKIT_THEME=macos nim r examples/controls_showcase.nim
NIMKIT_THEME=aqua nim r examples/controls_showcase.nimThe built-in themes are embedded CSS stylesheets with shared widget defaults. Application CSS can extend them, and typed Nim styling APIs remain available for programmatic overrides.
Use CSS for control colors, fonts, gradients, state styles, edge pinning and
native layout constraints. Style StackView/GridView spacing and alignment and
control-specific metrics through -nimkit-* properties. The CSS preview
lays out its toolbar, sidebar and editor from a stylesheet and reloads it when
you click Reload CSS:
nim r examples/css_theme_demo.nimRead the CSS theming guide for selectors, variables, supported properties and appearance scope.
You can also describe native GUIs in lightweight markup,
using HTML5 syntax and data-* attributes for native widget options:
<nk-main>
<nk-window id="window" title="Hello" data-frame="100 100 400 240">
<nk-stack-view id="root" data-axis="vertical" data-padding="24" data-spacing="12">
<nk-label data-label-style="title">Hello from Merenda</nk-label>
<nk-text-field id="name" placeholder="Your name"/>
<button id="save" data-action="saveDocument">Save</button>
</nk-stack-view>
</nk-window>
</nk-main>loadGuiResourceBundle reads the interface and instantiateResources constructs
its native controls. One document can define independent windows. Built-in elements
use nk-; application widgets can use names such as some-app-widget. Use IDs to
look up controls and connect behavior in Nim.
Try the GUI resource example with
nim ic -r examples/html_ui_demo.nim. It includes compact preferences controls,
Preview and Reset actions, and a separate About window. The Appearance dropdown
switches both windows between the custom stylesheet and the built-in CSS themes.
To use Merenda in your own project, add this dependency to your .nimble file
and run atlas install -tuk from that project:
requires "https://github.com/elcritch/merenda"Build your app with threads enabled and ARC or ORC, for example
nim r --threads:on --mm:arc main.nim. The examples in this repository already
have those settings.
FigDraw is compiled into the application. Merenda's experimental
useNativeDynlib mode and build_dynlib task have been removed; omit
-d:useNativeDynlib from existing build commands.
Build a resource document with Tekton's widget palette, property inspector, and live preview. Add layout guides and constraints, pin views to their parent, undo changes, and save the result for your Merenda app. Use Interact to try controls in the preview.
nim r src/merenda/tekton.nim
# Or open an existing interface:
nim r src/merenda/tekton.nim path/to/interface.cborSee Tekton's authoring workflow for supported resources and how to load the saved interface in your app.
A window, a label, and an application loop:
import merenda/nimkit
let
app = sharedApplication()
window = newWindow("Hello", frame = rect(100, 100, 360, 180))
root = newView()
greeting = newTitleLabel("Hello, Merenda!")
root.addSubview(greeting)
greeting.pinEdges(
toGuide = root.contentLayoutGuide(insets(24.0)),
edges = {leLeft, leTop, leRight},
)
app.runWindow(window, root)Save this as examples/greeting.nim in your checkout and run
nim r examples/greeting.nim.
Here's a counter. A stack view arranges the controls, and the button's action updates the label.
import merenda/nimkit
import sigils/selectors
let
app = sharedApplication()
window = newWindow("Counter", frame = rect(100, 100, 320, 220))
root = newView()
layout = newStackView(laVertical)
label = newStatusLabel("Clicked 0 times")
button = newButton("Click")
clickAction = actionSelector("counterClicked")
var clicks = 0
proc onClick(sender: DynamicAgent) =
if not sender.isNil:
inc clicks
label.text = "Clicked " & $clicks & " times"
button.target = newActionTarget(clickAction, onClick)
button.action = clickAction
layout.spacing = 12.0
layout.alignment = svaFill
layout.addArrangedSubview(label, button)
root.addSubview(layout)
layout.pinEdges(
toGuide = root.contentLayoutGuide(insets(44.0, 44.0, 0.0, 44.0)),
edges = {leLeft, leTop, leRight},
)
app.runWindow(window, root)This is examples/quick_start.nim. Run it with:
nim r examples/quick_start.nimNimKit's larger controls handle more of the work for you. This app opens a
Markdown file with selectable text, links, code blocks, tables, and images.
The view handles scrolling and layout as you resize the window. Up/Down arrows
scroll the reader, j/k select headings and paragraphs in reading order, and
Enter expands or collapses the selected block's section.
import std/os
import merenda/nimkit
let
path = absolutePath(paramStr(1))
app = sharedApplication()
window = newWindow(path.extractFilename(), frame = rect(120, 80, 820, 700))
root = newView()
viewer = newMarkdownView(readFile(path), imageBasePath = path.parentDir)
root.addSubview(viewer)
viewer.pinEdges(toGuide = root.contentLayoutGuide(insets(20.0)))
app.runWindow(window, root, viewer)Save it as examples/reader.nim, then run
nim r examples/reader.nim README.md. It expects a readable file path.
For a version with a built-in sample document, run:
nim r examples/markdown_viewer_demo.nim README.mdThat is the kind of efficiency NimKit aims for: you write the app's behavior, while the controls take care of text selection, focus, drawing, and layout. For an app with more interaction, try the to-do list or its table-based version, which adds row selection and drag reordering.
For a small app, MVP doesn't need a class hierarchy. Here, tasks holds the
model data in an ArrayController, the table and button are the view, and
markDone acts as the presenter. Select a row and click Mark done: the
presenter updates the model and refreshes the table.
import merenda/nimkit
import sigils/selectors
let
app = sharedApplication()
window = newWindow("Tasks", frame = rect(100, 100, 460, 320))
root = newView()
table = newTableView(frame = rect(24, 24, 412, 200))
doneButton = newButton("Mark done", frame = rect(24, 244, 140, 32))
tasks = newArrayController(columns = [
modelColumn("task", "Task", "task", 260.0),
modelColumn("state", "State", "state", 100.0),
])
for index, title in ["Write release notes", "Try the demo"]:
tasks.addItem(modelItem($index, fields = [
modelField("task", toObj(title)),
modelField("state", toObj("To do")),
]))
table.bindTableView(tasks)
table.selectionMode = tsmSingle
# The presenter turns a user action into a model update.
proc markDone(sender: DynamicAgent) =
discard sender
let selected = tasks.selectionController().selectedIdentifier()
if selected.len > 0:
tasks.setValue(selected, "state", toObj("Done"))
table.reloadData()
let doneAction = actionSelector("markTaskDone")
doneButton.target = newActionTarget(doneAction, markDone)
doneButton.action = doneAction
root.addSubview(table)
root.addSubview(doneButton)
app.runWindow(window, root, table)Save this as examples/tasks_mvp.nim and run nim r examples/tasks_mvp.nim.
The table binding supplies the columns and row values, so you only write the
action specific to your app. For a larger version, see the
table-based to-do app or the
model controller examples.
Sigils protocols let you attach methods to an individual object, even when its
type comes from a library. Here, an ordinary View gets a custom drawing method.
Click Inspect layout to replace that method with one that displays the
view's dimensions; click again to restore the preview.
import merenda/nimkit
import sigils/selectors
protocol PreviewDrawing of ViewDrawingProtocol:
method draw(view: View, context: DrawContext) =
context.addRectangle(view.bounds, fill(color(0.18, 0.32, 0.55)))
context.addText(view.bounds, "Design preview", color(1, 1, 1), taCenter)
protocol LayoutDrawing of ViewDrawingProtocol:
method draw(view: View, context: DrawContext) =
context.addRectangle(view.bounds, fill(color(0.12, 0.22, 0.24)))
let size = view.bounds.size
context.addText(
view.bounds, $size.width & " x " & $size.height, color(1, 1, 1), taCenter
)
let
app = sharedApplication()
window = newWindow("Dynamic drawing", frame = rect(100, 100, 420, 260))
root = newView()
preview = newView(frame = rect(24, 24, 372, 140))
button = newButton("Inspect layout", frame = rect(24, 188, 160, 32))
inspectAction = actionSelector("toggleLayoutDrawing")
preview.withProtocol(PreviewDrawing)
var inspecting = false
proc toggleLayout(sender: DynamicAgent) =
discard sender
inspecting = not inspecting
if inspecting:
preview.withProtocol(LayoutDrawing)
else:
preview.withProtocol(PreviewDrawing)
preview.needsDisplay = true
button.target = newActionTarget(inspectAction, toggleLayout)
button.action = inspectAction
root.addSubview(preview)
root.addSubview(button)
app.runWindow(window, root)Save this as examples/protocol_drawing.nim and run
nim r examples/protocol_drawing.nim.
Both implementations are compiled Nim code with typed View and DrawContext
arguments. NimKit calls the drawing protocol, and Sigils dispatches to the method
currently installed on preview. Replacing it leaves other views alone and
keeps this view's identity, layout, and place in the window intact.
This is useful for adding diagnostics, swapping rendering strategies, or customizing a library object without introducing a subclass for every variation. The same pattern works for view controller loading and table delegates.
An animationGroup turns ordinary property assignments into a coordinated
animation. These two panels slide together over 800 ms with linear motion.
Next slides to the details; Back reverses the trip.
import merenda/nimkit
import sigils/selectors
let
app = sharedApplication()
window = newWindow("Carousel", frame = rect(100, 100, 420, 260))
root = newView()
viewport = newView(frame = rect(24, 24, 372, 140))
first = newGroupBox("Welcome", frame = rect(0, 0, 372, 140))
second = newGroupBox("Details", frame = rect(372, 0, 372, 140))
button = newButton("Next", frame = rect(24, 188, 160, 32))
slideAction = actionSelector("slidePanels")
first.contentView = newLabel("Your first panel.")
second.contentView = newLabel("A little more information.")
viewport.clipsToBounds = true
var showingDetails = false
proc finishSlide(button: Button) {.slot.} =
button.enabled = true
proc slidePanels(sender: DynamicAgent) =
discard sender
if button.enabled:
button.enabled = false
showingDetails = not showingDetails
button.title = if showingDetails: "Back" else: "Next"
let size = viewport.bounds.size
let offset =
if showingDetails:
-size.width
else:
0.0'f32
let slide = animationGroup(duration = 800.ms, curve = acLinear):
first.frame = rect(offset, 0, size.width, size.height)
second.frame = rect(offset + size.width, 0, size.width, size.height)
slide.connect(finished, button, finishSlide)
discard app.startAnimation(slide)
button.target = newActionTarget(slideAction, slidePanels)
button.action = slideAction
viewport.addSubview(first)
viewport.addSubview(second)
root.addSubview(viewport)
root.addSubview(button)
app.runWindow(window, root)Run the carousel example with
nim r examples/carousel_demo.nim. The viewport clips the panels as they move,
and the animation's finished signal enables the button for the next transition.
For more, see property animations and sequences.
A standard Box can blur the content behind its rounded bounds through FigDraw.
Its child controls stay sharp, and its fill follows the active theme:
let overlay = newBox(frame = rect(24, 24, 320, 96))
overlay.addStyleClass(PopoverBoxStyleClass)
overlay.backdropBlurRadius = 20
overlay.backdropTintOpacity = 0.78
overlay.addContentSubview(newTextField("Search"))
root.addSubview(overlay)Set backdropBlurRadius to zero to restore the ordinary box fill.
backdropTintOpacity controls the themed tint over the blurred content, from
zero to one. This effect is rendered inside the application, independently of
native window backdrop effects.
NimKit apps can reuse the same controls through SearchBar or attach a
TextSearchController to any host view:
let preview = newTextView("λcat and dog")
let search = newTextSearchController(
preview, "document", textViewSearchAdapter(preview)
)
# Attach preview to a window before opening the controls.
discard search.showSearch()Keep the controller alive while its controls are attached, and call search.close()
before releasing it if the host remains alive. Custom TextSearchAdapter callbacks
provide text snapshots, reveal matches, and clear selections for terminals,
multiple documents, or other data sources. An optional replace callback adds
collapsed replacement controls and receives a validated Reni pattern and capture
template. The adapter owns edits, undo, and checking that source content is current.
Hosts can route find shortcuts through search.handleSearchKey(event) and call
search.refreshSearch() when their source changes.
Kosmo is a code editor built with Merenda and Moe's Vim-style editing engine. It brings together a file browser, split panes, terminal tabs, Markdown previews, Git diffs, and GitHub issues and PRs. You can use it on its own or explore its source to see how a larger Merenda app fits together.
Use the Files and Find icons at the left of the status bar to switch sidebar views. Click the active icon again to collapse the sidebar and give the editor the full window width; click either icon to reopen it at its previous width.
Press Cmd-F on macOS or Ctrl-F elsewhere to search an editor, Markdown
preview, Git diff, or GitHub tab. Use Enter / the arrow buttons to move through
matches, Cmd/Ctrl-G and Shift-Cmd/Ctrl-G for next and previous, and Escape
to close. Editor matches scroll to the center of the pane. Enable .* in any
content search, including terminal tabs, to use Reni regular expressions. Searches
default to literal text; Markdown, GitHub, diff, and terminal matches ignore case.
Use Up/Down arrows to scroll Markdown, GitHub and Git diff viewers. Read-only
NimKit text views share this scrolling behavior; editable text keeps its cursor
movement. Markdown readers also support j/k to select visible headings and
paragraphs and Enter to expand or collapse the selected section.
Diff search includes collapsed sections and loads ordinary patches within the viewer's size limits. Open oversized patches explicitly to include their contents.
The Files filter, Quick Open, and VS Code grammar search also offer .* for
Reni expressions. Quick Open keeps fuzzy filename ranking when this is off.
Invalid expressions show an error and clear stale results. Viewer expressions
can span lines; terminal expressions can span soft-wrapped output and retain
the original cell positions, including wide Unicode characters.
Terminal find centers older matches where possible and stays at the bottom for
matches near the end of the history.
Editor search and the Find sidebar open with replacement controls collapsed.
Click the chevron beside the search field to expand or collapse them without
clearing the query or results. On macOS, Option-Cmd-F opens editor replacement
and Option-Shift-Cmd-F opens replacement in files; elsewhere use
Alt-Ctrl-F and Alt-Shift-Ctrl-F. The regular Cmd/Ctrl-F editor shortcut and
Shift-Cmd/Ctrl-F file-search shortcut always return to search only.
Editor replacement offers Replace and Replace All, with one undo step per
operation. In the Find sidebar, run a search, expand replacement, enter text, then
choose Replace for the selected match or Replace All. Both fields treat
text literally by default. Enable .* to use Reni regular expressions in the
query and capture templates in the replacement: $0 is the entire match, $1
and later numbers are captures, ${name} is a named capture, and $$ inserts a
dollar sign. For example, search (?<name>cat|dog) and replace with ${name}!.
When named groups are present, Reni treats unnamed groups as noncapturing.
Matching is line by line, with Unicode-aware offsets; replacement text may
contain newlines. Invalid patterns or capture references show an error, and
invalid replacement templates leave files and buffers untouched. Empty
replacement text deletes matches. File replacement
saves the displayed results, including any search limits, checks that matched lines
still agree with the results, and skips files with unsaved editor changes. Its status
reports replacements and skipped files, then refreshes the search.
Filesystem notifications keep the browser and Quick Open inventory current. On macOS, one FSEvents stream covers a project tree; linked folders and Git metadata outside that tree retain their own streams. If native monitoring cannot cover a path, Kosmo polls periodically and logs the cause and affected paths. Missing directories and exhausted watch capacity are retried automatically.
Open, Open Folder, and Save As share a resizable file browser with Places shortcuts,
Back/Forward/Up navigation, and an editable location field. Enter an absolute path,
a relative folder, or ~/ and press Return to navigate. The file list and Name
column expand with the dialog; Save As keeps the filename below the browser so you
can change folders without losing the name you typed.
You don't need Nim to use a prebuilt Kosmo release. Run the installer from a shell (Git Bash on Windows):
curl -fsSL https://raw.githubusercontent.com/elcritch/merenda/HEAD/install.sh | bashOn macOS, it installs Kosmo.app in ~/Applications and a kosmo command in
~/.local/bin. On Linux, FreeBSD, and Windows, the command goes in
~/.local/bin. Make sure that directory is on your PATH.
Open the current folder or a file:
kosmo .
kosmo README.mdThese commands reuse a running Kosmo instance. Use kosmo --bg ./folder/ to
start a new instance detached from your shell, or kosmo --new ./folder/ to
start a new instance in the foreground. kosmo -v and kosmo --version print
the version and exit. On macOS, you can also open Kosmo.app from Finder.
Add one or more folders to the existing Kosmo window with --add:
kosmo --add ../shared-libraryUse Quick Open to find a file, drag tabs to arrange your panes, or choose File → New Terminal to open a shell. Markdown files open as previews, with a control to switch to the source editor. Merenda Settings places the theme and UI scale in Appearance, fonts in Typography, and scrolling in Behavior.
In Moe's normal mode, :e path opens a Kosmo document tab or selects the file's
existing tab.
:help and :config open reusable tabs; :config keeps Moe's interactive
settings viewer and its selection when you switch tabs, and closes with :q.
:split (:sp) opens the current buffer in a pane below, and :vsplit (:vs)
opens it in a pane to the right. Add a filename to open that file in the new
pane; relative paths use the editor's working directory. :new and :vnew
create empty buffers in those panes. Moe mappings for these commands and
mode_switch config use the same Kosmo tabs and panes.
:wq, :x, and ZZ save and close the selected native tab; other unsaved
tabs stay open. :bd accepts a buffer number or filename and removes that
buffer from every pane, refusing unsaved changes unless you add !.
Undo and Redo also work while typing, including when Input mode is forced.
Vim's "+ and "* registers use the native clipboard; on platforms with one
clipboard, both registers share it.
Copy and Select All work in Markdown previews, GitHub issues and pull requests, Git diff summaries and hunks, Help, and Command Output. Clipboard shortcuts and the Edit menu use the focused view's selection; Paste and Cut work in editable text views and search fields. Read-only views keep their content unchanged.
TextMate grammars installed from Kosmo Settings also highlight Markdown code
fences and Git diffs. Fences use the grammar's language ID (for example, sql),
and diffs use its filename and extension associations. Installing a grammar
refreshes open viewers and cached previews without restarting Kosmo.
Kosmo advances Moe's background work from the native event loop, including
when Git monitoring is disabled. Hook output, build output, and :jobs use a
reusable Command Output tab. :jobs! stops running external commands.
:terminal, shell commands, and manual pages open native terminal tabs.
Kosmo loads [Hook] settings from ~/.config/moe/moerc.toml; Moe's read/write
hook rules apply to native file opens and saves too.
Unsaved work is checkpointed every five seconds after changes into Kosmo's
recovery cache and removed on a clean close. After an interrupted session,
Kosmo opens Recovered Work when preserved copies exist. Use :recover to
open that tab again. Restore brings a copy into an unsaved editor buffer as
an undoable edit; Discard requires a second click to confirm removal.
Settings changes apply to the current Kosmo instance immediately. Choose Save as Default to use the committed theme, fonts, scale, and scrolling choices on the next launch; Reset restores the last saved values. You can also enable Remember changes for future launches to save each committed change automatically.
Terminal tabs sleep on PTY readiness while idle. A dedicated Sigils dispatcher
owns their sessions, reads and parses output, and accepts input and resize commands.
The UI consumes owned RChan snapshots without waiting for the parser. This worker
path is shared across platforms; native PTY startup currently requires POSIX.
For native timing measurements with cmatrix, ps, or a 10,000-line burst, see
terminal latency diagnostics.
Terminals default to Hybrid input: Ctrl-W v splits right, and
Ctrl-W h/j/k/l or Ctrl-W followed by an arrow navigates panes. On Linux and
Windows, Ctrl-C copies the terminal selection and Ctrl-V pastes. Prefix a
shortcut with Ctrl-\ to send it to the shell: Ctrl-\ Ctrl-C interrupts,
and Ctrl-\ Ctrl-W v sends the whole pane chord. Kosmo Settings → Terminal →
Terminal input switches between Hybrid and Raw shortcuts, which sends
Control keys directly. The choice applies to existing terminals and saves for
future launches as "terminalInput": "hybrid" or "raw" in
~/.config/kosmo/config.json. See the shortcut guide
for prefix cancellation and platform details.
Kosmo Settings → Moe Themes includes Catppuccin Latte, Catppuccin Mocha,
Kanagawa Wave, One Dark, and Tokyo Night Moon. These themes are embedded in
the executable and work from any launch directory. Add your own TOML themes
in ~/.config/moe/themes; a user theme with the same name overrides a bundled
theme.
Kosmo's file tree indents children by 10 points per level. To change this,
add "fileTreeIndentation": 8.0 to ~/.config/kosmo/config.json and restart
Kosmo. Values are nonnegative points per level; 0.0 removes indentation.
To use a Nim language server, add nimLspCommand to Kosmo's
~/.config/kosmo/config.json and restart Kosmo. The command must be an
absolute executable path followed by any arguments. Nimdex 0.1.2 defaults to
nim ic and requires a compiler with --genBif:on support, plus matching
nifler and nifmake companions beside Nim or on PATH. For example, build
Nimdex from its checkout with that compiler:
cd ../nimdex
mkdir -p bin
/absolute/path/to/bif-enabled/nim c -d:release -o:bin/nimdex src/nimdex.nimAdd this field to the JSON config, using absolute paths without spaces:
{
"nimLspCommand": "/absolute/path/to/nimdex/bin/nimdex daemon --compiler /absolute/path/to/bif-enabled/nim --log-file /absolute/path/to/nimdex.log"
}Kosmo enables Moe's LSP client when this field is set. In normal mode, press
g then d to go to a definition, or K to show hover information. Remove
the field or set it to an empty string to disable LSP on the next launch.
Nimdex's daemon command communicates over standard input and output and stays
attached to Kosmo; it does not need to detach itself.
--log-file appends daemon stderr to the chosen file and creates missing parent
directories. Omit it to send logs through Kosmo's LSP message log.
To run Nimdex separately, start its persistent LSP TCP listener in another terminal:
/absolute/path/to/nimdex/bin/nimdex daemon --lsp-listen 9257 --compiler /absolute/path/to/bif-enabled/nim --log-file /absolute/path/to/nimdex.logSet nimLspCommand to the listener's tcp://host:port address and restart Kosmo:
{
"nimLspCommand": "tcp://127.0.0.1:9257"
}Hostnames, IPv4 addresses, and bracketed IPv6 addresses such as
tcp://[::1]:9257 are accepted. Kosmo connects in its dedicated LSP child
process and forwards standard LSP Content-Length frames in both directions.
It does not launch the server; connection errors appear in the LSP message log,
and closing Kosmo disconnects its session while Nimdex keeps listening for the
next connection. Nimdex serves one editor session at a time, so use a separate
listener for each concurrently connected Kosmo window.
Kosmo initializes each connection with its editor's project directory as the
LSP workspace root.
Nimdex binds to 127.0.0.1 by default. --lsp-listen 0 chooses an available
port and records it in the daemon log. For another bind address, including a
Tailscale address, add --lsp-host ADDRESS and use that address in Kosmo's TCP
URL. The server must be able to access the same project and document paths;
TCP does not translate paths between machines. Use --lsp-listen for editor
LSP; Nimdex's separate --listen option serves its CLI query protocol.
Syntax colors arrive progressively as background workers finish small batches.
Markdown previews display their content before fenced-code coloring finishes;
selection, code-block scroll positions, and text layout survive those color updates.
Kosmo includes NIF syntax highlighting by default for .nif files.
To add language highlighting, open Kosmo Settings → TextMate Grammars and
search the built-in language grammars in the open-source microsoft/vscode
repository by language name, file extension, or TextMate scope. Select a result
to download, validate, and install its grammar files into Kosmo's user
configuration. This searches VS Code's source repository, not its extension
Marketplace.
You can also send a Git diff straight to Kosmo:
git diff | kosmo --diffChoose File → Show GitHub Issues and PRs to read the active project's issues
and pull requests in a Markdown tab, or press Cmd/Ctrl-Shift-H. Install the
GitHub CLI and sign in with gh auth login first;
the viewer uses the project's GitHub remote and your existing CLI credentials.
It defaults to open items, with controls for issues, pull requests, or both,
and open, closed, or all states. The Issues and Pull Requests sections start
expanded, with each individual issue and PR collapsed until you open it.
Descriptions render as Markdown alongside authors, labels, draft status, and PR
branch and review details. PRs also show a job summary and each CI check's workflow,
status, and link to its details. Click a section heading to expand or collapse it;
use the link beneath an item's heading to open it on GitHub. Use
Cmd-F/Ctrl-F to search the rendered page, and choose Refresh to fetch updates.
Each list shows up to 100 items and indicates when that limit is reached. Fetches
run in the background and are cancelled when the tab closes. Enable Auto-refresh
to poll every 30 seconds and refresh after workspace changes; it starts off,
like the Git Diff viewer. Automatic requests wait for the current fetch to finish.
Manual and automatic refreshes retain expanded and collapsed sections, including
when items move or their titles change. Switching projects resets section state.
The action can be assigned a shortcut in Kosmo Settings.
Run kosmo --help for command-line options. See the
keyboard shortcut guide for navigation
and Vim bindings, or release and installer details
for supported builds, custom install locations, and the static Linux build.
From your Merenda checkout, install the extra Kosmo dependencies, then build and launch it:
atlas install -tuk --features:kosmo
nim c -o:kosmo src/merenda/kosmo/kosmo.nim
./kosmo .On Windows, run ./kosmo.exe . after compiling.
On macOS, install the current checkout as a complete Kosmo.app with its icon,
bundled notices, debug symbols, and local code signature:
nim install_kosmoThis uses Atlas to resolve dependencies, replaces ~/Applications/Kosmo.app,
and updates the ~/.local/bin/kosmo link. Restart Kosmo if it was already
running. Set KOSMO_INSTALL_DIR or KOSMO_BIN_DIR to choose other locations.
The examples directory has complete apps you can run and change. These are good places to go once you've tried the basics:
- Layouts: stacks and constraints, constraint playground, and the layout guide.
- Tables and trees: table example, filter row (including date range pickers and token fields), outline example, and model controllers.
- App workflows: documents and windows, preferences, and settings and themes.
- Text and drawing: Markdown viewer, canvas, and terminal.
- Building UI from resources: resource guide and example.
- Development checks: reliability and memory profiling.
- Under the hood: NimKit design, Kosmo workspace updates, FigDraw, Siwin, and Sigils.