pencere is an open protocol for terminals.
Let some light into your terminal.
It lets a program show a real interface in the pane it runs in, on your machine or on a server over plain ssh.
A program takes its pane, and gives it back.
The way a full-screen program like vim takes the screen. But what it puts there is a real interface, not a grid of characters.
-
ssh shop-01+
~ $ ssh shop-01
shop-01 ~ $ dockerpen
It starts like any command.
At a prompt, on your machine or on a server over plain ssh.
-
Its view takes the pane.
The program does not draw it. It hands the terminal the view's files, and the terminal draws them, on your machine.
-
ssh shop-01+
~ $ ssh shop-01
shop-01 ~ $ dockerpen
shop-01 ~ $
It ends, and the shell is back.
What was on the screen is there again, as after any full-screen program.
While the view is up, the program and the view talk in six small messages. The view sends call,
subscribe and cancel; the program sends response, push and
progress. That is the whole protocol, and it is the same for every kind of view.
-
Plain ssh is enough
The messages ride in the terminal's own stream: no port, no extra connection, nothing to set up on the server.
-
The terminal's font and theme
A view can be a Lua script that the terminal draws itself, with the pencere kit, in its own font and theme. Or it can be a web page, which is told the terminal's colours and font.
-
Kept in a sandbox
The view runs on the machine of the person looking at it. A script gets nothing it was not handed; a web page reaches nothing but its own program unless the program names a domain and the person allows it.
-
Text where there is no host
A program in a terminal that does not support pencere is told so, and can fall back to text.
Programs made with it.
Each is one file, and shows a real interface in the pane it runs in, on your machine or on a server over plain ssh, in the font and the theme of your terminal.
- textpen A code editor: the project's files as a tree, tabs, search across them, and what git says of them.
-
toppen
A system monitor in the way of
topandbtop: CPU, memory, network, disks, GPU and a process table you can sort and act on. - dockerpen Docker in the pane: containers, their logs and resource use, images, volumes, networks and disk.
- sqlpen A SQL client for PostgreSQL and SQLite: the tables of the database, an editor that knows SQL, and the rows in a grid.
- pickpen Choose rows in the middle of a pipeline: filter, sort and mark them, and the rows you chose go out on stdout.
- linearpen Your Linear issues in a pane, an issue open beside them, and Claude, Codex or Cursor started on it in the pane next to it.
-
Your own
pencere newstarts one, in Lua, TypeScript or Rust.
Write one.
The same program: a view, one call it answers, and one topic it feeds. Whichever you write it in, it is one file to hand to someone, and pencere new <name> --lang lua|ts|rust starts it for you.
Run by the pencere command (pencere build makes one executable of it).
local pencere = require("pencere")
pencere.serve { -- shows src/view/: page.lua, a script of the kit's page API, drawn by the terminal
calls = { hello = function(params) return { message = "Hello, " .. params.name .. "!" } end },
topics = {
clock = function(_, sub)
local timer = pencere.time.every(1, function() sub:push({ now = pencere.time.now() }) end)
sub:on_end(function() timer:cancel() end)
end,
},
fallback = function() print("This terminal shows no views.") end,
}
On Node, Deno or Bun (deno compile makes one executable of it).
import { bundleFromDirectory, serve } from "@pencere/sdk";
await serve({
views: [{ kind: "web", bundle: await bundleFromDirectory(new URL("./view/", import.meta.url)) }],
calls: { hello: (params) => ({ message: `Hello, ${(params as { name: string }).name}!` }) },
topics: {
clock: (_params, subscription) => {
const timer = setInterval(() => subscription.push({ now: Date.now() / 1000 }), 1000);
return () => clearInterval(timer);
},
},
fallback: () => console.log("This terminal shows no views."),
});
With the pencere crate.
let outcome = pencere::serve(
Options::new()
.view(View::web(Bundle::from_dir("view", "index.html")?))
.call("hello", |params, _call| Ok(json!({ "message": format!("Hello, {}!", params["name"]) })))
.topic("clock", |_params, subscription| {
let feed = subscription.clone();
std::thread::spawn(move || {
while feed.push(json!({ "now": now() })) && !feed.sleep(Duration::from_secs(1)) {}
});
Ok(())
})
.fallback(|_| println!("This terminal shows no views.")),
)?;
Start
The pencere command makes, runs and packs an app. It installs with one line, on macOS and Linux.
curl -fsSL https://raw.githubusercontent.com/bateri/pencere/main/cli/install.sh | sh
A program in TypeScript or Rust takes the library instead: npm install @pencere/sdk, cargo add pencere.
The kit
What a view the terminal draws is written with: elements and their layout, an editor of text, and a library of components.
See the kitAny terminal can host it.
bateri is the first terminal that hosts pencere. The specification, the libraries and the tools are all under Apache-2.0, so any terminal or program, open or closed, can implement the protocol or embed this code.
-
A library for hosts
The crate
pencere-hostis a Rust library for terminals that host views. It does no I/O. -
Early
Everything is 0.x, and a minor release may still break.