# Attaching to tmux

Source: https://libtmux.org/en/lua/latest/guides/attaching-to-tmux/

> What a plain constructor call actually connects to, and how to find a session that might already exist instead of always creating a new one.

Obtain a server and session handle to control tmux from your program. Your
process keeps its own stdin and stdout, and tmux continues running
independently. [Attach and send keys](/examples/attach-and-send-keys/)
demonstrates this workflow.

Attaching your terminal is a separate operation. Python's `Session.attach()`
runs `tmux attach-session` and hands the terminal to tmux.
[tmuxp](https://tmuxp.git-pull.com/) uses it after building a workspace. Check
your port's reference if your program needs to hand over the terminal.

## Which socket a bare constructor reaches

Use an explicit socket when several tmux servers may be running. The examples
below show each constructor's defaults and environment-aware alternatives. To
locate the server from inside a pane, use the port's environment lookup API for
`TMUX` and `TMUX_PANE`.

Sources: Python's `Server.from_env()` is doctested in `src/libtmux/server.py`
(`pyproject.toml` `testpaths`). .NET's resolution order and `FromEnvironment`
are from `src/LibTmux/README.md` ("Where a bare connect lands"), one of the
nine documents `ReadmeExampleTests` compiles and runs. Go's is
`tmux/server_options.go`'s doc comments. Rust's fallback is
`crates/libtmux/examples/find.rs`, run via `cargo run --example find`. C++'s
four constructors are the README's own description of `Server`, at the top
of "What is libtmux?". Swift's is `README.md`'s top-level quickstart,
matched against `Examples/Sources/QuickStart/main.swift` by
`Scripts/check_examples.py`. Java's is `README.md`, run by
[`docs-tests`](../testing-with-libtmux/#java-docs-tests).

## Finding a session instead of always creating one

A script that runs more than once usually wants "attach if a session by
this name already exists, create it otherwise," not a fresh session every
time.

Sources: Go uses `examples/filter-query/main.go`, region `docs:query-in-tmux`.
Java uses `examples/.../BuildAWorkspace.java`, run by the examples module's
tests. For exactly-one lookup semantics, see [Filtering and querying, in
practice](../querying-and-filtering/). Swift uses
`Examples/Sources/ExampleCode/Querying.swift`, checked against the README by
`Scripts/check_examples.py` and exercised by
`Examples/Tests/ExampleTests/ModeTests.swift`.

.NET exposes `Server.HasSessionAsync(name)` in
`src/LibTmux/Server.Lifecycle.cs`. Its `CreateSessionAsync` supports
`ReplaceExisting`, which kills and recreates the session. Rust and C++ provide
query APIs for session lookup. See [Filtering and querying, in
practice](../querying-and-filtering/) and the port references for the call
signatures; this page has no tested excerpt for those combinations.

## Where to go next

- [Sending keys](../sending-keys/) and [Capturing output](../capturing-output/)
  pick up once you have a pane handle.
- [Attach and send keys](/examples/attach-and-send-keys/) has the full,
  sourced code for the round trip this guide assumes.
- [Testing with libtmux](../testing-with-libtmux/) if the server you want to
  attach to is one your own test suite should own and tear down.