---
url: https://among-terminal.github.io/overview.md
---

# Among Terminal overview

Among Terminal combines native VTE terminals, nested panes and live workspaces
in a GNOME window. The short [demonstration](/#demo) introduces the interface;
the full-length recordings here cover more workflows and controls.

## Complete workflow tour

[![Watch the complete Among Terminal workflow tour](/media/among-terminal-overview.png)](/media/among-terminal-overview.mp4)

**[Watch the overview · 1 min 53 s](/media/among-terminal-overview.mp4)**

The original silent tour joins the reviewed feature recordings with direct cuts:
themes, splitting and resizing, pane movement, focus, zoom, fullscreen,
workspace naming and switching, sidebar controls, plugins, consented session
restoration and pane closing. Recorded shortcuts remain visible; no soundtrack
or explanatory subtitles are added.

## Extended presentation

[![Watch the extended Among Terminal presentation](/media/among-terminal-promo.png)](/media/among-terminal-promo.mp4)

**[Watch the extended presentation · 2 min 1 s](/media/among-terminal-promo.mp4)**

The earlier long-form film presents the recorded workflows on a charcoal stage.
It is retained here separately from the approved 23-second README film.

## Explore individual features

* [Feature guide](/features/): demonstrations alongside controls and caveats.
* [Panes](/panes/), [sessions](/sessions/), [preferences](/preferences/)
  and [plugins](/plugins/): detailed references.

Use fullscreen to inspect terminal text. Previews link to MP4 files; GitHub
inline playback is not assumed. The recordings use isolated synthetic projects,
not personal shell startup files.

---

---
url: https://among-terminal.github.io/build.md
---

# Build prerequisites

This page is for developers. For ready-made packages, see [installation](/install/).

## Build and install from source

With Rust/Cargo 1.98.1 installed, clone the repository and run the source
installer as your normal user:

```sh
git clone https://github.com/Among-Terminal/among.git
cd among
sh scripts/install.sh --install-deps
```

The installer uses sudo only for Debian/Ubuntu build dependencies; compilation
and application installation run as your user. It installs a desktop entry and
`~/.local/bin/among`. It does not install Rust or change your toolchain.
Rerun it from an updated checkout to update; `~/.local/bin/among-uninstall`
removes only installer-owned files and preserves preferences and sessions.
See the [source installer reference](https://github.com/Among-Terminal/among/blob/main/docs/install.md)
for conflicts, XDG paths, rollback limitations and prebuilt-binary mode.

For a binary-only Cargo installation with the native prerequisites below:

```sh
cargo install --git https://github.com/Among-Terminal/among --locked among
```

This compiles the moving default branch, without desktop integration or plugins.
Do not run Cargo as root. Repeat to update; `cargo uninstall among` removes the
Cargo binary but preserves settings and sessions.

Built on Debian 13 (trixie), Rust 1.98.1, against GTK 4.18.6, libadwaita 1.7.6,
and VTE 0.80.1. Live acceptance runs use isolated Xephyr/native X11 with GNOME
Shell. A Wayland host desktop is not evidence of native Wayland application
behavior; Wayland, Snap and Flatpak runtime acceptance remains unexecuted.

## System packages

```sh
sudo apt install libgtk-4-dev libvte-2.91-gtk4-dev libadwaita-1-dev
```

Verify:

```sh
pkg-config --exists gtk4 libadwaita-1 vte-2.91-gtk4 && echo ok
```

The GTK4 VTE library must be **0.76 or newer**. Native context-menu dispatch
requires this version; check with `pkg-config --modversion vte-2.91-gtk4`.

### Do not install `libvte-2.91-dev`

That package provides the **GTK 3** build of VTE, whose pkg-config file is
`vte-2.91.pc` and whose libraries are `-lgtk-3 -lgdk-3`. The bindings used here are
generated against the **GTK 4** build, whose pkg-config file is `vte-2.91-gtk4`
and whose libraries are `-lvte-2.91-gtk4 -lgtk-4`.

Both can be installed side by side — they are different shared objects, not
conflicting packages — but only the `-gtk4` one satisfies the build.

## Rust dependencies

From `Cargo.toml`:

```toml
[dependencies]
gtk = { package = "gtk4", version = "0.11", features = ["v4_10", "v4_12"] }
adw = { package = "libadwaita", version = "0.9", features = ["v1_5"] }
vte = { package = "vte4", version = "0.10", features = ["v0_76"] }
glib = "0.22"
gio = "0.22"
serde = { version = "1", features = ["derive"] }
serde_json = "1"
libc = "0.2"
```

Several of these constraints are not optional, and none of them are explained in
the `vte4` README:

### `gtk4` needs the `v4_10` feature

`vte4`'s generated code references `gtk::Accessible`. In `gtk4` 0.11 that type is
behind the `v4_10` feature, so a plain `gtk4 = "0.11"` dependency fails:

```
error[E0425]: cannot find type `Accessible` in crate `gtk`
```

The `v4_12` feature is this project's own requirement, not `vte4`'s: it exposes
`CssProvider::load_from_string`, which is how `data/among.css` is installed.

### `glib` and `gio` must be listed directly

`vte4` does not re-export them. `Pty::new_sync` takes a `vte::PtyFlags`, and
`spawn_async` takes a `glib::SpawnFlags` and an `Option<&gio::Cancellable>`, so
both crates have to be reachable by name.

### `libadwaita` must track `gtk4`

The gtk-rs crates are versioned as a set, and the `-sys` crates declare a `links`
value. Two crates cannot both claim `links = "gtk-4"`, so cargo refuses the
build outright:

```
package `gtk4-sys` links to the native library `gtk-4`, but it conflicts with a
previous package which links to `gtk-4` as well: package `gtk4-sys v0.9.0`
```

`libadwaita 0.7` depends on `gtk4-sys 0.9`; `gtk4 0.11` needs `gtk4-sys 0.11`.
`libadwaita 0.9` is the release that tracks `gtk4 0.11`. Whenever `gtk4` is
bumped, `libadwaita` must move with it.

## Verifying a clean build

```sh
cargo build --release --locked
cargo test --locked
```

`cargo test` runs without a display. The VTE binding helpers that touch GTK —
`ShortcutTrigger::parse_string`, `CallbackAction::new`, `GtkSnapshot` — assert
that GTK is initialised, so they are kept out of the test paths and exercised
through the running application instead.

## Runtime notes

* VTE's search helpers need the PCRE2 multiline flag `0x400`, which is defined in
  neither the crate nor VTE's public headers. Without it VTE emits a warning on
  every search call.
* `vte::Regex::for_search` and `vte::Regex::for_match` are different constructors
  with different purposes; using the wrong one triggers a GLib critical at runtime.
* `text_range` and `text_selected_full` are commented out in the generated
  bindings and are unavailable. `text_selected` is behind the `v0_70` feature, and
  going through the clipboard to read text is not reliable enough to build on.

---

---
url: https://among-terminal.github.io/index.md
---

# Among Terminal

Keep your shells, projects and tools together in one native GNOME window.
Among Terminal combines VTE terminals with split panes, named workspaces and
optional live status plugins.

## Install a release package

Use a ready-made package from [GitHub Releases](https://github.com/Among-Terminal/among/releases).
No Rust toolchain or compilation is needed.

| Format | Best for | Availability |
| --- | --- | --- |
| AppImage | A portable bundle with the main runtime libraries included | In preparation; not downloadable yet |
| DEB | Debian/Ubuntu; APT installs runtime dependencies | **RC2 preview available**, amd64 and arm64 |
| RPM | Fedora; DNF installs runtime dependencies | In preparation; not downloadable yet |

### Install the available DEB

Download a ready-made **0.1.0 RC2 preview** package for
[Ubuntu 24.04 or Debian 13](/install/), on amd64 or arm64.
For Ubuntu 24.04 on amd64, open a terminal in your download folder:

```sh
sudo apt install ./among-terminal_0.1.0.rc.2-1.ubuntu24.04_amd64.deb
```

Launch **Among Terminal** from the applications menu. No Git, Rust or build
scripts are required. This is a prerelease, not a stable release.
[Downloads, updates and removal](/install/).

[Watch or download the video](/media/among-terminal-action-v5.mp4).
The feature guide describes every action without requiring video playback.

## Built for several things at once

* **Split and resize.** Keep an editor, shell and monitor side by side;
  adjust dividers with the mouse or keyboard.
* **Rearrange live panes.** Drag pane headers to change the layout without
  restarting their processes.
* **Organize workspaces.** Name and colour-code projects, switch instantly,
  and collapse the sidebar without losing access to running terminals.
* **Stay on the keyboard.** Move focus, zoom a pane, switch workspaces and
  customize shortcuts in Settings.
* **Restore your layout.** Reopen splits and known directories in fresh shells.
  Running commands and scrollback are not resumed.
* **Choose your status.** Enable a clock, resource meters or per-pane directory
  labels. Plugins are optional and disabled by default.

[Explore features with screenshots and demonstrations →](/features/)

## Make your own plugin

Plugins are separate executables exchanging JSON lines with the application.
They can supply status text, icons and meters without depending on GTK.
They run as your user, not in a security sandbox: install only trusted code.

[Write your first plugin →](/plugin-development/#writing-one) ·
[Protocol reference](/plugin-development/#protocol)

## Learn the controls

[Panes](/panes/) · [Workspaces and sessions](/sessions/) ·
[Keyboard shortcuts](/shortcuts/) · [Preferences](/preferences/)

Ready to try it? See [installation](/install/).

---

---
url: https://among-terminal.github.io/features.md
---

# Features in practice

Among Terminal keeps native VTE terminals in a single GNOME window. This guide
connects each everyday control to a real demonstration and its detailed reference.
The recordings use synthetic projects; zsh, Starship, `ll`, `mc` and `htop` are
demo tools, not software installed or configured by Among Terminal.

[Full-length overview videos](/overview/) ·
[Default shortcuts](/shortcuts/)

## Split and resize terminals

Press **Ctrl+Shift+N** to split the focused pane. A wide pane splits side by side;
a tall pane splits top to bottom. Repeat to build a nested layout with separate
shells, for example a project listing, file manager and process monitor.

Drag a divider to allocate more space, or use **Ctrl+Shift+Right** to grow the
focused pane and **Ctrl+Shift+Left** to shrink it. Resizing keeps the terminals
running rather than starting replacement shells.

[![Separate live terminals running ll, mc and htop](/media/features/02-split-resize.png)](/media/features/02-split-resize.mp4)

**Demonstrations:** [split panes](/media/features/02-split-resize.mp4) ·
[keyboard resize](/media/features/02b-keyboard-resize.mp4) ·
[mouse resize](/media/features/02c-mouse-resize.mp4).

## Rearrange panes without restarting tools

Drag a **pane header**, not terminal text, onto another pane's edge. Left/right
edges place panes side by side; top/bottom edges stack them. The drop indicator
previews the destination. The moved terminal retains its process and focus;
dragging inside terminal text still selects text.

[![Moving a live pane by its header](/media/features/03-pane-drag.png)](/media/features/03-pane-drag.mp4)

[Pane movement and drop rules](/panes/#dragging-a-pane-to-a-new-position).

## Focus, zoom and fullscreen

* Click a terminal or its header to focus it; **Alt+Arrow** moves between panes.
* **Ctrl+Shift+X** expands the focused pane to fill its workspace. Press again to
  recover the same nested layout; hidden panes keep running.
* **F11** enters or leaves fullscreen. Normal startup is maximized, not fullscreen.

[![Zooming a pane while preserving the workspace layout](/media/features/04b-zoom.png)](/media/features/04b-zoom.mp4)

**Demonstrations:** [focus](/media/features/04-focus.mp4) ·
[zoom and restore](/media/features/04b-zoom.mp4) ·
[fullscreen](/media/features/04c-fullscreen.mp4).

## Organize projects into workspaces

Use the header's **New workspace** button or **Ctrl+Shift+T**. Double-click its
sidebar name to rename it: **Enter** accepts, **Escape** cancels, and empty names
are rejected. Each workspace has a colour marker and a live terminal count.

Click a sidebar entry, use **Alt+1…9**, or cycle with **Ctrl+PageUp/PageDown**.
Inactive workspaces keep their terminals and processes running. The sidebar
collapse button reduces the list to a strip: colours and counts remain visible,
and every workspace remains reachable.

[![Renaming and switching between Atlas and Orbit](/media/features/05-workspaces.png)](/media/features/05-workspaces.mp4)

**Demonstrations:** [create, rename and switch](/media/features/05-workspaces.mp4) ·
[collapse and expand the sidebar](/media/features/05b-sidebar.mp4).

## Clipboard, links and pane actions

Right-click a terminal, or press **Shift+F10** in the focused terminal, to open
its native menu. In mouse-reporting programs, use **Shift+right-click**; an
ordinary right-click still goes to the program. Menu actions belong to the pane
that requested them, including when another pane was previously focused.

**Copy** copies that pane's selected text; without selection it is disabled.
**Paste** uses VTE's normal text-paste handling, including bracketed paste when
requested by the terminal program; without a clipboard text format it is disabled.
**Select All** selects available terminal text and scrollback, not other panes.
Copy/Paste availability follows selection and clipboard changes even while the
menu is open. Pasting sends text to the program: it is not session command replay,
but a shell can interpret pasted newlines, so only paste text you trust.

Pointer-opened menus can offer **Copy Link** and **Open Link** for explicit
hyperlinks and plain absolute **http**, **https** and **mailto** URLs. An explicit
hyperlink takes precedence over its displayed text. Other valid explicit schemes
are copy-only; malformed, control-containing or oversized targets are not offered.
Keyboard-opened menus omit link entries rather than reuse an old pointer target.
Open Link requests the desktop handler asynchronously, never a shell command;
handler failure shows an error while the terminal remains usable.

**Split Pane**, **Expand/Restore Pane** and **Close Terminal** reuse the existing
pane controls. Their shortcut hints follow Settings, and removing a shortcut does
not disable its menu action. Arrow keys navigate, Enter activates, and Escape
returns to terminal input. No context-menu recording is included in the videos.

[Detailed menu and pane rules](/panes/#terminal-context-menu).

## Optional live status plugins

After [installing the examples](/plugins/#installing), open **Settings** with
**Ctrl+,** and select **Plugins**. All three examples are disabled by default;
enable only the ones you want. Switches apply immediately and persist on restart.

| Plugin | Where it appears | What it reports |
| --- | --- | --- |
| `clock` | Right application footer | Local time, including seconds |
| `system-status` | Application header | CPU, memory and root-filesystem usage, with percentages and meters |
| `pane-pwd` | Each pane footer | That pane's known directory; the tooltip contains the full path |

Directory changes need your shell to publish **OSC 7**; installing Starship alone
does not supply it. Unknown directories are not replaced with another pane's
path. Resource readings describe the plugin's process/mount namespace, which may
differ from the whole host in a sandbox. Plugins run as separate processes, but
that is fault isolation, not a security sandbox: install only trusted code.

[![Toggling clock, resource meters and pane directories in Settings](/media/features/06-plugins.png)](/media/features/06-plugins.mp4)

[Live status and directory integration](/plugins/#live-status-examples) ·
[Third-party plugin protocol](/plugin-development/#protocol).

## Restore a layout, not yesterday's commands

On a new launch with a saved session, choose **Restore** or **Start new**.
Restoration recovers workspace names, colours, nested splits, focus and known
directories, including inactive workspaces. Every terminal starts a **fresh
shell**: commands, running tools and scrollback are not replayed.

The demonstration restores four shells in different project directories, then
manually runs `ll`. Changed directories require shell OSC 7 reporting even if
the directory plugin is disabled. Missing directories fall back to an accessible
home/startup directory and are reported in Settings. Storage failures are visible
and retryable; recent changes can be lost after a crash.

[![Choosing Restore and reopening separate project directories](/media/features/07-session-restore.png)](/media/features/07-session-restore.mp4)

[Session consent, storage and recovery limits](/sessions/).

## Close a pane and keep working

**Ctrl+Shift+W** closes the focused pane and its process. The sibling that fills
the space receives focus, so the next keystrokes reach a surviving terminal.
Closing a workspace's last pane closes that workspace; the final workspace asks
for confirmation before the application exits. Closing a pane can end a running
job: this is not a detach operation.

[![Closing one pane and typing ll in its surviving sibling](/media/features/08-close-pane.png)](/media/features/08-close-pane.mp4)

[Closing, process exit and focus rules](/panes/#closing-and-exiting).

## Appearance and preferences

The native interface supports light and dark styling. Shell prompts and terminal
colours are configured separately; Among Terminal does not import GNOME Terminal
profiles.

[![The terminal listing in light and dark appearance](/media/features/01-themes.png)](/media/features/01-themes.mp4)

In **Settings → Keyboard**, select an action and press a new shortcut, or use
**Escape** to remove its binding. Changes take effect without restarting and are
saved together with explicit unbinding. Save failures leave the current edit
active for this session and show a warning; a later edit retries saving.

Shortcut editing and storage recovery are documented but are not demonstrated
in these clips. See [shortcut controls](/shortcuts/) and
[preference persistence](/preferences/).

The written instructions explain each action without requiring video playback.
Demonstrations show native X11 behaviour; they do not establish support for
untested platforms or assistive technologies.

---

---
url: https://among-terminal.github.io/install.md
---

# Installing Among Terminal

Install a ready-made release package. No Git, Rust, Cargo or build scripts are needed.

| Format | How dependencies are handled | Availability |
| --- | --- | --- |
| AppImage | The main runtime libraries are intended to be bundled | In preparation; not downloadable yet |
| DEB | APT installs the required distribution libraries automatically | **RC2 preview available** for Ubuntu 24.04 and Debian 13 |
| RPM | DNF installs the required distribution libraries automatically | In preparation; not downloadable yet |

Only the DEB packages below are currently published. AppImage and RPM download
links will be added after their build and runtime checks pass.

## Download

These are **0.1.0 RC2 preview packages**, not a stable release. Choose the file
matching both your distribution version and CPU architecture:

| Distribution | amd64 (Intel/AMD 64-bit) | arm64 (64-bit ARM) |
| --- | --- | --- |
| Ubuntu 24.04 | [Download `.deb`](https://github.com/Among-Terminal/among/releases/download/v0.1.0-rc.2/among-terminal_0.1.0.rc.2-1.ubuntu24.04_amd64.deb) | [Download `.deb`](https://github.com/Among-Terminal/among/releases/download/v0.1.0-rc.2/among-terminal_0.1.0.rc.2-1.ubuntu24.04_arm64.deb) |
| Debian 13 | [Download `.deb`](https://github.com/Among-Terminal/among/releases/download/v0.1.0-rc.2/among-terminal_0.1.0.rc.2-1.debian13_amd64.deb) | [Download `.deb`](https://github.com/Among-Terminal/among/releases/download/v0.1.0-rc.2/among-terminal_0.1.0.rc.2-1.debian13_arm64.deb) |

Not sure which architecture you have? Run `dpkg --print-architecture`.
Check your distribution version in **Settings → About**, or `/etc/os-release`.
Do not use a Debian package on Ubuntu or vice versa. Other distribution versions
have not been accepted for these packages.

## Install and launch

Open a terminal in the folder containing the downloaded file. On Ubuntu 24.04
with amd64, run:

```sh
sudo apt install ./among-terminal_0.1.0.rc.2-1.ubuntu24.04_amd64.deb
```

For another supported target, use the exact filename you downloaded. Keep the
`./` prefix: it tells APT to install a local package. APT downloads the required
runtime libraries from your configured distribution repositories.

Launch **Among Terminal** from the applications menu, or run `among`.
If an older Cargo, Snap or source-built copy is also installed, `/usr/bin/among`
explicitly launches the DEB installation.

## Update and remove

Download the newer package for the same distribution and architecture, then run
`sudo apt install ./filename.deb` with its exact filename. Close and relaunch
Among Terminal after the update.

There is no Among APT repository yet: `apt upgrade` does not download newer
Among releases automatically. An RC of the same base version sorts below the
stable version; do not downgrade an existing stable installation to that RC.

```sh
sudo apt remove among-terminal
```

Your preferences, sessions and separately installed plugins are kept in your
home directory. Removing the DEB does not remove another Snap, Cargo or
source-built copy.

## Package contents and integrity

The DEB installs the application, desktop entry, icon and licence notices.
Example plugins are provided but disabled by default. See [using plugins](/plugins/).

The [release page](https://github.com/Among-Terminal/among/releases/tag/v0.1.0-rc.2)
provides checksums, matching source materials and build/check provenance.
Checksums detect changed files; they are not a separate publisher signature.
Installed CI checks cover X11/Xvfb, not full stable acceptance or GNOME/Wayland
certification. See the release notes for the exact scope and known limitations.

## For developers

To compile or modify the application, see [building from source](/build/).
Source compilation is not required to install these packages.

---

---
url: https://among-terminal.github.io/shortcuts.md
---

# Keyboard shortcuts

The header's left controls are Settings, sidebar toggle, then New workspace.
`Ctrl+Shift+T` (or your configured replacement) also creates a workspace.

Edits in Preferences are saved immediately and restored on the next launch,
including removed bindings and actions displaced by a shortcut reassignment.
Storage is `$XDG_CONFIG_HOME/among/shortcuts.json` (or
`~/.config/among/shortcuts.json`); see [Preferences storage](/preferences/).
If saving fails, the edit remains session-only and Preferences shows a warning.

Bindings live in a single registry (`src/shortcuts.rs`), which is what makes them
inspectable and changeable without touching the code that uses them.

## Defaults

| Action | Binding | Notes |
| --- | --- | --- |
| Focus up | `Alt+Up` | no neighbour in that direction: no change |
| Focus down | `Alt+Down` | no neighbour in that direction: no change |
| Focus left | `Alt+Left` | no neighbour in that direction: no change |
| Focus right | `Alt+Right` | no neighbour in that direction: no change |
| Activate workspace 1 | `Alt+1` | beyond the last workspace: no change |
| Activate workspace 2 | `Alt+2` |  |
| Activate workspace 3 | `Alt+3` |  |
| Activate workspace 4 | `Alt+4` |  |
| Activate workspace 5 | `Alt+5` |  |
| Activate workspace 6 | `Alt+6` |  |
| Activate workspace 7 | `Alt+7` |  |
| Activate workspace 8 | `Alt+8` |  |
| Activate workspace 9 | `Alt+9` |  |
| New workspace | `Ctrl+Shift+t` | becomes the active workspace |
| Split pane | `Ctrl+Shift+n` | orientation chosen from the pane's shape |
| Grow pane | `Ctrl+Shift+Right` | one step; only that split moves |
| Shrink pane | `Ctrl+Shift+Left` | one step; only that split moves |
| Close pane | `Ctrl+Shift+w` | cascades to the workspace, then to exit |
| Open preferences | `Ctrl+,` | shortcuts and plugins |
| Toggle fullscreen | `F11` | returns to the previous size |
| Toggle pane zoom | `Ctrl+Shift+x` | fills the workspace; again restores |
| Next workspace | `Ctrl+PageDown` | wraps around |
| Previous workspace | `Ctrl+PageUp` | wraps around |

This list is generated from the running registry, so it cannot drift from what
the application installs:

```sh
AMONG_LIST_BINDINGS=1 among
```

Several of these are additions beyond the five originally requested. They exist
because the specification requires a keyboard path to each behaviour, and a
required behaviour with no way to reach it is not implemented: divider resizing,
workspace cycling, preferences, fullscreen, and pane expansion.
`Ctrl+Shift+Arrow` is used for resizing so it sits a modifier level away from
`Alt+Arrow` focus movement — adjusting a divider and choosing a direction need
to be distinguishable by touch.

### Why these and not others

The obvious alternative for pane focus is `Ctrl+Shift+Arrow`, as used by several
terminal emulators. `Alt+Arrow` was chosen because it does not collide with
anything on a stock GNOME desktop.

Verified against the live settings schema on the target machine:

* GNOME claims `Ctrl+Alt+Arrow` for switching **its own** workspaces, `Ctrl+Alt+Tab`
  for panels, `Alt+Tab` for applications, and every `Super` sequence for the
  overview.
* None of the defaults above touches those.
* `Ctrl+Shift+T/N/W` are unclaimed by the desktop, and unclaimed by readline and
  zsh.
* `Alt+Arrow` is not bound by the desktop or by GNOME Terminal's own profile.

Binding a sequence the desktop also handles would make the action silently never
fire, which looks like a broken application rather than a conflict. The registry
reports such bindings instead of accepting them (`is_reserved_by_desktop`).

## Splitting

There is one split binding, not separate horizontal and vertical ones. The
orientation comes from the shape of the pane being split:

* width ≥ height → a **vertical** divider, so the two panes sit side by side
* height > width → a **horizontal** divider, so the two panes are stacked

Comparing the two extents directly, rather than their ratio, matches the
intuition that a wide area divides better across. This is the same behaviour as
Terminator's `split_auto`.

The new pane receives focus, so typing continues where the user last was looking.

## Running an action without a key

```sh
AMONG_ACTION=split_pane among
```

Accepted names: `new-workspace`, `split-pane`/`split`, `close-pane`/`close`,
`focus-up`, `focus-down`, `focus-left`, `focus-right`, `next-workspace`,
`previous-workspace`, `workspace-N`.

The environment is used rather than a command-line flag because GApplication
parses and rejects any option it does not recognise, which makes a custom flag
unusable.

Invoking an action that has no binding reports it instead of doing nothing
silently:

```sh
AMONG_ACTION=fly-away among
# among: unknown action name in AMONG_ACTION
```

## Rebinding

Overrides are read at startup and applied to the running process:

```sh
AMONG_REBIND="split-pane=<Control><Shift>d" among
```

Several entries are separated by commas. An unusable accelerator or an unknown
action name is reported and ignored rather than accepted:

```sh
AMONG_REBIND="split-pane=<<bad" among
# among: `<<bad` is not a usable accelerator
```

Binding a sequence that another action already holds transfers it, so the mapping
from sequence to action stays a function — the previous holder becomes unbound.

## Preferences

`Ctrl+,` opens a preferences window with two pages.

**Keyboard** lists every action the application can perform, including ones with
no binding — a list of only the bound actions would hide half of what can be
configured. Select a row to capture a new combination; select it again to cancel,
or press Escape to remove the binding. A rebind applies immediately,
without restarting.

A sequence the desktop handles first is refused rather than stored, because the
action would then never fire — the same reason the defaults avoid `Super` and
`Ctrl+Alt`.

**Plugins** lists every configured plugin with its state: running, disabled, not
installed, stopped, or speaking an incompatible protocol version. The switch
starts or stops the plugin; stopping one withdraws its content immediately rather
than leaving it frozen on screen. Plugins that are missing or incompatible cannot
be switched on, since there is nothing to start.

## How shortcuts are wired

Actions are registered as `gio::SimpleAction`s on the window and the keys are
attached with `GtkApplication::set_accels_for_action`, under the `win.` prefix.

This is not an arbitrary choice. A `GtkShortcutController` looks like the obvious
tool, but its default `LOCAL` scope is consulted *after* the focused widget — and
a terminal consumes every key it receives. The result is that no application
shortcut fires at all while the terminal has focus, which is the only state that
matters. `GLOBAL` scope fixes the ordering, but the action-and-accelerator route
is the one GTK itself uses for application shortcuts and is what is done here.

Unclaimed sequences still reach the terminal: GTK only consumes what a registered
accelerator matches.

## Global shortcuts

Everything above is *inside* the window, and takes effect only while the
application has focus. A desktop-wide shortcut — one that works while another
application is focused — is a different mechanism: it has to be registered with
the desktop shell.

On GNOME that means a custom keybinding in
`org.gnome.settings-daemon.plugins.media-keys`, whose command invokes the
application. The neighbouring `glagol` project does exactly this in its
`hotkeys.rs`, and that approach is the one to copy if a shortcut has to work from
outside the application.

## Unrecognised keys

Anything the application does not claim is delivered to the focused terminal
unchanged. A shortcut is handled by a `ShortcutController` on the window, and GTK
delivers accelerators before the focused widget, so a claimed sequence never
reaches the terminal while everything else falls through.

This matters for a terminal: an application shortcut that leaked into the shell
would insert stray text into a running command.

---

---
url: https://among-terminal.github.io/licensing.md
---

# Licensing

Among Terminal's original code, example plugins and artwork use
[Apache-2.0](https://github.com/Among-Terminal/among/blob/main/LICENSE).
AppStream catalog metadata uses CC0-1.0.

Third-party dependencies retain their own licenses. Rust dependency notices are
preserved in [THIRD_PARTY](https://github.com/Among-Terminal/among/tree/main/THIRD_PARTY)
and [NOTICE](https://github.com/Among-Terminal/among/blob/main/NOTICE).

The application dynamically links native GTK, libadwaita and VTE libraries.
Their LGPL terms are not replaced by the application's Apache license.
Distributors must preserve applicable notices and license texts and satisfy
corresponding-source and library replacement/debugging obligations for the
components they actually ship.

See the repository's [distribution obligations](https://github.com/Among-Terminal/among/blob/main/docs/licensing.md)
and [source delivery instructions](https://github.com/Among-Terminal/among/blob/main/docs/source-delivery.md).
A build or generated inventory alone does not establish license compliance.

---

---
url: https://among-terminal.github.io/panes.md
---

# Panes

A pane is a container holding one terminal together with the application's own
interface around it. This is what the container looks like:

```
+------------------------------------------+
| title, and any plugin content for the pane|   <- the header, and the drag handle
+------------------------------------------+
|                                          |
|               terminal                   |
|                                          |
+------------------------------------------+
| plugin footer content, when there is any |   <- hidden while empty
+------------------------------------------+
```

## Dragging a pane to a new position

A pane can be moved by dragging its header onto another pane. While the drag is
in progress the target shows which half the pane would occupy, and dropping
divides the target's area in half along that edge.

* Drop on the **left** or **right** part of a pane: the two end up side by side.
* Drop on the **top** or **bottom** part: the two end up stacked.
* The indication follows the pointer between edges, so the result is known before
  the pane is dropped.
* A drag that leaves every pane, or ends anywhere else, changes nothing.

The header is the handle rather than the whole pane, because dragging across a
terminal body is text selection — a gesture a terminal user relies on constantly.

A moved pane keeps its identity: the terminal and the process running in it are
the same afterwards, and focus follows the pane to its new position. The space
the pane vacated is reclaimed by whatever shared it, so no gap is left behind. A
drop on a pane's own area does nothing.

## Headers and the terminal's title

Clicking a terminal or its header makes that pane active: keyboard input, pane
actions and the focused highlight follow the same pane. Dragging within terminal
text remains selection; only the header is a pane-movement handle.

A pane's header shows the title the program in that terminal has set, through the
usual OSC escapes, alongside a permanent `#N` identity label supplied by the host.
Workspace terminal counts in both sidebar forms also belong to the host and do
not require a plugin. Programs use titles to advertise what they are doing.
Examples include a file
open in an editor, a host being connected to, a build in progress — so the header
is the natural place to read it.

When a title changes on a pane that is **not** focused, the header is marked and
stays marked until that pane is focused. A title change on the focused pane leaves
no mark, because the user is already looking at it.

A pane whose terminal has never set a title, which is rare because most shells do
at every prompt, falls back to showing the pane's number.

Plugin content for the pane's header appears beside the title; neither replaces
the other. See [plugins](/plugins/).

## Terminal context menu

Right-click a terminal, or press **Shift+F10** in the focused terminal. If the
program has enabled mouse reporting, an ordinary right-click goes to that
program; use **Shift+right-click** for Among's menu instead. Arrow keys navigate
the menu, **Enter** activates a row, and **Escape** returns to terminal input.

The menu belongs to the requesting pane, not whichever pane was previously
focused. It uses symbolic icons alongside text labels. Copy uses selected text,
Paste delegates to VTE (including bracketed paste when enabled by the program),
and Select All selects terminal text. Copy is disabled without a selection;
Paste is disabled when the clipboard offers no text.
Both states update while the menu is open. Select All includes available
scrollback and blank terminal rows; Copy preserves the resulting text. Paste
sends text to the receiving program rather than replaying a saved session. A
shell may interpret pasted newlines, so do not paste untrusted commands.

At a pointer target, explicit hyperlinks take precedence over plain absolute
http/https/mailto URLs. Copy Link uses the captured URI even if the pointer later
moves. Other valid explicit schemes are copy-only; Open Link is disabled for them.
Malformed, control-containing and oversized targets are not offered. Keyboard
invocation has no link target and omits link entries. Open Link requests the
desktop's handler asynchronously; failures are reported without shell execution.

Split Pane, Expand/Restore Pane and Close Terminal use the same operations as
their shortcuts. The menu remains available when those shortcuts are unbound;
its hints follow the current bindings. Closing the last terminal still asks for
confirmation rather than silently exiting.

## Closing and exiting

Closing the focused pane focuses the sibling that expands into its space. If
that sibling is split, its first leaf in tree order wins. Closing a background
pane preserves focus; process exit follows the same rule.

A pane is a terminal window and the application is what surrounds it, so closing
cascades upward:

```
Ctrl+Shift+W    the pane and its process go, the layout closes up
  last pane     the workspace closes too
    last one    a confirmation appears before the application exits
```

A pane also closes when the process in it exits — typing `exit`, or a program
that ends — following the same cascade. The exit is reported, naming the status
when it is not zero, so a terminal disappearing is never mistaken for something
the user did. Closing the window with the platform's close control takes the same
path, including the confirmation.

The cascade stops at the last workspace: it asks rather than exiting, because
every terminal's process goes with it.

## Expanding a pane

`Ctrl+Shift+X` expands the focused pane to fill its workspace, and pressing it
again restores the layout.

Only the rendering changes. The layout tree is untouched, so restoring brings
back every pane at exactly the size and position it had, nested dividers
included, and no terminal is restarted. Closing the expanded pane simply returns
the workspace to its normal layout. Expanding in one workspace does not affect
any other.

---

---
url: https://among-terminal.github.io/plugin-development.md
---

# Plugin development

Plugins are separate executables using newline-delimited JSON on stdin and stdout.
They run as your user, not in a security sandbox. Install only trusted code.

[Installing and enabling plugins](/plugins/#installing) · [Protocol reference](#protocol)

## Writing one

### Third-party plugin quick start

Plugins run as your user, not in a security sandbox. Install only code you trust.
They can use any language; the host launches the file directly, so scripts need
a shebang, executable permissions and an installed interpreter. Only protocol
JSON lines belong on stdout, and every reply must be flushed.

Create an independent Cargo package with a JSON dependency:

```sh
cargo new --bin my-status
cd my-status
cargo add serde_json@1
```

Replace `src/main.rs` with:

```rust
use std::io::{self, BufRead, Write};
use serde_json::{json, Value};

fn main() -> io::Result<()> {
    let stdin = io::stdin();
    let mut stdout = io::stdout();
    for line in stdin.lock().lines() {
        let Ok(line) = line else { continue };
        let Ok(message) = serde_json::from_str::<Value>(&line) else { continue };
        let kind = message["type"].as_str().unwrap_or_default();
        let reply = match kind {
            // The host is going away; stop rather than block on stdin.
            "shutdown" => break,
            "hello" => json!({"type": "hello", "major": 1, "minor": 1}),
            "status" => {
                // Only the app header carries fragments; every other scope
                // gets an empty list, which the host renders as nothing.
                let fragments = if message["scope"] == "app_header" {
                    json!([{"text": "Hello", "priority": 10}])
                } else {
                    json!([])
                };
                json!({
                    "type": "status",
                    "request_id": message["request_id"].as_i64().unwrap_or_default(),
                    "refresh_ms": 2000,
                    "fragments": fragments,
                })
            }
            _ => continue,
        };
        // Every reply must be flushed: the host reads line by line and a
        // buffered reply is indistinguishable from a hung plugin.
        writeln!(stdout, "{reply}")?;
        stdout.flush()?;
    }
    Ok(())
}
```

Build it and install it under the same name you will register:

```sh
plugin_dir="${XDG_DATA_HOME:-$HOME/.local/share}/among/plugins"
mkdir -p "$plugin_dir"
cargo build --release --locked
install -m 755 target/release/my-status "$plugin_dir/my-status"
```

Add `{"name": "my-status", "enabled": false}` to the `plugins` array in
`${XDG_CONFIG_HOME:-$HOME/.config}/among/plugins.json`, preserving other entries
and fields. If the file does not exist, create it with:

```json
{"plugins": [{"name": "my-status", "enabled": false}]}
```

The configuration name is the installed filename, not a path or display title.
The host reads registered names at startup and lists only those whose files
exist in the plugin directory. Merely copying a file there does **not** add it
to Settings. Restart Among Terminal when it is safe to close its terminal
sessions, then open Settings → Plugins and enable `my-status`; `Hello` will
appear in the application header. A protocol or launch failure is shown as
Faulted rather than Running. For an already registered plugin update, disable
it, replace its file, then re-enable it; no host restart is needed.

For compiled Rust plugins, start with the independent package below; for other
languages, use the same JSON-lines protocol documented above. There is no GTK
dependency or application SDK requirement.

The independent [example package](https://github.com/Among-Terminal/among/blob/main/examples/plugins/Cargo.toml) contains
standalone binaries and [shared stdio plumbing](https://github.com/Among-Terminal/among/blob/main/examples/plugins/src/protocol.rs).
It does not depend on or link the host. Within that package, a binary can use:

```rust
use among_example_plugins::protocol::{run, Status};
use serde_json::json;

fn main() -> std::process::ExitCode {
    run(|scope, _context| Status {
        refresh_ms: Some(2000),
        fragments: if scope == "app_header" {
            vec![json!({"text": "Hello", "priority": 10})]
        } else {
            Vec::new()
        },
    })
}
```

The loop handles the version 1.0 handshake, request IDs, malformed JSON, events,
flushing, EOF and shutdown. For a third-party package, implement that same wire
contract or reuse the independent example code; no application library is needed.

`pane-pwd` reports each pane's last known directory, including its actual initial
shell directory. Later changes require OSC 7; an unknown directory emits no content.

Test the binaries and their real stdio replies with:

```sh
cargo test --locked --manifest-path examples/plugins/Cargo.toml
```

## Protocol

### Host to plugin

Every message has a `type` field.

```jsonc
// Sent once when the plugin starts.
{"type": "hello", "major": 1, "minor": 0}

// Collect data now. Answer with a status message carrying the same request_id.
{"type": "status", "request_id": 7, "scope": "pane_header:1", "context": {
  "active_workspace": 0,
  "workspace_count": 2,
  "focused_pane": 1,
  "terminals": [
    {"pane": 1, "workspace": 0, "cwd": "/home/demo/projects", "title": "bash", "running": true}
  ]
}}

// Something happened the plugin may care about.
{"type": "event", "event": {"kind": "working_directory_changed"}, "pane": 1, "detail": "/tmp"}

// The host is stopping.
{"type": "shutdown"}
```

Event kinds are `pane_opened`, `pane_closed`, `process_exited`, `working_directory_changed`,
and `workspace_activated`.

### Plugin to host

```jsonc
// Reply to hello. The major version must match the host's.
{"type": "hello", "major": 1, "minor": 0}

// The answer to a status request.
{"type": "status", "request_id": 7, "refresh_ms": 2000,
 "fragments": [
   {"icon": "git-branch-symbolic", "text": "main*", "style": "warning", "priority": 20,
    "tooltip": "Uncommitted changes present"}
 ]}
```

`refresh_ms` is how often the data changes:

* A number means the host will re-ask after at most that many milliseconds.
* `null` means event-driven: the host asks when a terminal changes rather than on
  a timer.

That matters for expensive plugins. `git status` on a large repository should
declare a few seconds, or `null` and let terminal events drive it; either way the
host will not poll it faster than asked.

The refresh clock restarts when an answer arrives, not when the question is sent.
Without that distinction one slow plugin gets asked on every tick — for `git
state` that means forking a subprocess tens of times a second, which starves the
other plugins of response time.

## Scopes

Where content is shown. A plugin is told which scope it is answering.

| Scope                  | Appears                                    |
|------------------------|--------------------------------------------|
| `app_header`           | the window's top strip                     |
| `app_footer`           | the window's bottom strip                  |
| `workspace_header`     | above the active workspace's panes         |
| `pane_header:<id>`     | above that pane's terminal                 |
| `pane_footer:<id>`     | below that pane's terminal                 |
| `workspace_summary:<n>`| beside workspace `n`'s name in the sidebar |

The sidebar summary takes the first fragment of the response. Several plugins may
each contribute one, and all of them are shown — one plugin never replaces
another's content, and a plugin supplying more content never causes another's to
be dropped.

A pane header belongs to that pane alone: content supplied for one pane does not
appear in another pane, nor in the workspace as a whole.

## Fragments

A fragment is pure data. The host decides how to draw it, which is why a plugin
cannot break the layout by producing something oversized.

```jsonc
{
  "text": "main",          // optional; may be omitted if an icon is given
  "icon": "folder-symbolic", // optional GTK icon name
  "style": "success",      // success | warning | error | accent | dim
  "tooltip": "Clean tree", // optional
  "priority": 20           // lower sorts first within a slot
}
```

`style` is a closed set, and these are all of its names:

| Name | Conveys |
| --- | --- |
| `success` | the thing reported is in good order |
| `warning` | it needs attention but nothing is broken |
| `error` | it is broken |
| `accent` | it is worth looking at, with no judgement |
| `dim` | it is present but unimportant |

The first four are coloured from the platform's own semantic colours and are kept
distinct from one another. `dim` is not a sixth colour: it is the ordinary text
at reduced opacity, so quietness is shown by weight rather than by another hue.

Omit `style` entirely for ordinary text — that is the default appearance.

A name outside this set, or no name at all, draws the fragment in the default
appearance rather than failing the message. A plugin is never disconnected over a
style it guessed wrong. An icon the theme
does not have is dropped rather than drawn as a broken placeholder, and long text
is elided.

Order within a slot is by `priority`, then by plugin name, so re-sending the same
data never reshuffles a slot.

## Versioning

The protocol version is negotiated at start-up and is independent of the
application's version.

* The **major** version must match exactly. A plugin whose major differs is
  reported as incompatible and its data is ignored — the host does not guess.
* The **minor** version may be lower, so the host can add fields additively
  without breaking existing plugins.

## Failure handling

Plugins are untrusted input. Everything below is discarded and the application
continues:

* A line that is not valid JSON, or does not match the schema.
* A message of a type the host does not know.
* A value out of range: `priority` outside −1000…1000, `text` longer than 512
  characters, or `refresh_ms` above an hour.
* More than 64 fragments in one response.
* A fragment with neither text nor an icon.

A plugin that crashes, exits, or does not answer within the timeout is marked
faulted and stopped. Its content is withdrawn rather than left frozen, and it is
restarted later. The application and every terminal stay usable throughout.

Standard error is discarded by the host. Use a protocol `error` response for a
diagnostic, or exit nonzero for an unrecoverable failure so the host notices it;
printing to stderr alone does not reach the user.

Because the pipe to a plugin is separate from the interface, a plugin stuck in a
long computation cannot freeze the window: the host reads its output off the main
loop and applies a timeout instead of waiting inline.

---

---
url: https://among-terminal.github.io/preferences.md
---

# Preferences storage

The storage module uses `$XDG_CONFIG_HOME/among`, falling back to
`$HOME/.config/among` when XDG_CONFIG_HOME is absent or empty.

Plugin choices keep the existing `plugins.json` format:

```json
{"plugins": [{"name": "clock", "enabled": false}]}
```

Shortcut overrides use `shortcuts.json`, version 1:

```json
{"version": 1, "overrides": {"split-pane": "<Control><Shift>b", "toggle-zoom": null}}
```

An absent override inherits the current default; null explicitly removes a
binding. Unknown fields and entries are retained when saving other preferences.
Malformed files and unsupported versions are not automatically overwritten.

Writes use a private temporary file in the destination directory and atomic
replacement. Failures before replacement preserve the prior document; failures
confirming directory durability after replacement report uncertainty. Symlink
destinations are refused. Independent external edits are merged when detected;
simultaneous writes by external editors are not fully serialized.

## Changing preferences

Accepted edits in both Preferences pages apply immediately and are saved without
a Save button. Fresh launches restore plugin choices and shortcut overrides.
Reassigning an occupied shortcut also saves the displaced action as unbound.
Cancelled capture and rejected/no-op edits do not write new overrides.

A failed write leaves the edit active for this session and shows a warning in
Preferences and a notification. A later edit in the same settings category retries
pending changes; successful saving clears that category's warning. Repair malformed
files or directory permissions before retrying. Startup errors are visible too.
Plugin faults do not change the saved desired enabled state.

Clock, resources and pane PWD remain optional and disabled by default. Only explicit
user changes enable them. No terminal contents or workspace layouts are saved here.

Developer checks are described in [the contributing guide](https://github.com/Among-Terminal/among/blob/main/CONTRIBUTING.md#checking-changes).

---

---
url: https://among-terminal.github.io/sessions.md
---

# Sessions

Session snapshots live at `${XDG_DATA_HOME:-$HOME/.local/share}/among/session.json`.
This is independent of `plugins.json` and `shortcuts.json`: saving a session does
not rewrite preferences, install plugins or modify shell configuration.

## Saving and restoring

A new application process with a valid snapshot asks **Restore** or **Start new**.
Restore recreates each terminal as a fresh shell in its saved directory, including
inactive workspaces, and restores the active workspace and its focused pane.
It does not resume old processes, repeat commands, restore scrollback or retain
temporary pane zoom. The window opens maximized as usual.

Start new (also Escape) opens the usual single-terminal workspace. Its next
checkpoint replaces the previous session. Closing the window while the prompt is
still open exits without launching terminals or altering the old snapshot.
Activating an already running application does not ask again.

Changed session state is checkpointed every two seconds by a separate ordered
writer, normally reaching disk within three seconds. Unchanged state does not
cause disk writes. Confirmed application exit saves the latest model before
terminal teardown; canceling exit keeps the live session running. A crash can
lose changes newer than the last completed checkpoint. Power loss or a storage
error can lose more: there is no unconditional durability guarantee.

If a saved directory is deleted or inaccessible, the shell uses an accessible
home or startup directory. Settings shows affected panes. VTE can silently fall
back during spawning; the host reads the new process's actual `/proc/<pid>/cwd`
rather than assuming the requested path was used. Only the actual known location
is recorded. New ordinary terminals retain the normal startup directory.

For directory changes after launch, the shell must publish OSC 7. See the tested
[Bash integration](/plugins/#live-status-examples). This does not require enabling
pane-pwd or any other plugin, and Among Terminal never edits your shell files.
For example, after enabling the optional Bash hook, `cd /tmp` is recorded on the
next checkpoint even when the workspace is inactive.

Storage failures are reported in Settings without blocking terminal input. Later
checkpoints retry after the problem is fixed. Invalid or future-version documents
are preserved until externally corrected or removed. A failed final save asks
whether to keep working or exit without saving; keeping the window open resumes
checkpoint retries. Routine checkpoints do not show success notifications.

## Snapshot format

Version 1 stores workspace order, names, colours, the active workspace index,
per-workspace focus, nested split orientations/ratios and a directory entry for
each pane. `vertical` means a vertical divider (panes side by side), while
`horizontal` means a horizontal divider (panes stacked). Ratios describe the
first child's fraction, not pixels, and must lie between 0.05 and 0.95.

```json
{
  "version": 1,
  "active": 0,
  "workspaces": [
    {
      "name": "project",
      "colour": 0,
      "focused": 1,
      "layout": {"type": "pane", "id": 1},
      "directories": [{"pane": 1, "cwd": null}]
    }
  ]
}
```

Pane IDs are nonzero and unique across all workspaces. Sparse IDs retain their
numbers without reserving an array up to that number; exhausted IDs prevent new
pane creation instead of wrapping. Each focused ID must belong to that workspace.
Directory entries must exactly match its leaves. Paths are absolute or `null`
when unknown; they come from terminal-reported cwd or a known initial shell
directory, never another pane's cwd. Changes after launch need shell OSC 7 reporting
to be known reliably. No plugin is required to collect these reports.

The file contains no commands, process IDs, shell environment or scrollback.
Input is bounded to 8 MiB, 64 nested splits, 4096 panes and 256 workspaces;
unreadable, malformed, unsupported or unsafe files are not silently overwritten.
The loader also retains the JSON parser's recursion safety limit.

New snapshot files are private (mode 0600). Existing stricter permissions are
preserved. Saving writes and syncs a same-directory temporary file, then renames
it atomically and syncs its directory. A failed replacement retains the previous
complete file; a directory-sync error after replacement means the new file was
written but its power-loss durability is uncertain. Symlink and non-regular
destinations are refused. Manually editing a snapshot while it is being saved
can produce a retryable concurrent-change warning.

---

---
url: https://among-terminal.github.io/plugins.md
---

# Plugins

A plugin is an executable run directly by Among Terminal as a separate process.
The host supplies no interpreter. Any language works if its installed executable
can run on the system; scripts may use a shebang and must provide their runtime.
Plugin code is never loaded into the application, and
that is the whole point: a plugin that segfaults, hangs, or misbehaves takes only
itself down, while the live terminals — which hold whatever the user is running —
stay up.

The cost is a process spawn and messaging round trips. Compiled examples also
require a build step, unlike a script that can be copied with its runtime available.

The exchange is newline-delimited JSON on the plugin's stdin and stdout. Nothing
else is shared. There is no GTK type, no widget handle, and no function pointer
crossing the boundary, so there is no ABI for either side to break.

## Live status examples

Host protocol 1.1 adds optional `meter` on a fragment: a finite fraction from 0
to 1 rendered as a compact GTK bar. Keep a readable percentage in `text`.
Bars are 50 pixels wide. Their whole track and fill share a continuously changing
hue: green at 0%, yellow at 50%, red at 100%; the track is translucent so the
filled fraction stays distinguishable. Numeric percentages remain a non-color cue.
The host's shared application header and footer use bold monospace by default,
including the clock and N/A labels. Footer text has opacity 0.7; the upper panel
and individual pane footers are not dimmed. Plugins do not select this typography.
Omit or set `meter` to null for N/A. Values outside this range are rejected.
Major 1 is unchanged; 1.0 hosts ignore the field and show only the text.

`clock` shows local 24-hour HH:MM:SS once at the right of the shared application
footer every second, demonstrating a different slot than the resource header.
It uses the process's local timezone configuration (including `TZ`), not UTC.

`system-status` shows labelled graphical CPU, MEM and DISK bars with percentages. CPU samples
the first eight aggregate `/proc/stat` counters: busy is the interval total minus
idle and iowait; guest counters are not counted twice. Startup, reset and zero
intervals show N/A. MEM is `(MemTotal - MemAvailable) / MemTotal`, not a sum that
treats all caches as unavailable. Both are rounded to the nearest percent and
sampled at most once a second. DISK targets `/` using `statvfs`: used is blocks
minus free, divided by used plus available (excluding reserved availability),
rounded upward like `df`. It is sampled at most once every five seconds.
Failed sources show N/A independently. These describe the process's proc/mount
namespace; sandbox figures need not describe the whole host.

`pane-pwd` polls each pane's last terminal-reported directory every second,
including unfocused panes. The full path is in the tooltip; long labels are
truncated. Labels contain only the path, without a `PWD:` prefix. Unknown
directories produce no content; the plugin never substitutes
the host or focused pane's directory. A known initial shell directory is available
at launch; subsequent directory changes require the shell to opt in to OSC 7.

For Bash, test this in a terminal (no shell files are modified):

```sh
among_osc7() {
    local LC_ALL=C directory uri='file://' byte encoded i
    directory=$(pwd -P && printf '.') || return
    directory=${directory%.}
    directory=${directory%$'\n'}
    for ((i=0; i<${#directory}; i++)); do
        byte=${directory:i:1}
        case "$byte" in
            [a-zA-Z0-9/._~-]) uri+=$byte ;;
            *) printf -v encoded '%%%02X' "'$byte"; uri+=$encoded ;;
        esac
    done
    printf '\033]7;%s\007' "$uri"
}
PROMPT_COMMAND="among_osc7${PROMPT_COMMAND:+; $PROMPT_COMMAND}"
among_osc7
```

This optional helper uses Bash builtins, encoding physical-directory bytes rather
than interpreting spaces, non-ASCII names or control characters as URI syntax.
Add it to your own Bash configuration only if wanted.
Try `cd /tmp` and wait up to two seconds for the footer. Other shells require
their own prompt hook; no untested zsh/fish integration is claimed here.

## Installing

Preferences saves explicit enable/disable choices immediately to `plugins.json`
and restores them on startup. A Faulted process remains desired-enabled until
you disable it. Save failures are reported as session-only changes; see
[Preferences storage](/preferences/).

`cargo run --release` builds only the application. It does **not** build this
independent example package, replace installed plugin files or enable new ones.
To build all examples, back up installed copies and add only missing default
configuration entries, run from the repository:

```sh
sh scripts/install-plugins.sh --enable-new
```

Existing configuration fields and enabled/disabled entries are preserved. Backups
are created before replacement. All three plugins are disabled by default;
enable wanted plugins explicitly in Preferences.
Existing explicitly enabled examples stay enabled during upgrades; turn them off
in Preferences if no longer wanted. Backups
are stored under `${XDG_DATA_HOME:-$HOME/.local/share}/among/plugin-backups/`.
To update only selected binaries without changing configuration:

```sh
sh scripts/install-plugins.sh system-status clock
```

Disable/re-enable running plugins in Preferences after replacement. Newly added
configuration names load on the next host startup. A rebuilt host does not
replace an already running single-instance process: another `cargo run --release`
may activate that process. Restart the host only when it is safe to end its live
terminal sessions. Plugin updates alone do not close any terminal.

Merge plugin configuration entries with existing settings rather than replacing
them. Clock and resource plugins are optional demonstrations of status slots.

Plugins are executables in `$XDG_DATA_HOME/among/plugins` (`~/.local/share/among/plugins`),
named after the plugin:

```sh
cargo build --release --locked --manifest-path examples/plugins/Cargo.toml
plugin_dir="${XDG_DATA_HOME:-$HOME/.local/share}/among/plugins"
mkdir -p "$plugin_dir"
install -m 755 examples/plugins/target/release/clock "$plugin_dir/clock"
install -m 755 examples/plugins/target/release/system-status "$plugin_dir/system-status"
install -m 755 examples/plugins/target/release/pane-pwd "$plugin_dir/pane-pwd"
```

Then register them in `$XDG_CONFIG_HOME/among/plugins.json` (`~/.config/among/plugins.json`):

```json
{"plugins": [
  {"name": "clock", "enabled": false},
  {"name": "system-status", "enabled": false},
  {"name": "pane-pwd", "enabled": false}
]}
```

Configuration is read leniently, because one broken entry must not stop the
application from starting:

* A missing file, unparsable JSON, or a file without a `plugins` key means no
  plugins are loaded.
* A plugin named in the configuration that is not installed is reported and
  skipped; the rest still load.
* An entry without a `name` is skipped.

### Updating an installed example

Changing an example in this repository does not update the installed copy.
Build first, then replace the selected installed executable at the same name:

```sh
cargo build --release --locked --manifest-path examples/plugins/Cargo.toml
install -m 755 examples/plugins/target/release/clock "${XDG_DATA_HOME:-$HOME/.local/share}/among/plugins/clock"
```

Disable and re-enable `clock` in preferences to start the updated copy
without closing any terminals.
Replacing an old script with the binary does not require deleting it first.
An already-running process keeps executing its old code until restarted.

## Develop a plugin

See [plugin development](/plugin-development/) for a Rust quick start and the JSON-lines protocol.