### One-Liner Examples

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/quick-reference.md

Common one-liner commands for interacting with ZMX sessions, including creating, running commands, monitoring, and managing sessions.

```bash
# Create and attach
zmx attach mydev

```

```bash
# Run command and get exit code
zmx run dev ls && echo "Success" || echo "Failed"

```

```bash
# Run detached, wait, print result
zmx run ci -d npm test && zmx wait ci && echo "Tests passed"

```

```bash
# Monitor session live
watch -n 0.5 'zmx history dev | tail -30'

```

```bash
# Export history to HTML
zmx history dev --html > session.html

```

```bash
# Kill all sessions matching pattern
zmx list --short | xargs -I{} zmx kill {}

```

```bash
# Run command with output capture
zmx history $(zmx run build -d make) | tee build.log

```

```bash
# Check if session is responding
zmx list | grep "session_name=dev" || echo "Session down"

```

```bash
# SSH to remote session
ssh -o RemoteCommand='zmx attach work' user@server

```

```bash
# Prefix all sessions for isolation
export ZMX_SESSION_PREFIX="$(whoami)@$(hostname)."
zmx attach dev

```

--------------------------------

### Tail command example

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/api-reference/cli-commands.md

Connects to all matching sessions and streams their output, updating as new data arrives. Useful for monitoring long-running tasks started with -d.

```bash
zmx tail 'build.*'
```

--------------------------------

### getSocketPath Usage Example

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/api-reference/socket-utils.md

Example of how to use the getSocketPath function.

```zig
const path = try socket.getSocketPath(alloc, "/run/user/1000/zmx", "dev");
defer alloc.free(path);
// path = "/run/user/1000/zmx/dev"
```

--------------------------------

### Logging Usage Example

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/api-reference/socket-utils.md

Examples of using ZMX's custom logging system.

```zig
std.log.info("message", .{});
std.log.warn("warning", .{});
std.log.err("error", .{});
std.log.debug("debug info", .{});
```

--------------------------------

### ZMX_DIR_MODE Examples

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/configuration.md

Examples of setting the ZMX_DIR_MODE environment variable for directory permissions.

```bash
# Default: user and group can access
export ZMX_DIR_MODE=0750

# Allow group access for shared sessions
export ZMX_DIR_MODE=0770

# Minimal: user only
export ZMX_DIR_MODE=0700

# Public access (not recommended)
export ZMX_DIR_MODE=0777
```

--------------------------------

### ForkPtyFailed Example

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/errors.md

Example of a ForkPtyFailed error when spawning a session.

```bash
zmx attach dev
# error: ForkPtyFailed
```

--------------------------------

### OutOfMemory Example

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/errors.md

Example of an OutOfMemory error during zmx run.

```bash
zmx run dev ... 
# error: OutOfMemory
```

--------------------------------

### findTaskExitMarker() Example

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/api-reference/socket-utils.md

Illustrative example of the ZMX_TASK_COMPLETED marker format.

```text
$ ls
file.txt
$ echo ZMX_TASK_COMPLETED:0
ZMX_TASK_COMPLETED:0
```

--------------------------------

### Print Command Examples

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/api-reference/cli-commands.md

Examples illustrating how to inject text directly into a ZMX session's display and scrollback.

```bash
# Inject a status message
zmx print dev "Status: Running build"

# Inject with newlines
printf '\r\n[INFO] Starting process\r\n' | zmx print dev
```

--------------------------------

### ZMX_SESSION_PREFIX Example

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/configuration.md

Example demonstrating how ZMX_SESSION_PREFIX affects session naming.

```bash
export ZMX_SESSION_PREFIX="myproject."
zmx attach dev      # Actually creates "myproject.dev"
zmx attach test     # Actually creates "myproject.test"
zmx kill dev        # Kills "myproject.dev"
```

--------------------------------

### Example Resolution

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/configuration.md

Examples of how zmx resolves the socket directory location based on environment variables.

```bash
export XDG_RUNTIME_DIR=/run/user/1000
# zmx resolves socket_dir to: /run/user/1000/zmx
```

```bash
export TMPDIR=/var/tmp
# zmx resolves socket_dir to: /var/tmp/zmx-1000 (if UID is 1000)
```

```bash
export ZMX_DIR=/custom/zmx/path
# zmx uses: /custom/zmx/path
```

--------------------------------

### Version command example output

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/api-reference/cli-commands.md

Displays zmx version and dependency information.

```text
zmx             0.6.0
ghostty_vt      0.19.4
socket_dir      /run/user/1000/zmx
log_dir         /run/user/1000/zmx/logs
```

--------------------------------

### SessionNotFound Example

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/errors.md

Example of an error when operating on a non-existent session.

```bash
zmx history nosuchsession
# error: session "nosuchsession" does not exist
```

--------------------------------

### Run Command Examples

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/api-reference/cli-commands.md

Examples showing how to send a command to a ZMX session without attaching, including background execution and reading from stdin.

```bash
# Run build command and wait for output
zmx run dev zig build

# Run command in background, return immediately
zmx run dev -d npm test

# Run command from stdin
echo "ls -la" | zmx run dev

# Run with arguments containing special characters
zmx run dev grep -r "TODO.*pattern" src/
```

--------------------------------

### ZMX_LOG_MODE Examples

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/configuration.md

Examples of setting the ZMX_LOG_MODE environment variable for log file permissions.

```bash
# Default: user and group can read
export ZMX_LOG_MODE=0640

# Allow group write access
export ZMX_LOG_MODE=0660

# User only
export ZMX_LOG_MODE=0600
```

--------------------------------

### Attach Command Examples

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/api-reference/cli-commands.md

Examples demonstrating how to attach to a ZMX session, either for an interactive shell or to run a specific command.

```bash
# Attach to session 'dev' and spawn a login shell
zmx attach dev

# Attach to session 'build' and run vim
zmx attach dev vim

# Attach to session 'test' and run multiple commands
zmx attach test bash -c 'cd src && make'
```

--------------------------------

### getSeshName() Examples

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/api-reference/socket-utils.md

Examples demonstrating the usage of getSeshName() with and without a prefix.

```zig
const name = try socket.getSeshName(alloc, "dev");  // "dev"

// With prefix set:
// name = "project.dev" (if ZMX_SESSION_PREFIX="project.")
```

--------------------------------

### TextRequired Example

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/errors.md

Examples of zmx send or print with no text and no stdin.

```bash
zmx send dev              # No text, no stdin
zmx send dev "text"       # OK
echo "text" | zmx send dev  # OK
```

```bash
zmx send dev "your text"
printf 'echo hello\r' | zmx send dev
```

--------------------------------

### Task Mode Usage Examples

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/configuration.md

Demonstrates how to use `zmx run` and `zmx wait` for background tasks and how to view task history.

```bash
zmx run dev sleep 10      # Blocks until command completes
zmx run dev -d sleep 100  # Returns immediately, task runs in background
zmx wait dev              # Wait for background task
zmx history dev | tail -20  # See what happened
```

--------------------------------

### Building From Source

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/README.md

Instructions for building the ZMX project from source using Zig, specifying optimization level and installation prefix.

```bash
# Requires: Zig v0.15
zig build -Doptimize=ReleaseSafe --prefix ~/.local
```

--------------------------------

### Session prefix example

Source: https://github.com/neurosnap/zmx/blob/main/README.md

Demonstrates how to use ZMX_SESSION_PREFIX to prefix session names.

```bash
export ZMX_SESSION_PREFIX="d."
zmx a runner # ZMX_SESSION=d.runner
zmx a tests  # ZMX_SESSION=d.tests
zmx k tests  # kills d.tests
zmx wait     # suspends until all tasks prefixed with "d." are complete
```

--------------------------------

### forkpty() Usage Example

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/api-reference/socket-utils.md

Example of using forkpty to create a child process with a PTY.

```zig
var master_fd: c_int = undefined;
const pid = cross.forkpty(&master_fd, null, null, &ws);
if (pid < 0) return error.ForkPtyFailed;
if (pid == 0) {
    // Child: exec shell
    execChild();
    unreachable;
}
// Parent: pid contains child PID
```

--------------------------------

### SessionUnresponsive Example

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/errors.md

Example of a timeout error when the daemon does not respond.

```bash
zmx history dev
# Timeout waiting for history response
```

--------------------------------

### shellQuote() Example

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/api-reference/socket-utils.md

Example of shellQuote to safely quote a string for shell execution.

```zig
const arg = "it's here";
const quoted = try util.shellQuote(alloc, arg);
// Result: 'it'"'"'s here'
defere alloc.free(quoted);
```

--------------------------------

### Utilities CLI Commands

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/quick-reference.md

Commands for showing help, version, and shell completions.

```bash
# Show help
zmx help
zmx -h

# Show version
zmx version
zmx -v

# Shell completions
eval "$(zmx completions bash)"
eval "$(zmx completions zsh)"
zmx completions fish | source
```

--------------------------------

### Send Command Examples

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/api-reference/cli-commands.md

Examples for sending raw text to a ZMX session's PTY input, including sending commands with newlines and special characters.

```bash
# Send command with automatic newline appending
printf 'echo hello\r' | zmx send dev

# Send Ctrl+C to interactive program
zmx send dev $(printf '\x03')

# Send multiple lines
printf 'ls\recho done\r' | zmx send dev

# Send text with multiple arguments
zmx send dev 'some' 'text'
```

--------------------------------

### NameTooLong Example

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/errors.md

Example demonstrating a session name that exceeds the Unix domain socket path limit.

```bash
export ZMX_DIR=/var/very/long/path/to/socket/directory
zmx attach "very_long_session_name_that_exceeds_limits"
# Error: NameTooLong
```

```text
error: session name is too long (64 bytes, max 50 for socket directory "/var/run")
```

--------------------------------

### get_session_entries() Example

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/api-reference/socket-utils.md

Example usage of get_session_entries to retrieve and print session information.

```zig
var sessions = try util.get_session_entries(alloc, "/run/user/1000/zmx");
defere {
    for (sessions.items) |entry| entry.deinit(alloc);
    sessions.deinit(alloc);
}

for (sessions.items) |session| {
    std.debug.print("name={s} pid={?d}\n", .{session.name, session.pid});
}
```

--------------------------------

### fish/config.fish

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/quick-reference.md

Adds zmx session name to the prompt and enables fish completions.

```fish
# Add zmx session name to prompt
if set -q ZMX_SESSION
  function fish_prompt
    echo -n "[$ZMX_SESSION] "
    # (rest of prompt)
  end
end

# Enable completions
if type -q zmx
  zmx completions fish | source
end
```

--------------------------------

### InvalidCommand Example

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/errors.md

Example of an InvalidCommand error due to incorrect subcommand usage.

```bash
zmx invalid_subcommand
```

--------------------------------

### Install zmx via Homebrew

Source: https://github.com/neurosnap/zmx/blob/main/README.md

This command installs the zmx package using the Homebrew package manager.

```bash
brew install neurosnap/tap/zmx
```

--------------------------------

### Completions command examples

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/api-reference/cli-commands.md

Outputs shell completion script for bash, zsh, or fish.

```bash
# Enable completions for bash
eval "$(zmx completions bash)"

# Enable completions for zsh
eval "$(zmx completions zsh)"

# Enable completions for fish (note: different usage)
zmx completions fish | source
```

--------------------------------

### SessionsDisappeared Example

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/errors.md

Example of a SessionsDisappeared error when a session crashes during zmx wait.

```bash
zmx run dev -d "sleep 100"
zmx wait dev
# [Later, daemon crashes]
# error: 1 session(s) disappeared before completing
```

--------------------------------

### Permissions Configuration

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/quick-reference.md

Environment variables for setting directory and log file permissions.

```bash
# Allow group access (shared sessions)
export ZMX_DIR_MODE=0770
export ZMX_LOG_MODE=0660

# For system-wide or shared service
export ZMX_DIR=/var/run/zmx
export ZMX_DIR_MODE=0770
```

--------------------------------

### Timeout Example

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/errors.md

Example of how zmx list probes sessions and marks unreachable ones due to timeout.

```bash
zmx list     # Probes each session, marks unreachable if timeout
```

--------------------------------

### Project-Based Namespacing Configuration

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/configuration.md

Example of scoping sessions to a specific project using `ZMX_SESSION_PREFIX`.

```bash
export ZMX_SESSION_PREFIX="myproject."

# Now all sessions are scoped:
zmx attach build    # Session is "myproject.build"
zmx attach test     # Session is "myproject.test"
zmx list            # Shows all "myproject.*" and other projects' sessions
```

--------------------------------

### Utility Module

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/quick-reference.md

Zig API utility functions for zmx.

```zig
// Get all active sessions
var sessions = try util.get_session_entries(alloc, socket_dir);
defer {
    for (sessions.items) |entry| entry.deinit(alloc);
    sessions.deinit(alloc);
}

// Check if string needs quoting
if (util.shellNeedsQuoting(arg)) {
    const quoted = try util.shellQuote(alloc, arg);
    defer alloc.free(quoted);
}

// Detect user input
if (util.isUserInput(payload)) {
    // Real user input, not mouse/focus event
}

// Detect Ctrl+\
if (util.isCtrlBackslash(buf)) {
    // User pressed detach key
}

// Find task exit code
if (util.findTaskExitMarker(output)) |code| {
    // Task completed with code
}
```

--------------------------------

### FilePathRequired Example

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/errors.md

Example of calling zmx write without a file path.

```bash
zmx write dev              # Missing file path
zmx write dev /path/to/file < data.txt  # OK
```

```bash
zmx write <session> <file_path> < input
```

--------------------------------

### InvalidSessionName Example

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/errors.md

Examples demonstrating valid and invalid session names with InvalidSessionName errors.

```bash
zmx attach "session/name"     # Error: InvalidSessionName
zmx attach "session.name"     # OK (dots are allowed)
zmx run "../etc/passwd"       # Error: InvalidSessionName
```

```bash
zmx attach my-session
zmx attach my_session
zmx attach my.project.dev
```

--------------------------------

### maxSessionNameLen Calculation Example

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/api-reference/socket-utils.md

Example of calculating the maximum session name length using maxSessionNameLen.

```zig
const max = socket.maxSessionNameLen("/run/user/1000/zmx");
// max = 107 - 18 - 1 = 88 bytes max for session name
```

--------------------------------

### Run Command Example Payload

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/api-reference/ipc-protocol.md

Example payload for the Run message, representing a null-terminated command string.

```text
"ls -la /tmp\r"
```

--------------------------------

### ZMX_SESSION Usage

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/configuration.md

Examples of how to use the ZMX_SESSION environment variable within a zmx session.

```bash
# Inside a zmx session, check which session you're in
echo $ZMX_SESSION

# Use in shell prompt
if [[ -n $ZMX_SESSION ]]; then
  export PS1="[$ZMX_SESSION] ${PS1}"
fi
```

--------------------------------

### HistoryFormat Usage Example

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/api-reference/socket-utils.md

Example of using the HistoryFormat enum to send a history format byte.

```zig
const format = util.HistoryFormat.vt;
const format_byte = @intFromEnum(format);
iipc.send(fd, .History, &[_]u8{format_byte});
```

--------------------------------

### NoMatchingSessions Example

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/errors.md

Example of a NoMatchingSessions error when zmx wait is called with non-existent session names.

```bash
zmx wait nonexistent
# error: no matching sessions found
```

--------------------------------

### Session Management CLI Commands

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/quick-reference.md

Commands for creating, attaching, running, listing, and killing zmx sessions.

```bash
# Create/attach session
zmx attach <name>
zmx attach <name> <command>

# Run command without attaching
zmx run <name> <command>
zmx run <name> -d <command>      # Detached (background)

# List sessions
zmx list
zmx list --short

# Kill session
zmx kill <name>
zmx kill <name> --force
zmx kill <name> --fish           # For fish shell

# Detach current session
zmx detach
# OR: Press Ctrl+\
```

--------------------------------

### History command examples

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/api-reference/cli-commands.md

Outputs the scrollback history of a session in different formats.

```bash
# Get last 100 lines of history
zmx history dev | tail -100

# Save history with colors for viewing
zmx history dev --vt > dev.log

# Export as HTML
zmx history dev --html > dev.html

# Monitor history while session runs
watch -n 1 'zmx history dev | tail -20'
```

--------------------------------

### InvalidPayload Example

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/errors.md

Example illustrating an InvalidPayload error due to a resize message with incorrect byte count.

```bash
Resize message with wrong byte count (not 4 bytes).
```

--------------------------------

### Custom Temporary Directory Configuration

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/configuration.md

Example of setting a custom temporary directory for zmx when the default is insufficient.

```bash
# When /tmp is too small or slow
export TMPDIR=/var/tmp
export ZMX_DIR_MODE=0750
# zmx will use /var/tmp/zmx-{uid}
```

--------------------------------

### zsh/.zshrc

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/quick-reference.md

Adds zmx session name to the prompt and enables zsh completions.

```zsh
# Add zmx session name to prompt
if [[ -n $ZMX_SESSION ]]; then
  export PS1="[$ZMX_SESSION] ${PS1}"
fi

# Enable completions
if command -v zmx &> /dev/null;
  eval "$(zmx completions zsh)"
fi
```

--------------------------------

### Socket Directory Configuration

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/quick-reference.md

Environment variables for configuring the zmx socket directory.

```bash
# Use custom directory
export ZMX_DIR=/custom/zmx

# Use XDG_RUNTIME_DIR (recommended on Linux)
export XDG_RUNTIME_DIR=/run/user/1000
# zmx uses: /run/user/1000/zmx

# Use temporary directory
export TMPDIR=/var/tmp
# zmx uses: /var/tmp/zmx-{uid}

# Check what zmx uses
zmx version | grep socket_dir
```

--------------------------------

### printSessionNameTooLong Output Example 2

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/api-reference/socket-utils.md

Example error output from printSessionNameTooLong when the socket directory path itself is too long.

```text
error: socket directory path is too long ("/very/long/path/ப்புகளை")
```

--------------------------------

### CommandRequired Example

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/errors.md

Demonstrates the trigger and resolution for the CommandRequired error.

```bash
zmx run dev              # No command, no stdin
zmx run dev ls           # OK
echo "ls" | zmx run dev  # OK
```

```bash
zmx run <session> <command> [args...]
zmx run <session> < commands.txt
```

--------------------------------

### bash/.bashrc

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/quick-reference.md

Adds zmx session name to the prompt and enables bash completions.

```bash
# Add zmx session name to prompt
if [[ -n $ZMX_SESSION ]]; then
  export PS1="[$ZMX_SESSION] ${PS1}"
fi

# Enable completions
if command -v zmx &> /dev/null;
  eval "$(zmx completions bash)"
fi
```

--------------------------------

### Debugging CLI Commands

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/quick-reference.md

Commands for viewing logs, listing sockets, and checking session info for debugging.

```bash
# View logs
tail -f /run/user/1000/zmx/logs/dev.log
tail -f /run/user/1000/zmx/logs/zmx.log

# List all sockets
ls -la /run/user/1000/zmx/

# Check session info
zmx list
```

--------------------------------

### Non-Blocking I/O with Poll

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/architecture.md

Example of using poll() for non-blocking I/O in Zig.

```Zig
var poll_fds: []posix.pollfd = ...;  // Array of fd, events, revents
const n = try posix.poll(poll_fds, -1);  // Block until event
// Check poll_fds[i].revents for what happened
```

--------------------------------

### Info Request Usage

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/api-reference/ipc-protocol.md

Zig code example for requesting session information from the daemon.

```zig
ipc.send(fd, .Info, "");  // Request
```

--------------------------------

### IPC Module

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/quick-reference.md

Zig API functions for Inter-Process Communication with zmx sessions.

```zig
// Send message
try ipc.send(fd, .Input, data);
try ipc.send(fd, .History, "");

// Append message to buffer
try ipc.appendMessage(alloc, &write_buf, .Output, data);

// Get terminal size
const size = ipc.getTerminalSize(fd);  // returns Resize

// Create socket buffer
var sb = try ipc.SocketBuffer.init(alloc);
defer sb.deinit();

// Read from socket
const n = try sb.read(fd);

// Extract messages
while (sb.next()) |msg| {
    // msg.header.tag, msg.payload
}

// Probe session (with timeout)
const result = try ipc.probeSession(alloc, socket_path);
posix.close(result.fd);
// result.info contains Info struct
```

--------------------------------

### Interaction CLI Commands

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/quick-reference.md

Commands for sending input, printing text, and writing files through a zmx session.

```bash
# Send input (fire-and-forget)
zmx send <name> <text>
echo "command" | zmx send <name>

# Inject text (no shell execution)
zmx print <name> <text>

# Write file through session
echo "content" | zmx write <name> /path/to/file
cat large-file | zmx write <name> /tmp/output
```

--------------------------------

### Socket Module

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/quick-reference.md

Zig API functions for interacting with zmx sessions at the socket level.

```zig
// Get current session name
const sesh = socket.getSeshNameFromEnv();

// Get full session name with prefix
const name = try socket.getSeshName(alloc, "dev");
deffer alloc.free(name);

// Connect to session
const fd = try socket.sessionConnect(socket_path);
defer posix.close(fd);

// Check if session exists
const exists = try socket.sessionExists(dir, "dev");

// Create listening socket
const fd = try socket.createSocket(path);

// Get full socket path
const path = try socket.getSocketPath(alloc, socket_dir, "dev");
defer alloc.free(path);

// Max session name length
const max = socket.maxSessionNameLen(socket_dir);
```

--------------------------------

### Autossh Example

Source: https://github.com/neurosnap/zmx/blob/main/README.md

Using autossh to ensure SSH connections automatically reconnect.

```bash
autossh -M 0 -q d.term
```

--------------------------------

### File Paths

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/quick-reference.md

Structure of the socket directory and its contents, including session sockets and log files.

```bash
{socket_dir}/                      Socket directory
├── <name>                         Session socket (Unix domain)
└── logs/
    ├── zmx.log                    Global CLI log
    └── <name>.log                 Per-session daemon log

```

--------------------------------

### NoHistoryResponse Example

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/errors.md

Example of a NoHistoryResponse error when requesting history.

```bash
zmx history dev
# error: NoHistoryResponse
```

--------------------------------

### Use Over SSH

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/README.md

Provides an example of configuring SSH to directly attach to remote ZMX sessions by using a 'RemoteCommand'.

```bash
# Create SSH config entry
# Host d.*
#     HostName 192.168.1.100
#     RemoteCommand zmx attach %k
#     RequestTTY yes

# Now connect to remote sessions
ssh d.dev      # Attaches to "dev" session on remote
ssh d.test     # Attaches to "test" session on remote
```

--------------------------------

### Build zmx from source

Source: https://github.com/neurosnap/zmx/blob/main/README.md

Instructions for building zmx from source, requiring Zig v0.15. Ensure ~/.local/bin is in your PATH.

```bash
zig build -Doptimize=ReleaseSafe --prefix ~/.local
```

--------------------------------

### NoAckReceived Example

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/errors.md

Example of a NoAckReceived error during a write operation.

```bash
echo "content" | zmx write dev /tmp/file.txt
# error: NoAckReceived
```

--------------------------------

### Monitoring CLI Commands

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/quick-reference.md

Commands for viewing history, following output, waiting for tasks, and checking session status.

```bash
# View history
zmx history <name>
zmx history <name> --vt          # With colors
zmx history <name> --html        # HTML format

# Follow output
zmx tail <name>
zmx tail <name> <name2>          # Multiple sessions

# Wait for task completion
zmx wait <name>
zmx wait <name> <name2> <name3>  # Multiple

# Check status
zmx list | grep <name>
```

--------------------------------

### Session Naming Configuration

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/quick-reference.md

Environment variable for adding a prefix to all zmx session names.

```bash
# Add prefix to all sessions
export ZMX_SESSION_PREFIX="myproject."
zmx attach dev              # Creates "myproject.dev"
zmx kill dev                # Kills "myproject.dev"

# Remove prefix if needed
unset ZMX_SESSION_PREFIX
```

--------------------------------

### SSH Config Entry

Source: https://github.com/neurosnap/zmx/blob/main/README.md

An example SSH configuration entry for a remote dev server using zmx.

```bash
Host = d.*
    HostName 192.168.1.xxx

    RemoteCommand zmx attach %k
    RequestTTY yes
    ControlPath ~/.ssh/cm-%r@%h:%p
    ControlMaster auto
    ControlPersist 10m
```

--------------------------------

### sessionConnect() Usage

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/api-reference/socket-utils.md

Example usage of sessionConnect() to establish a Unix domain socket connection to a session.

```zig
const socket_path = try socket.getSocketPath(alloc, socket_dir, session_name);
defer alloc.free(socket_path);

const fd = try socket.sessionConnect(socket_path);
defere posix.close(fd);
// Use fd for ipc communication
```

--------------------------------

### SessionNameRequired Example

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/errors.md

Examples of commands that trigger SessionNameRequired and their resolutions.

```bash
zmx run         # Error: SessionNameRequired
zmx send        # Error: SessionNameRequired
zmx attach      # Actually defaults to list, not an error
```

```bash
zmx run dev "command here"
zmx send dev "text to send"
```

--------------------------------

### getSeshPrefix() Usage

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/api-reference/socket-utils.md

Example usage of the getSeshPrefix() function to retrieve the session name prefix from the environment.

```zig
const prefix = socket.getSeshPrefix();
if (prefix.len > 0) {
    std.debug.print("prefix: {s}\\n", .{prefix});
}
```

--------------------------------

### Create and Use a Session

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/README.md

Demonstrates how to create a new session named 'dev', attach to it interactively, perform some basic commands, and then detach.

```bash
# Create session and attach
zmx attach dev

# Inside session, work normally
$ ls -la
$ cd project
$ make build

# Detach (close terminal or press Ctrl+\)
```

--------------------------------

### ConnectionRefused Example Error

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/errors.md

Example of the error message when a connection is refused.

```text
error: session unresponsive: ConnectionRefused
session <name> is unresponsive (ConnectionRefused)
daemon may be busy: try again, add `--force` flag, or kill the process directly
```

--------------------------------

### Troubleshooting Permission Denied

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/configuration.md

Steps to troubleshoot 'Permission denied' errors, focusing on socket directory permissions.

```bash
# Check socket directory permissions
ls -ld /run/user/1000/zmx

# Verify dir_mode matches group access needs
echo $ZMX_DIR_MODE    # Should be 0770 for group access
```

--------------------------------

### Example Write Payload

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/api-reference/ipc-protocol.md

An example of the Write message payload in hexadecimal format.

```text
00 00 00 0B        (path_len = 11 in little-endian)
2F 74 6D 70 2F 66  (/tmp/file - path)
69 6C 65 2E 74 78 74
... (file content bytes)
```

--------------------------------

### BrokenPipe / ConnectionResetByPeer Example

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/errors.md

Example of a BrokenPipe error when the daemon crashes during a send operation.

```bash
zmx send dev "text"     # Daemon crashes
# error: BrokenPipe
```

--------------------------------

### Run Command in Background

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/README.md

Shows how to run a command ('make test') in a detached background session, check its status, and wait for its completion.

```bash
# Start long-running task detached
zmx run build -d make test

# Check status
zmx list | grep build

# Wait for completion
zmx wait build

# Or monitor output
zmx tail build
```

--------------------------------

### printSessionNameTooLong Output Example 1

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/api-reference/socket-utils.md

Example error output from printSessionNameTooLong when the session name is too long.

```text
error: session name is too long (64 bytes, max 50 for socket directory "/run/user/1000/zmx")
```

--------------------------------

### usage

Source: https://github.com/neurosnap/zmx/blob/main/README.md

Command-line interface for zmx.

```bash
zmx - session persistence for terminal processes

Usage: zmx <command> [args...]

Commands:
  [a]ttach <name> [command...]             Attach to session, creating if needed
  [r]un <name> [-d] [command...]           Send command without attaching
  [s]end <name> <text...>                  Send raw input to session PTY
  [p]rint <name> <text...>                 Inject text into session display
  [wr]ite <name> <file_path>               Write stdin to file_path through the session
  [d]etach                                 Detach all clients (ctrl+\ for current client)
  [l]ist|ls [--short]                      List active sessions
  [k]ill <name>... [--force]               Kill session and all attached clients
  [hi]story <name> [--vt|--html]           Output session scrollback
  [w]ait <name>...                         Wait for session tasks to complete
  [t]ail <name>...                         Follow session output
  [c]ompletions <shell>                    Shell completions (bash, zsh, fish)
  [v]ersion                                Show version
  [h]elp                                   Show this help

Attach:
  This will spawn a login $SHELL with a PTY.  You can provide a
  command instead of creating a shell.

  Examples:
    zmx attach dev
    zmx attach dev vim

History:
  This should generally be used with `tail` to print the last lines
  of the session's scrollback history.

  Examples:
    zmx history <session> | tail -100

Run:
  Commands are passed as-is: do not wrap in quotes.
  Commands run sequentially: do not send multiple in parallel.
  Avoid interactive programs (pagers, editors, prompts): they hang.

  `--fish` is required when the session runs fish shell.

  If the command hangs, send Ctrl+C to recover:
    zmx run <session> $(printf '\x03')

  If the command hangs, print the history to see the error:
    zmx history <session> | tail -100

  `-d` will detach from the calling terminal. Use `wait` to track
  its status.

  Examples:
    zmx run dev ls
    zmx run dev --fish ls src
    zmx run dev zig build
    zmx run dev grep -r TODO src
    zmx run dev git -c core.pager=cat diff

Send:
  Sends raw text to the session's PTY input (fire-and-forget).
  Unlike `run`, no completion marker is appended and no exit code
  is tracked.  Useful for TUI applications, interactive prompts,
  or any program that reads stdin directly.

  Text is sent byte-for-byte with no automatic carriage return.
  Append \r yourself when you want the shell to execute a command.

  Text can also be piped via stdin:
    printf 'ls -la\r' | zmx send dev

  Examples:
    printf 'echo hello\r' | zmx send dev
    zmx send dev $(printf '\x03')
    zmx send dev /compact

Print:
  Injects text directly into the session display and scrollback.
  Never touches the PTY input -- the shell sees nothing.
  Caller is responsible for newlines (\r\n).

  Examples:
    printf '\r\nhello\r\n' | zmx print dev
    zmx print dev "$(printf '\r\nalert\r\n')"

Write:
  Writes stdin to file_path inside the session. Works over SSH.
  file_path can be absolute or relative to the session shell's cwd.
  Requires base64 and printf in the remote environment.
  Large files are chunked automatically (~48KB per chunk).
  File path must not contain single quotes.

  Examples:
    echo "hello" | zmx write dev /tmp/hello.txt
    cat main.zig | zmx write dev src/main.zig

Wait:
  Used with a detached run task to track its status.  Multiple
  sessions can be provided.

  Examples:
    zmx run -d dev sleep 10
    zmx wait dev
    zmx wait dev other

Environment variables:
  SHELL                Default shell for new sessions
  ZMX_DIR              Socket directory (priority 1)
  XDG_RUNTIME_DIR      Socket directory (priority 2)
  TMPDIR               Socket directory (priority 3)
  ZMX_SESSION          Session name (injected automatically)
  ZMX_SESSION_PREFIX   Prefix added to all session names
  ZMX_DIR_MODE         Sets mode for socket and log directories (octal, defaults to 0750)
  ZMX_LOG_MODE         Sets mode for log files (octal, defaults to 0640)

```

--------------------------------

### Verify prefix setting

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/configuration.md

If using a prefix, verify it is set correctly.

```bash
echo $ZMX_SESSION_PREFIX
```

--------------------------------

### Adding New IPC Message Type - Example

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/architecture.md

Example of adding a new 'Status' message type to the IPC protocol.

```zig
// ipc.zig
pub const Tag = enum(u8) {
    // ... existing tags ...
    Status = 14,  // new
};

// main.zig daemon loop
.Status => try daemon.handleStatus(client, msg.payload),

// main.zig define handler
fn handleStatus(self: *Daemon, client: *Client, payload: []const u8) !void {
    // ... implementation ...
}
```

--------------------------------

### Session Naming with Prefix

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/api-reference/cli-commands.md

Demonstrates how to use the ZMX_SESSION_PREFIX environment variable to prefix session names.

```bash
export ZMX_SESSION_PREFIX="project."
zmx attach dev    # Creates "project.dev" session
zmx kill dev      # Kills "project.dev" session
```

--------------------------------

### Header Struct

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/types.md

Message header sent at the start of every IPC message.

```zig
pub const Header = packed struct {
    tag: Tag,
    len: u32,
}
```

--------------------------------

### Development Machine Configuration Verification

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/configuration.md

Shows how to verify the socket directory used by zmx, typically when XDG_RUNTIME_DIR is set.

```bash
# Uses XDG_RUNTIME_DIR if available (typical Linux desktop)
# No configuration needed if XDG_RUNTIME_DIR is set

# Verify what zmx uses:
zmx version | grep socket_dir
```

--------------------------------

### Check available commands

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/errors.md

How to check available commands for ZMX.

```bash
zmx help
zmx --help
```

--------------------------------

### List all active sessions

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/api-reference/cli-commands.md

Lists all active sessions with metadata.

```bash
# List all active sessions
zmx list

# List with short format
zmx ls --short

# Parse for specific session
zmx list | grep "dev"
```

--------------------------------

### File Write Behavior Execution

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/configuration.md

Illustrates how files are written through a session using zmx, including base64 encoding and chunking.

```bash
printf '<base64>' | base64 -d > <file>      # First chunk
printf '<base64>' | base64 -d >> <file>     # Subsequent chunks
```

--------------------------------

### Follow real-time log

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/errors.md

Follow the real-time log of a session.

```bash
tail -f /run/user/1000/zmx/logs/dev.log
```

--------------------------------

### Sessions in Different Directories - Solution

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/configuration.md

Provides solutions to ensure consistent session management by either setting ZMX_DIR consistently or using ZMX_SESSION_PREFIX for organization.

```bash
# Set ZMX_DIR consistently
export ZMX_DIR=/tmp/zmx
zmx list              # Now consistent

# Or use ZMX_SESSION_PREFIX to organize
export ZMX_SESSION_PREFIX="host1."
```

--------------------------------

### Basic Attach and Type Flow

Source: https://github.com/neurosnap/zmx/blob/main/_autodocs/architecture.md

Illustrates the sequence of events and process interactions when a user attaches to a session and types commands.

```text
User Terminal          Client Process      Daemon Process
──────────────────────────────────────────────────────
$ zmx attach dev       
    │
    ├─ fork()
    │
    Parent returns to shell
    
    Child process:
    ├─ connectSession()
    │  └─ Creates Unix socket connection
    │
    ├─ clientLoop()
    │  └─ Sends Init message with terminal size
    │
    └─ poll() on stdin, socket, signal_pipe
       │
       User types 'ls'
       │
       stdin event → read stdin
       │
       package as Input message
       │
       queue in sock_write_buf
       │
       POLLOUT on socket
       │
       write sock_write_buf to socket
                                              │
                                              Receives Input message
                                              │
                                              queue in pty_write_buf
                                              │
                                              POLLOUT on PTY
                                              │
                                              write "ls" to PTY
                                              │
                                              shell executes: ls
                                              │
                                              PTY output: "file1\nfile2\n$ "
                                              │
                                              read from PTY
                                              │
                                              feed to ghostty-vt
                                              │
                                              package as Output message
                                              │
                                              append to client write_buf
                                              │
       ← ← ← ← ← ← ← ← ← ← ← ← ← ← ← ← ← ←
       
       Receives Output message
       │
       package for stdout_buf
       │
       POLLOUT on stdout
       │
       write to stdout
       │
User sees: file1
           file2
           $

```