Core Library0.xAPI Reference

Choose documentation 3

latest

Current version

latest
English

Early release libtmux is released, and its APIs may still change between releases. This site's structure and URLs may change too.

method libtmux-ts latest

Server.newSession

Create a detached session and resolve it as a handle.

Source and package
Qualified name
Server.newSession
Module
server
Declared in
Server
Package
libtmux
Source
packages/libtmux/src/server.ts
Other languages
PowerShell Julia Elixir PythonRubyLuaRustGoJavaC#C++SwiftKotlinScala F#

Description#

Save this complete program as new-session.ts. With Bun 1.4.2 or newer, tmux 3.2a or newer, and libtmux installed, run bun run new-session.ts. It creates and stops a private tmux server. A failed operation or cleanup exits with an error; a cleanup error names the retained socket directory.

Examples#

import { strict as assert } from "node:assert";
import { mkdtemp, readdir, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { Server } from "libtmux";
const directory = await mkdtemp(join(tmpdir(), "ltx-example-"));
const server = new Server({
socketPath: join(directory, "tmux.sock"),
configFile: "/dev/null",
timeoutMs: 5_000,
});
const failures: unknown[] = [];
try {
const session = await server.newSession({
name: "work",
windowName: "editor",
shellCommand: "cat",
startDirectory: directory,
environment: { LIBTMUX_EXAMPLE: "ready" },
});
assert.equal(session.name, "work");
assert.equal(session.windows.one().name, "editor");
assert.equal(session.panes.one().currentPath, directory);
console.log("created:", session.name, session.windows.one().name);
await server.newSession({ name: "review", groupWith: session.id });
await session.newWindow({ name: "logs", shellCommand: "cat" });
const snapshot = await server.snapshot();
const review = snapshot.sessions.one({ name: "review" });
assert.equal(review.windows.count(), 2);
assert.equal(snapshot.sessions.one({ name: "work" }).windows.count(), 2);
console.log(
"grouped review windows:",
review.windows
.map((item) => item.name)
.sort()
.join(", "),
);
} catch (error) {
failures.push(error);
} finally {
try {
if ((await readdir(directory)).includes("tmux.sock")) await server.kill();
await rm(directory, { recursive: true });
} catch (error) {
failures.push(new Error(`Cleanup failed; inspect ${directory}`, { cause: error }));
}
}
if (failures.length > 0) throw new AggregateError(failures, "Example failed");
Parameters

tmux command#

The tmux commands behind newSession.

tmux C API#

The C declarations in tmux that implement these commands.

Each path starts at a function a command runs, which is degree 1. The degree counts steps from there along the path, and each step is a call or a reference: degree 2 is reached from that function, degree 3 from the next, and so on.

Create a session and its first pane

  1. 1 cmd_new_session_exec
  2. calls → 2 spawn_window
  3. calls → 3 spawn_pane
  4. calls → 4 window_add_pane
  5. calls → 5 window_pane_create

Guides#

Pages that discuss newSession.

In other ports#

Create a session

Esc

Type to search.

Reference previewOpen reference