Quick start

Drive tmux from F#: send keys and wait for what a pane prints, run a command to its exit status, and list and filter sessions, windows, panes and clients with typed filters tmux evaluates itself. Every function works on the LibTmux core objects. The F# package and core share a repository, release version, and primary author in the libtmux organization.

Run isolated tmux · Connect to running tmux · Send, wait, read · Query tmux · Stream events

Find a shell, send it keys, wait for its output, and run a command:

open System
open System.Threading
open LibTmux
open LibTmux.FSharp

let runInShellAsync (cancellationToken: CancellationToken) (server: Server) =
    task {
        // List and filter: tmux narrows the listing, then every row is rechecked.
        let! shells =
            server
            |> Server.panes
            |> Query.where (PaneFields.currentCommand |> Filter.oneOf [ "bash"; "sh"; "zsh" ])
            |> Query.list cancellationToken

        match shells |> Seq.tryHead with
        | None -> return None
        | Some pane ->
            // Type a command and wait for what it prints, not for its echo.
            let! ready =
                pane
                |> Pane.sendAndWait cancellationToken (TimeSpan.FromSeconds 10.) "echo ready" "ready"

            // Run a command to its exit status and read what it printed.
            let! listing = pane |> Pane.run cancellationToken (TimeSpan.FromSeconds 30.) "ls /"

            match listing with
            | PaneRun.Exited status -> return Some(ready.Found, status, listing.Output)
            | PaneRun.Ended
            | PaneRun.NotStarted
            | PaneRun.TimedOut -> return None
    }

Building a query reads nothing; Query.list asks tmux, which drops panes that cannot match, and checks every row it returns. Pane.sendAndWait types the line, then waits for a later line to contain the text; the screen before it and the line’s own echo do not count. It sleeps on the pane’s output instead of polling, and ends early if the program exits while it waits. Pane.run returns the lines the command printed, and PaneRun tells a command that exited, with its status, from one whose shell exited first, one that never started, and one that ran out of time. server comes from Server.createOwned, which the quick start below uses to run these steps on an isolated server. Pass a server from Server.connect only with care: the sample types into the first shell it finds, and on a tmux already running that may be the terminal you are reading.

Alpha API: pin a package version and upgrade deliberately. The walkthrough uses .NET SDK 10 and tmux 3.2a through 3.7c on Linux or macOS. The package targets net8.0 and net10.0.

Choose a call¶

Connect¶

Find¶

Type, wait and run¶

Build¶

Observe¶

Recover¶

Caveats¶

• Queries: tmux narrows each listing where it can, and every row is rechecked.
• Waits: Pane.sendAndWait ignores the line’s echo. Every wait ends early when the program exits, and raises TmuxPaneException if it already had. Which wait compares them and their PaneWait outcomes.
• Runs: Pane.run needs a POSIX shell prompt; it refuses fish, PowerShell and a REPL.
• Bounds: a handle from Server.within shares its bound with the sessions, windows and panes taken from it.
• Live state: Mirror.start returns a mirror to use!. Mirror.waitUntil raises when no view matches in time; Mirror.tryWaitUntil returns None.
• Events: inside Control.withSession, Control.events, Control.watchPane and Control.watchPanes read the client it opens, one reader at a time.

Captured sessions, windows, panes, and IDs are the core .NET types. A window linked into more than one session has contextual placements; filtering keeps their order and multiplicity. An uncaptured relationship raises IncompleteSnapshotException rather than behaving as empty.

Quick start¶

Install tmux and make sure it is available on PATH.

Create an F# console project:

$ dotnet new console --language F# --framework net8.0 --output tmux-demo

Enter it:

$ cd tmux-demo

Add LibTmux.FSharp from NuGet; it brings in the matching LibTmux core package and records the selected prerelease version in the project:

$ dotnet package add LibTmux.FSharp --prerelease

Replace Program.fs with this complete program:

open System
open System.Threading
open LibTmux
open LibTmux.FSharp

let runAsync () =
    task {
        use deadline = new CancellationTokenSource(TimeSpan.FromSeconds 30.)
        let token = deadline.Token

        // A server of its own on a private socket, without user configuration.
        let options =
            ServerConnectionOptions(
                SocketName = "fsharp-" + Guid.NewGuid().ToString("N"),
                ConfigurationFile = "/dev/null"
            )

        use! owned = options |> Server.createOwned token

        // One session whose window runs a plain shell, whatever the user's login shell is.
        let! session =
            owned.Value |> Server.newSession token (SessionSpec.running "build" "/bin/sh")

        let! pane = session |> Session.activePane token

        // Type a command and wait for what it prints, not for its echo.
        let! started =
            pane
            |> Pane.sendAndWait token (TimeSpan.FromSeconds 10.) "echo build started" "build started"

        printfn "wait found: %b" started.Found

        // Run a command to its exit status and read what it printed.
        let! result =
            pane |> Pane.run token (TimeSpan.FromSeconds 10.) "printf 'ok\\n'; exit 3"

        match result with
        | PaneRun.Exited status -> printfn "run: exit %d, output %A" status (List.ofSeq result.Output)
        | PaneRun.Ended -> printfn "run: the shell exited first"
        | PaneRun.NotStarted -> printfn "run: the shell was not at a prompt"
        | PaneRun.TimedOut -> printfn "run: still running"

        // List and filter: tmux narrows the listing, then every row is rechecked.
        let! found =
            owned.Value
            |> Server.sessions
            |> Query.where (SessionFields.name |> Filter.startsWith "bu")
            |> Query.list token

        printfn "sessions: %s" (String.Join(", ", [ for listed in found -> listed.Name ]))
    }

runAsync().GetAwaiter().GetResult()

Run it:

$ dotnet run

It prints:

wait found: true
run: exit 3, output ["ok"]
sessions: build

Server.createOwned starts a server on a unique socket, with the tmux on PATH; set ServerConnectionOptions.TmuxBinaryPath to use another. use! stops it when the task ends. The wait succeeds whether the line appeared before or after it began, and the run’s exit status comes from the shell, not from reading the screen. The listing reaches tmux as a filter, so tmux returns only the sessions that match.

The quickstart source is the published block. From a checkout, dotnet run --project examples/LibTmux.FSharp.Quickstart runs it against the source. CI instead passes -p:UsePackageReferences=true, restores only LibTmux.FSharp from freshly packed artifacts, runs the program against real tmux on both target frameworks, and compares what it prints with the block above.

Existing tmux¶

options |> Server.connect ct attaches to a server already running on the socket the options name; use it in place of Server.createOwned for a server your program did not start. Server.connect never starts tmux. Default options resolve the default socket; socket selection explains the configuration order. Code running inside a tmux pane can use Server.FromEnvironment() to locate that pane’s server.

Keep going¶

• Send, wait and read; split panes: owned scopes, waits, runs and live mutation.
• Query tmux, filter captured objects and supported fields: every level, pushdown, screen search, relations and capture depth.
• Choose an execution mode and stream events: scoped clients, cold streams, pane watches, cancellation, and command chains.
• Test code that drives tmux: a private server per test, waits instead of sleeps, and CI setup.
• Share one server across tasks: what handles, waits, runs, control clients and mirrors share.
• Run tmux work in a service: one bounded handle, stopping, retries, one writer per pane, and telemetry.
• Call the core from F# and browse signatures.
• Share tmux with an assistant: the LibTmux.Mcp server, a shared socket, and which F# function each tool matches.
• Read benchmark records: measured core execution modes and benchmark methods.

Compatibility¶

Selection.exactlyOne and Query.exactlyOne return FSharp.Core’s Result, whose compiler-generated ToString formats through printf, which NativeAOT publication rejects. Under NativeAOT, read one row with Query.atMostOne, which still raises on several matches, or with Query.tryExactlyOne where none and several may be treated alike. The NativeAOT consumer runs both.