# server.Server.newSession

- **Module:** server
- **Package:** libtmux
- **Language:** TypeScript
- **Kind:** method
- **Source:** https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/libtmux/src/server.ts#L1114
- **Page:** https://libtmux.org/en/ts/latest/reference/server-server-newsession/

```
newSession(options?: NewSessionOptions): Promise<Session>
```

Create a detached session and resolve it as a handle.

Save this complete program as `new-`[`session.ts`](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/libtmux/src/session.ts). With Bun 1.4.2 or newer,
tmux 3.2a or newer, and `libtmux` installed, run `bun run new-`[`session.ts`](https://github.com/libtmux/libtmux-ts/blob/46cccfef2a546de55ce8b308249b8c76339089a0/packages/libtmux/src/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

```ts
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

- `options?` (`NewSessionOptions`)

## tmux command

The tmux commands behind `newSession`.

- [`new-session`](/en/tmux/latest/manual/new-session/)

## tmux C API

The C declarations in tmux that implement these commands.

- [`cmd_new_session_entry`](/en/tmux/latest/reference/c-variable-cmd_new_session_entry/) (attribute)
- [`cmd_new_session_exec`](/en/tmux/latest/reference/c-function-cmd-new-session-c-cmd_new_session_exec/) (function)

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. [`cmd_new_session_exec`](/en/tmux/latest/reference/c-function-cmd-new-session-c-cmd_new_session_exec/) (function)
2. calls → [`spawn_window`](/en/tmux/latest/reference/c-function-spawn_window/) (function)
3. calls → [`spawn_pane`](/en/tmux/latest/reference/c-function-spawn_pane/) (function)
4. calls → [`window_add_pane`](/en/tmux/latest/reference/c-function-window_add_pane/) (function)
5. calls → [`window_pane_create`](/en/tmux/latest/reference/c-function-window-c-window_pane_create/) (function)

## Guides

Pages that discuss `newSession`.

- [TypeScript MCP examples](/en/ts/latest/mcp/examples/)
- [TypeScript workspace builder examples](/en/ts/latest/workspace/internals/examples/)

## In other ports

Create a session

| Language | Equivalent |
| --- | --- |
| Python | [`libtmux.Server.new_session`](/en/py/latest/reference/libtmux-server-new_session/) (method) |
| Ruby | [`LibTmux::Server#new_session`](/en/ruby/latest/reference/libtmux-server-new_session/) (method) |
| Lua | [`libtmux.Server:new_session`](/en/lua/latest/reference/libtmux-server-new_session/) (method) |
| Rust | [`server.Server.new_session`](/en/rs/latest/reference/server-server-new_session/) (method) |
| Go | [`tmux.Server.NewSession`](/en/go/latest/reference/tmux-server-newsession/) (method) |
| Java | [`io.github.libtmux.Server.newSession`](/en/java/latest/reference/io-github-libtmux-server-server-newsession/) (method) |
| Kotlin | [`io.github.libtmux.kotlin.Server.newSession`](/en/kotlin/latest/reference/io-github-libtmux-kotlin-server-newsession/) (method) |
| Scala | [`io.github.libtmux.scaladsl.Server.newSession`](/en/scala/latest/reference/io-github-libtmux-scaladsl-server-newsession/) (method) |
| C# | [`LibTmux.Server.CreateSessionAsync`](/en/csharp/latest/reference/libtmux-server-createsessionasync/) (method) |
| C++ | [`libtmux::Server::new_session`](/en/cxx/latest/reference/libtmux-server-new_session/) (method) |
| Swift | [`Server.newSession(named:startDirectory:windowName:width:height:environment:shell:)`](/en/swift/latest/reference/server-newsession(named-startdirectory-windowname-width-height-)/) (method) |

No equivalent is recorded in PowerShell, Julia, Elixir or F#.