Crate focal

Crate focal 

Source
Expand description

Focal - Terminal focus library.

This crate provides cross-platform functionality for focusing terminal windows and switching multiplexer panes. It supports:

  • Terminal detection: Identify which terminal emulator owns a TTY
  • Cross-platform activation: Bring terminal windows to front (macOS + Linux)
  • Terminal-specific handlers: Precise tab/pane focusing for iTerm2, Terminal.app, WezTerm, Kitty
  • Multiplexer support: Switch to the correct tmux/zellij/screen pane

§Focus Modes

The library supports two focus modes:

  • SingleWindow: Uses Accessibility APIs (AXRaise) to bring only the specific window to the front. Requires accessibility permissions on macOS.

  • ActivateApp: Uses traditional app activation which brings ALL windows of the terminal app to the front. No special permissions required.

§Usage

ⓘ
use focal::{focus_session, focus_session_with_mode, FocusResult, FocusMode};

// Focus using default mode (SingleWindow with ActivateApp fallback)
match focus_session(pid, None) {
    FocusResult::Success => println!("Focused!"),
    FocusResult::MuxSwitched { mux, target } => {
        println!("Switched to {mux} {target}");
    }
    FocusResult::NotFound => println!("Terminal not found"),
    _ => {}
}

// Or explicitly choose a mode
focus_session_with_mode(pid, None, FocusMode::ActivateApp);

§Architecture

The focus flow works as follows:

  1. Check if the process is in a terminal multiplexer (tmux, zellij, screen)
  2. If so, switch to the correct pane and get the client TTY
  3. Get the TTY device for the process
  4. Detect which terminal emulator owns the TTY
  5. Try terminal-specific focusing (for precise tab/pane control)
  6. Fall back to generic window activation

Re-exports§

pub use detect::Terminal;
pub use detect::TerminalKind;
pub use mux::Focuser;
pub use mux::Multiplexer;
pub use mux::MuxFocusResult;

Modules§

activate
Cross-platform window activation.
detect
Terminal detection from TTY device.
mux
Terminal multiplexer handlers.
terminals
Terminal-specific focus handlers.
tty
TTY device utilities.
util
Shared utilities for the focal crate.

Enums§

FocusMode
Focus mode for terminal window activation.
FocusResult
Result of attempting to focus a terminal.

Functions§

focus_by_tty
Focus a terminal window by its TTY device.
focus_by_tty_with_mode
Focus a terminal window by TTY with explicit mode control.
focus_session
Focus the terminal window containing the given process.
focus_session_with_mode
Focus the terminal window with explicit mode control.
get_tty_device
Get the TTY device for a process.