tmux client library for Swift

Control tmux, connect to and create servers, navigate sessions, windows, and panes, send keys, watch for changes via control mode, capture pane contents.

Quickstart

Install the package and run a complete program.

Topics

Subject-by-subject, with Swift in every code block.

Examples

Complete programs, sourced from the code each port tests.

Testing

Test code that uses tmux with an isolated server.

Install

.package(url: "https://github.com/libtmux/libtmux-swift", from: "0.1.0")

At a glance

Server → Session → Window → Pane. Each level of the tmux hierarchy has its own entry in the Swift API, with the tmux object it wraps.

Type	Wraps
`Server`	A tmux server
`Session`	A session, ID `$n`
`Window`	A window in a session, ID `@n`
`Pane`	A pane in a window, ID `%n`

What it does

Start with Swift

+ Error handling + Cleanup

import Foundation
import LibTmux

@main
struct Quickstart {
    static func main() async throws {
        let server = try Server(
            socketName: "libtmux-home-\(UUID().uuidString)",
            configurationFile: "/dev/null"
        )

        try await work(server)
    }

    static func work(_ server: Server) async throws {
        let session = try await server.newSession(
            named: "work",
            windowName: "editor",
            shell: "/bin/sh"
        )
        let logs = try await server.newWindow(
            in: session,
            named: "logs",
            shell: "/bin/sh"
        ).window
        let pane = try await server.splitWindow(logs, direction: .right)

        try await server.run("printf '\\nhello from %s\\n' libtmux", in: pane)

        let ready = try RegexPattern("^hello from libtmux$")
        let result = try await server.waitForOutput(
            in: pane,
            matching: [ready],
            timeout: .seconds(5)
        )
        guard result.outcome == .matched else {
            throw QuickstartError.outputTimedOut
        }

        for line in result.tail where line == "hello from libtmux" {
            print(line)
        }
    }

    enum QuickstartError: Error {
        case outputTimedOut
    }
}

import Foundation
import LibTmux

@main
struct Quickstart {
    static func main() async throws {
        let server = try Server(
            socketName: "libtmux-home-\(UUID().uuidString)",
            configurationFile: "/dev/null"
        )

        do {
            try await work(server)
        } catch {
            print("tmux quickstart failed: \(error)")
            throw error
        }
    }

    static func work(_ server: Server) async throws {
        let session = try await server.newSession(
            named: "work",
            windowName: "editor",
            shell: "/bin/sh"
        )
        let logs = try await server.newWindow(
            in: session,
            named: "logs",
            shell: "/bin/sh"
        ).window
        let pane = try await server.splitWindow(logs, direction: .right)

        try await server.run("printf '\\nhello from %s\\n' libtmux", in: pane)

        let ready = try RegexPattern("^hello from libtmux$")
        let result = try await server.waitForOutput(
            in: pane,
            matching: [ready],
            timeout: .seconds(5)
        )
        guard result.outcome == .matched else {
            throw QuickstartError.outputTimedOut
        }

        for line in result.tail where line == "hello from libtmux" {
            print(line)
        }
    }

    enum QuickstartError: Error {
        case outputTimedOut
    }
}

import Foundation
import LibTmux

@main
struct Quickstart {
    static func main() async throws {
        let server = try Server(
            socketName: "libtmux-home-\(UUID().uuidString)",
            configurationFile: "/dev/null"
        )

        do {
            try await work(server)
        } catch {
            if try await server.isRunning() {
                try await server.killServer()
            }
            throw error
        }
        try await server.killServer()
    }

    static func work(_ server: Server) async throws {
        let session = try await server.newSession(
            named: "work",
            windowName: "editor",
            shell: "/bin/sh"
        )
        let logs = try await server.newWindow(
            in: session,
            named: "logs",
            shell: "/bin/sh"
        ).window
        let pane = try await server.splitWindow(logs, direction: .right)

        try await server.run("printf '\\nhello from %s\\n' libtmux", in: pane)

        let ready = try RegexPattern("^hello from libtmux$")
        let result = try await server.waitForOutput(
            in: pane,
            matching: [ready],
            timeout: .seconds(5)
        )
        guard result.outcome == .matched else {
            throw QuickstartError.outputTimedOut
        }

        for line in result.tail where line == "hello from libtmux" {
            print(line)
        }
    }

    enum QuickstartError: Error {
        case outputTimedOut
    }
}

import Foundation
import LibTmux

@main
struct Quickstart {
    static func main() async throws {
        let server = try Server(
            socketName: "libtmux-home-\(UUID().uuidString)",
            configurationFile: "/dev/null"
        )

        do {
            try await work(server)
        } catch {
            print("tmux quickstart failed: \(error)")
            if try await server.isRunning() {
                try await server.killServer()
            }
            throw error
        }
        try await server.killServer()
    }

    static func work(_ server: Server) async throws {
        let session = try await server.newSession(
            named: "work",
            windowName: "editor",
            shell: "/bin/sh"
        )
        let logs = try await server.newWindow(
            in: session,
            named: "logs",
            shell: "/bin/sh"
        ).window
        let pane = try await server.splitWindow(logs, direction: .right)

        try await server.run("printf '\\nhello from %s\\n' libtmux", in: pane)

        let ready = try RegexPattern("^hello from libtmux$")
        let result = try await server.waitForOutput(
            in: pane,
            matching: [ready],
            timeout: .seconds(5)
        )
        guard result.outcome == .matched else {
            throw QuickstartError.outputTimedOut
        }

        for line in result.tail where line == "hello from libtmux" {
            print(line)
        }
    }

    enum QuickstartError: Error {
        case outputTimedOut
    }
}

Run this example

Swift 6.2+, tmux on Linux/macOS

Save the program above as Sources/Main.swift in a new directory, along with the files below.

Cleanup is omitted; the private tmux server and its temporary files may remain. Select Cleanup to remove them when the program finishes. The program stops its private tmux server and removes any temporary files it created when it finishes. Error handling adds diagnostics; every version checks required results and deadlines.

Package.swift

// swift-tools-version: 6.2
import PackageDescription

let package = Package(
    name: "ApiExample",
    platforms: [.macOS(.v13)],
    dependencies: [
        .package(name: "libtmux", path: "libtmux-source")
    ],
    targets: [
        .executableTarget(
            name: "ApiExample",
            dependencies: [
                .product(name: "LibTmux", package: "libtmux"),
            ],
            path: "Sources"
        )
    ]
)

Setup and run

# Save the files above at their displayed relative paths.
git clone https://github.com/libtmux/libtmux-swift.git libtmux-source
git -C libtmux-source checkout --detach 7993e7044347629b08020e9b02ae8bcffa0e5898
swift build --jobs 2 --product ApiExample
.build/debug/ApiExample

Expected output

hello from libtmux

Library revision: 7993e7044347.

Typed API

Typed objects instead of parsed format strings: Pane
Addressing by tmux ID: PaneID
Filtering and queries over tmux objects: FilterExpr
Typed errors instead of exit codes and stderr: TmuxError

What you get over the tmux CLI

Connect to or start a tmux server: Server
Traversal from a server down to its panes: Server.panes()
Send keys to a pane: Server.sendKeys(_:to:literally:)
Watch for changes through tmux control mode: ControlSession
Capture pane contents: Server.capture(_:includingHistory:)
Arguments passed as a list, with no shell quoting: TmuxCommand

Testing

Run tests against an isolated tmux server: withTmuxServer(socketFileName:_:).

Scripting & web

Compiled & native

JVM

.NET

BEAM

tmux

tmux client library for Swift

Quickstart

Guides

Topics

Examples

API reference

Testing

Install

At a glance

What it does

Start with Swift

Setup and run

Expected output

Typed API

What you get over the tmux CLI

Testing