Terminal Multiplexer · GPU Rendered

Tern

A terminal with a daemon that keeps your programs alive, wherever you work. Split panes, open files and browsers side by side, run agents, and switch machines without losing anything.

User guide for Shawn · Tern 0.4.5

How your setup works

Daemon keeps programs alive. Close the window, close the lid, or reconnect from another device. Your shells, agents, and other programs stay running on the mini. Updates install in place without restarting anything.

Get started

The big idea

Window, session, tab, pane, block. The hierarchy explained in plain words.

Block types

Shell, agent, file, browser, git, board, notebook, and more. What each does.

Everyday tasks

How to new tab, split, move, close, rename, open files, and more.

Shortcuts cheat sheet

Confirmed keys and probable shortcuts. Printable.

Your setup (Shawn)

Claude in shells, omp as agent, screenshot paste, the Monitor tab, and more.

Copy, paste & notifications

How clipboard works, the OSC 52 trick, and alert behavior.

Carly, lenses & surfaces

The built-in assistant, command lenses, and native surfaces explained.

Settings explained

What your current settings mean and what they do.

Scripting from the terminal

Useful tern CLI commands with one-line examples.

Gotchas

Things that surprised you or don't work the way you'd expect.

Glossary

Every term, alphabetical, one-line definition.

Back to overview

The Big Idea

Window, session, tab, pane, block. The hierarchy from top to bottom.

The hierarchy

Window (the app)
└─ Session (named workspace)
└─ Tab (one screen)
└─ Pane (split, horizontal or vertical)
└─ Block (what lives there: shell, file, browser, etc)

Window

The macOS app window. Shows one session at a time. You can have multiple windows open on the same machine, or open windows on different machines (MacBook, Mac mini, etc) and they all connect to the same daemon.

Session

A named workspace. You might have a "projects" session, a "monitoring" session, and a "work" session. Switch between sessions via the palette or by clicking another session's tab. Sessions can be locked against accidental closing with keep-open.

Tab

One screen in a session. A tab can hold one pane or be split into multiple panes side by side or stacked. Drag tabs to reorder them. New tab opens in the focused pane's folder by default.

Pane / Split

A tab divided horizontally (left and right) or vertically (top and bottom). Split right is Cmd+D. Split down is Shift+Cmd+D. Navigate between panes with Cmd+] and Cmd+[ (probably; confirm in Settings).

Block

What lives inside a pane. Shell (your terminal prompt), agent (runs omp for you), file viewer/editor, browser, git graph, board, notebook, SQLite database browser, task manager, screen share, profile/flame graph, or note. Only one block per pane.

Picture-in-picture (PiP)

A block floating over another pane. Useful for a browser or file you want to reference without closing what's underneath. Dock it back with Ctrl+Cmd+P (probably). Or stash it, or corner-park it (top-left, top-right, bottom-left, bottom-right).

The daemon

Tern runs a daemon on the Mac mini that owns every pane's program and scrollback. Windows are just views onto the daemon. You can close the window, close the lid, or disconnect and reconnect from another device, and your programs stay running.

This is why:

You can reconnect to a session from a different machine and pick up where you left off.
Closing the MacBook lid does not kill your shells or agents.
Updates download in the background and install in place. Programs keep running.
Several windows or devices can attach to the same daemon at once.

If a program crashes, restart it. Tern will remember the scrollback up until the crash. If Tern itself crashes, you can resume with omp --resume (if you started the agent yourself).

Your setup: MacBook as viewer, Mini as host

Your MacBook runs the Tern window. Your Mac mini runs the daemon, over Tailscale at port 8376.

What this means:

When you type in a pane, keystrokes go to the mini.
Terminal output and files render on your MacBook's GPU.
Browser blocks also render on the MacBook (so localhost in a browser block means your MacBook, not the mini).
Close the MacBook lid or disconnect. The programs on the mini keep running.
Reconnect from another device and the mini still holds your panes.

Images do not forward from the mini to the MacBook. Shawn's clipsync watcher handles this: take a screenshot, then paste with Ctrl+V in Claude (not Cmd+V).

Back to overview

Block types

What can live in a pane, and how to open each one.

Blocks at a glance

Shell

Your terminal prompt (zsh, login shell).

Shift+Cmd+T to open new. Or click on an existing shell to focus it.

Agent

Runs omp (Claude, your LLM assistant). Typing omp in a shell also counts as an agent block.

Shift+Cmd+A to open new.

File

View or edit a file. Renders Markdown. Shows diffs with git gutters.

Cmd+O or Cmd+P to open file picker. Or tern open --split right FILE[:LINE] from shell.

Browser

Web page. Renders on your MacBook.

Palette "New browser block" or Shift+Cmd+B (probably). Click a link in a block to open in Tern browser by default.

Git

Commit graph, diffs, staging area. Auto-fetches every 5 min and fast-forwards pulls.

Option+Cmd+G (probably) or palette "New git block".

Board

Kanban board read from Markdown or TODO.md.

Option+Cmd+K (probably) or palette "New board block".

Notebook

Jupyter notebook.

Palette "New notebook block".

SQLite

Database browser clone for .db files.

Palette "New SQLite block".

Task manager

Live process table. What is running right now.

Palette "New task manager block".

Screen

Another machine's display, over the network.

Palette "New screen block". Add the host in Settings > Hosts first.

Profile

Flame graph for CPU profiling.

Palette "New profile block".

Note

Plain text note. Not synced, local to this pane.

Palette "New note block".

Opening blocks

Most blocks open with keyboard shortcuts or the command palette (Cmd+K). Try the palette first if you are not sure. You can also use the CLI:

tern new shell
tern new agent
tern open FILE
tern browser --url https://example.com

Back to overview

Everyday tasks

How to do common things in Tern.

Working with tabs and panes

New tab

Cmd+T opens a new tab. It opens in the focused pane's folder by default (set in Settings > Tabs & panes).

Split a pane

Split right: Cmd+D

Split down: Shift+Cmd+D

Navigate between panes

Next pane: Cmd+] (probably)

Previous pane: Cmd+[ (probably)

Move between panes by direction

Option+Cmd+Arrow to move focus up, down, left, right (probably).

Close a pane

Cmd+W (probably). If the pane is running a program, you may be asked to confirm (set in Settings > Tabs & panes with confirm_close).

Close an entire tab

Option+Cmd+W (probably).

Rename a tab

Shift+Cmd+R (probably) or right-click the tab. Or use the CLI: tern rename BLOCK "New name".

Go to a specific tab

Cmd+1 through Cmd+9 to jump to tab 1, 2, 3, etc (probably).

Switch sessions

Palette "Switch session" or click another session's tab. Or tern new session NAME to create one from the shell.

Working with files

Open a file

Cmd+O to open a file picker. Or tern open FILE or tern open FILE:LINE to open at a specific line.

Open a file in a new split

tern open --split right FILE or tern open --split down FILE.

Show the file tree

Control+Cmd+E (probably) or palette "files". The tree is 256 pixels wide by default (set in Settings > Blocks).

Search in scrollback

Cmd+F to find text in the current pane's scrollback. Scrollback is set to 200,000 lines (in your settings).

Search for files

Cmd+P to open the file picker (searches workspace). The palette can also search branches and commits if you are in a git repo.

Working with other blocks

Open a browser

Palette "New browser block" or Shift+Cmd+B (probably). Click a link to open it in the Tern browser by default.

Open an agent (omp)

Shift+Cmd+A opens a new agent block. Or type omp in any shell.

Picture-in-picture (PiP)

tern pip BLOCK --over BLOCK --corner tl (top-left, tr, bl, br)

Dock back into the split: Control+Cmd+P (probably).

Stash a PiP: palette "Stash block".

Zoom a block (maximize)

Shift+Cmd+Return (probably) to zoom the focused pane to fill the tab. Hit it again to unzoom.

Using the palette

Cmd+K opens the command palette. It lists every action and every pane in the current session. Start typing to filter.

Shift+Cmd+P opens palette in "commands only" mode (omits panes).

Other useful things

Clear a pane and scrollback

Shift+Cmd+K (probably). This deletes the scrollback history too.

Show/hide the sidebar

Cmd+B. The sidebar holds your sessions and blocks.

Insert a path

Option+Cmd+P (probably) inserts the absolute path of the current file or pane at your cursor.

Check for new version

Tern downloads updates in the background. When ready, a "Restart to update" pill appears. Hit it to install and restart (programs keep running).

Back to overview

Shortcuts cheat sheet

Confirmed keys and shortcuts that probably work (verify in Settings > Keyboard).

Confirmed shortcuts

These work as of Tern 0.4.5 and are stable.

Action	Key
New tab	`Cmd+T`
Split right	`Cmd+D`
Split down	`Shift+Cmd+D`
Palette (all)	`Cmd+K`
Palette (commands only)	`Shift+Cmd+P`
Open file	`Cmd+O`
File picker	`Cmd+P`
New shell block	`Shift+Cmd+T`
New agent block	`Shift+Cmd+A`
Copy to clipboard	`Cmd+C`
Find in scrollback	`Cmd+F`
Clear pane + scrollback	`Shift+Cmd+K`
Insert path at cursor	`Option+Cmd+P`
Markdown source toggle	`Cmd+E`
Show/hide sidebar	`Cmd+B`
Preferences	`Cmd+,`
Quit Tern	`Cmd+Q`

Probable shortcuts

Verify before using. These are inferred but not yet confirmed. Check Settings > Keyboard to confirm they are bound on your Mac.

Action	Key
Close pane	`Cmd+W`
Close tab	`Option+Cmd+W`
Next pane	`Cmd+]`
Previous pane	`Cmd+[`
Focus pane by direction	`Option+Cmd+Arrow`
Resize pane	`Control+Cmd+Arrow`
Move pane	`Option+Shift+Cmd+Arrow`
Zoom block (maximize)	`Shift+Cmd+Return`
Go to tab N	`Cmd+1` through `Cmd+9`
Rename tab	`Shift+Cmd+R`
Previous tab	`Shift+Cmd+[`
Next tab	`Shift+Cmd+]`
Next layout	`Control+Cmd+L`
Alerts inbox	`Shift+Cmd+I`
Browser block	`Shift+Cmd+B`
Browser PiP	`Option+Shift+Cmd+B`
Browser address bar	`Cmd+L`
Prompt jump (up)	`Cmd+Up`
Prompt jump (down)	`Cmd+Down`
Files tree	`Control+Cmd+E`
New git block	`Option+Cmd+G`
New board block	`Option+Cmd+K`
PiP back to split	`Control+Cmd+P`
Carly (assistant)	Tap `Cmd` twice or `Shift+Cmd+Space`

How to verify: Open Tern > Preferences (Cmd+,) > Keyboard. Look for the action name or key. If it is not listed, it is not bound on your system.

Agent CLI deletion gotcha

In omp or other agent CLIs, Cmd+Backspace (delete to line start) and Cmd+Left / Cmd+Right (jump to line start/end) are hard-coded and may not be what you expect. If you want Cmd+Backspace to send the raw chord instead of deleting, add this to Settings > Keyboard:

"cmd+backspace": "unbind"

Back to overview

Your setup (Shawn)

Claude, omp, screenshots, the Monitor tab, and tips for your MacBook + mini setup.

Claude in shell panes

You run Claude in shell panes. You can type claude <prompt> or just claude to start an interactive session. Open a new shell with Shift+Cmd+T.

omp as the agent button

Shift+Cmd+A opens a new agent block. Your agent command is set to omp (in Settings > Terminal).

You can also type omp in any shell to start an agent right there. omp is your Ollama-powered LLM; it speaks the Tern Surface Protocol so it renders rich messages (diffs, chat bubbles, checkboxes, etc).

Screenshot paste (Ctrl+V, not Cmd+V)

Images do not forward from the Mac mini to your MacBook. Your clipsync watcher fixes this.

To paste a screenshot into Claude:

Take a screenshot (Shift+Cmd+5 or Shift+Cmd+3).
Click on Claude in your pane.
Press Ctrl+V (not Cmd+V).

clipsync watches the mini's clipboard and syncs images to your MacBook.

Clip to MacBook clipboard

clip < file from the mini puts the file's contents on your MacBook's clipboard. The daemon allows programs to write the clipboard when clipboard_write: allow (which is your current setting). This is the OSC 52 escape sequence.

cat /path/to/file | clip

Open a file in a split (from the shell)

tern open --split right FILE or tern open --split down FILE opens a file in the specified direction.

tern open --split right /etc/hosts
tern open --split down /Users/sf/my-project/main.py:42

The Monitor tab

You have a "Monitor" tab that shows a Beszel dashboard. This is a browser block. It renders on your MacBook, so you can visit localhost URLs on the mini from it.

Browser blocks render on your MacBook

Browser blocks are rendered on your MacBook's GPU, not the mini. This means:

localhost in a browser block = your MacBook, not the mini.
You can open a local web service running on the mini by its Tailscale address.

Update the mini's remote server

When you update Tern, the mini's daemon also needs the new version. Run this from your MacBook:

sudo tern remote update

Programs keep running. If the versions get too far out of sync, Tern offers to restart the daemon.

Lid close = no effect

Close the MacBook lid. Your panes stay alive on the mini. When you open it again and reconnect, they are still there.

This is the magic of the daemon: it holds your programs even when the viewer (your MacBook) is offline.

Reconnect to the mini

Tern reconnects automatically at launch if reconnect_hosts: on (which is your current setting). You can also manually reconnect via palette "Switch host" or the host popover in Settings.

Back to overview

Copy, paste & notifications

How clipboard and alerts work in Tern.

Copy to clipboard

By default, copy_on_select: false in your settings. Selecting text does not automatically copy it. Use Cmd+C to copy after selecting.

If you want selecting to copy automatically, change copy_on_select: true in Settings.

Paste into programs

Cmd+V pastes. If the clipboard contains control codes (like ANSI color) or multiple lines, Tern asks you to confirm first (if paste.confirm: true, which is your current setting). This prevents accidental command injection.

quote_urls_at_prompt: true (your current setting) means URLs pasted at the shell prompt are automatically quoted so they don't break.

OSC 52: Programs write the clipboard

When clipboard_write: allow (your current setting), programs can write to the MacBook clipboard using the OSC 52 escape sequence. This is how clip < file works on the mini.

Security note: Any program on the mini can write your clipboard if this is enabled. Read what you paste before running it in a shell.

Notifications

When notifications: true (your current setting), Tern shows desktop notifications as toasts and stores them in the inbox.

Inbox

Shift+Cmd+I (probably) opens the alerts inbox. This is where all notifications are logged.

Notification visual cues

Bell ripple from cursor: A notification arrived while you are focused on that pane.
Dot on pane: An unseen alert in that pane.
Ring on tab: An agent finished in that tab.
Check on tab: Marks the tab as read after the ring appears.

Mute notifications

Use notification_filters in Settings to drop specific notifications. For example, mute all notifications from a certain program.

Back to overview

Carly, lenses & surfaces

The built-in assistant, command lenses, and native surfaces explained.

Carly (the built-in assistant)

Carly is a glass pill in the top right of Tern. She reads your terminals, files, browser pages, and git state. She can type into shells, open files, rearrange tabs, and change settings.

How to summon Carly

Tap Cmd twice, or
Press Shift+Cmd+Space

What Carly knows

Carly has memory in editable Markdown files. She can schedule tasks and heartbeat every 30 minutes (set in Settings > Carly).

Agents she drives

When Carly starts or drives an agent, that agent pane glows. One Undo reverses Carly's actions across tabs.

Command lenses

Tern recognizes certain commands and draws them as rich interactive views instead of raw text output. Examples: git status, cargo, docker, rg, ls.

Set command_lenses in Settings to enable or disable lenses. You can toggle raw output view with a button in the lens.

Native surfaces

Programs that speak the Tern Surface Protocol can draw native UI in their output. This is why omp chats look rich (with diffs, math, Mermaid diagrams, etc) instead of plain text.

Control what surfaces are rendered with these settings:

native_surfaces (global on/off)
surface_diffs (diffs drawn natively)
surface_chat (chat bubbles)
surface_headings (headings)
surface_fold (collapsible sections)

Native prompt and completion

native_prompt: true (your current setting) means Tern draws your zsh prompt itself, so it never smears on resize. Your prompt_style is imported, which reads your powerlevel10k config.

native_completion: true (your current setting) shows Tab completions in a native popover instead of the terminal. Cleaner and faster.

Composer (native editing)

native_editing: true makes omp's chat input behave like a text field. Ctrl+Z there undoes your draft instead of suspending omp.

composer_text can be "plain" or "Markdown". Set to "Markdown" if you want to write formatted text in omp.

Plugins

Tern plugins are Luau packages that add blocks, lenses, commands, and keybinds. Find them in tern plugin dir.

Plugins have full access to the system. Read a plugin's code before installing it.

Manage plugins

tern plugin list
tern plugin install PLUGIN_NAME
tern plugin remove PLUGIN_NAME

Disable all plugins temporarily in Settings > Native > plugins_disabled.

Back to overview

Settings explained

What your current settings mean. Values in brackets are yours.

Appearance

Setting	Your value	What it means
theme	Dark	Use dark theme. Set to Light for light theme, or System to follow the OS.
contrast	Light	Auto-adjust contrast. Off = no change, Light = light adjustment, Always = maximum contrast.
layout	Tiles	Pane layout style.
font_size	14	Terminal font size in points. Adjust with Option+scroll wheel.
material	Clear	Visual material for the pane background. Choose from Clear, Glass, or Solid.
opacity	60%	Transparency of pane backgrounds when material is Glass or Clear.
blur	56	Blur intensity behind panes. Higher = more blur.
density	Compact	Spacing inside panes. Compact = tight, Normal = loose.

Tabs & Panes

Setting	Your value	What it means
tabs	Horizontal	Are tabs arranged horizontally (left to right) or vertically (top to bottom)?
pane_headers	Never	Show headers above panes. Never = hide, Split = show only when split, Always = always show.
new_tabs	Focused	When opening a new tab, open it in the focused pane's folder.
new_blocks	Shell	Default block type for new splits. Shell or Agent.
agent_placement	split	Where new agents open. split = new pane, new tab = new tab, replace = replace idle shell.
cross_session_click	switch	What happens when you click a pane in another session. switch = go to that session, open = open a new split.
confirm_close	running_programs	Ask before closing. never = never ask, running_programs = ask if programs are running, always = always ask.

Terminal

Setting	Your value	What it means
scrollback_lines	200,000	How many lines of scrollback to keep per pane.
copy_on_select	false	Copy to clipboard when text is selected. false = require Cmd+C.
link_click	Click	How to open links. Click = left-click, Command+click = hold Cmd.
clipboard_write	allow	Allow programs on the mini to write to your MacBook's clipboard (OSC 52). deny = block.
notifications	on	Show program notifications as toasts and in the inbox.
shell	(zsh login)	Shell to use. Usually zsh or bash.
agent_command	omp	Command to run when you press Shift+Cmd+A or type agent in a shell.
paste.confirm	true	Ask before pasting control codes or multi-line text into a program.
quote_urls_at_prompt	true	Auto-quote pasted URLs so they don't break.

Native UI

Setting	Your value	What it means
native_prompt	true	Tern draws your zsh prompt (no smearing on resize).
prompt_style	imported	imported = read your powerlevel10k, system = simple prompt.
native_completion	true	Show Tab completions in a native popover.
native_editing	true	Make omp's composer behave like a text field. Ctrl+Z undoes draft.
native_surfaces	(on by default)	Render program output as rich UI (diffs, chat, math, etc).
command_lenses	(on by default)	Recognize git, cargo, docker commands and draw them as rich views.
composer_text	plain	omp chat input format. plain = plain text, Markdown = Markdown.

Hosts & Updates

Setting	Your value	What it means
reconnect_hosts	on	Automatically connect to known remote hosts on launch.
auto_update	on	Automatically download and install Tern updates. You approve with "Restart to update".

Blocks

Setting	Your value	What it means
file_tree	closed, 256 wide	File tree width in pixels. closed = hidden by default.
git auto_fetch	5 min	Auto-fetch git remotes every 5 minutes.

Keyboard

Setting	Your value	What it means
keymap	tern	Shortcut preset. tern, Ghostty, kitty, cmux, tmux.
keymap_prefix	ctrl+b	Prefix key for tmux preset (only used if keymap is tmux).
keybinds	(none)	Custom key bindings in JSON. e.g. {"cmd+d": ["split_right"]}.

Back to overview

Scripting from the terminal

Useful tern CLI commands with one-line examples.

Overview

The tern CLI lets you manipulate sessions, tabs, panes, and blocks from the shell. Most commands take a BLOCK identifier: id, @focused, a title, program name, or SESSION/BLOCK.

Useful for scripting

You can build workflows that open files, run commands in panes, wait for completion, and capture output.

Common commands

Open and launch

tern open FILE                           # Open a file
tern open FILE:42                         # Open file at line 42
tern open --split right FILE              # Open in new pane (right)
tern open --split down FILE               # Open in new pane (down)
tern open --preview FILE                  # Open in preview mode
tern new shell                            # Create a new shell block
tern new agent                            # Create a new agent (omp)
tern new session NAME                     # Create a new session
tern new tab --cwd /path/to/dir           # New tab in specific folder

Focus and navigation

tern focus @focused                      # Focus the current pane
tern focus "Shell 1"                      # Focus by name
tern ls                                   # List all blocks in current session

Run commands in a pane

tern run BLOCK "ls -la"                 # Run a shell command
tern send BLOCK keys "ctrl+c"             # Send keys
tern send BLOCK text "hello world"        # Type text
tern send BLOCK paste "text"              # Paste text

Manage tabs and panes

tern split BLOCK right                  # Split the pane right
tern split BLOCK down                     # Split the pane down
tern rename BLOCK "New name"              # Rename a block
tern close BLOCK                          # Close a pane
tern kill session NAME                    # Close an entire session

Inspect and wait

tern inspect BLOCK                      # Show details about a block
tern wait BLOCK --until exit              # Wait for pane to exit
tern wait BLOCK --until prompt            # Wait for shell prompt
tern wait BLOCK --until idle=2000         # Wait for 2 sec of inactivity
tern capture BLOCK                        # Capture pane output
tern capture BLOCK --scrollback           # Capture full scrollback

Picture-in-picture

tern pip BLOCK                          # Float a block
tern pip BLOCK --over OTHER_BLOCK         # Float over specific pane
tern pip BLOCK --corner tl                # Corner: tl, tr, bl, br
tern dock BLOCK left                      # Dock back into split

Other useful commands

tern keep-open SESSION                  # Lock session against closing
tern events                                # Stream pane events
tern whoami                                # Show current user/host
tern remote update                         # Update mini daemon
tern remote discover                       # Find remote Tern instances

Browser blocks

tern browser open --url https://example.com
tern browser goto https://example.com
tern browser snapshot                      # Capture browser view
tern browser eval "document.title"         # Run JavaScript

Database (SQLite)

tern db /path/to/database.db            # Open SQLite browser

Plugins

tern plugin list                        # List installed plugins
tern plugin install PLUGIN_NAME           # Install a plugin
tern plugin remove PLUGIN_NAME            # Uninstall a plugin
tern plugin dir                            # Show plugin directory

JSON output

Add --json to any command for machine-readable output:

tern ls --json                          # List blocks as JSON
tern inspect BLOCK --json                 # Inspect in JSON format

Example: Open a file in a split, wait, then capture

tern open --split right /path/to/file
tern wait @focused --until prompt
tern capture @focused

Back to overview

Gotchas

Things that do not work the way you might expect.

Gotcha 1: Cmd+Backspace in agent CLIs

Cmd+Backspace deletes to the line start in omp and other agent CLIs. Cmd+Left and Cmd+Right jump to line start/end. These are hard-coded.

If you want Cmd+Backspace to send the raw chord, add this to Settings > Keyboard:

"cmd+backspace": "unbind"

Gotcha 2: Browser blocks render on the MacBook

This is a feature, not a bug, but it means localhost in a browser block means your MacBook, not the mini. To visit a service on the mini, use its Tailscale address instead.

Gotcha 3: Images do not forward to the MacBook

Screenshot from the mini and paste with Ctrl+V in Claude, not Cmd+V. clipsync syncs images for you.

Gotcha 4: Update the mini's daemon separately

When Tern updates on your MacBook, the mini's daemon also needs updating. Run:

sudo tern remote update

Programs keep running. If versions drift too far, Tern offers to restart the daemon.

Gotcha 5: Programs live on the mini, not in the window

Closing the Tern window or lid closes nothing. Programs stay alive on the mini. To stop a program, close the pane, kill the session, or send Ctrl+C from within the pane.

Gotcha 6: Ctrl+B prefix is tmux-preset only

If your keymap is "tern" (the default), Ctrl+B is dormant. It is only active if you choose the "tmux" preset. Your keymap is set to "tern", so Ctrl+B does nothing by default.

Gotcha 7: Copy-on-select is off by default

Selecting text does not copy it. Use Cmd+C to copy. To change this, set copy_on_select: true in Settings.

Gotcha 8: Plugins have full access

There is no permission model for plugins. They can read files, run commands, and access the network. Read a plugin's code before installing it.

Gotcha 9: Cmd+B hides the sidebar

In Markdown files, Cmd+B usually means bold. In Tern, it hides/shows the sidebar. In git blocks, it shows/hides branches. Learn which app you are in.

Gotcha 10: Settings change after updates

When you update Tern, re-check your shortcuts in Settings > Keyboard. A new version might rebind some keys.

Gotcha 11: Security: clipboard write on the mini

With clipboard_write: allow, any program on the mini can write your MacBook's clipboard. This is why clip < file works, but it also means a malicious process could steal data. Be careful what you run.

Getting help

tern --help or tern COMMAND --help shows usage for any command.

Tern logs are in ~/Library/Logs/Tern. Palette > "Open logs and app state" goes there.

Back to overview

Glossary

Every term, alphabetical, one-line definition.

Glossary

Agent	A block that runs `omp` or another command. Agents can read context and type into panes.
Block	The content of a pane: shell, file, browser, git, agent, board, notebook, SQLite, task manager, screen, profile, or note.
Board	A Kanban board block read from Markdown or TODO.md files.
Carly	The built-in assistant. A glass pill in the top right that reads context and can manipulate Tern.
Clipboard write (OSC 52)	Programs can write to your MacBook's clipboard over the network if `clipboard_write: allow`.
Command lens	A rich interactive view for recognized commands (git, cargo, docker, rg, ls). Raw output available with a toggle.
Composer	omp's chat input box. Can be plain text or Markdown. `Ctrl+Z` undoes drafts.
Daemon	The long-running process on the Mac mini that holds all panes, programs, and scrollback. Survives window/lid close.
File block	View or edit a file. Renders Markdown. Shows git diffs with gutters.
Git block	Commit graph, diffs, and staging area. Auto-fetches every 5 minutes.
GPU rendering	Tern uses your GPU to draw the terminal. Smooth, fast, anti-aliased.
Hyperlinks	Links in terminal output. Click or Command+click to open. Behavior set by `link_click`.
Keymap	A shortcut preset: tern, Ghostty, kitty, cmux, or tmux. Choose in Settings > Keyboard.
Keymap prefix	A prefix key (like Ctrl+B) used in tmux preset. Dormant if you use keymap "tern".
Link click	How to open links in terminal output: "Click" = left-click, "Command+click" = hold Cmd.
Native completion	Tab completions drawn in a native popover, not in the terminal.
Native editing	omp's composer behaves like a text field. `Ctrl+Z` undoes draft instead of suspending.
Native prompt	Tern draws your zsh prompt itself. No smearing on resize. Style read from powerlevel10k.
Native surfaces	Programs that speak the Tern Surface Protocol draw native UI (diffs, chat, math, Mermaid) instead of plain text.
Notebook	A Jupyter notebook block.
Notification	A desktop alert from a program. Shows as a toast and stored in the inbox.
omp	An Ollama-powered LLM that runs in agent blocks. Speaks the Tern Surface Protocol for rich output.
OSC 52	An escape sequence that programs use to write the clipboard. Enabled with `clipboard_write: allow`.
Pane / Split	A tab divided horizontally (left/right) or vertically (top/bottom). Each pane holds one block.
Picture-in-picture (PiP)	A block floating over another pane. Dock back in, stash, or corner-park it.
Plugins	Luau packages that add blocks, lenses, commands, keybinds. Full system access, no permissions.
Profile block	A flame graph for CPU profiling.
Remote host	Another machine running a Tern daemon over the network. Connect over Tailscale.
Scrollback	Terminal history. Tern keeps 200,000 lines per pane in your settings.
Session	A named workspace of tabs. Switch between sessions; lock against closing with keep-open.
Shell block	Your terminal prompt (zsh). One or many per session.
Surface Protocol	A protocol programs speak to draw native UI in Tern. omp is an example.
Tab	One screen in a session. Can hold one or many panes (splits).
Tailscale	A private network mesh. Your MacBook connects to the Mac mini daemon over Tailscale at port 8376.
Task manager	A live process table block. Shows running processes in real time.
Window	The macOS Tern application window. Can show multiple windows on different machines, all connected to the same daemon.