Python workspace internal API
tmuxp 1.74.0 · Source
tmuxp’s workspace APIs are internal implementation details with no stability
guarantee. They use libtmux’s Server, Session, Window, and Pane objects
for tmux control. Use the CLI guide to load workspace files.
Load and validateLink to section
tmuxp.workspace.loader.expand normalizes shorthand, variables, and paths.
loader.trickle applies inherited configuration after expansion. Both operate
on workspace dictionaries. validation.validate_schema checks required
structure; it is not a complete machine-readable schema of every runtime
behavior.
Consult the upstream loader API and validation API for parameter and error details.
Build and extendLink to section
tmuxp.workspace.builder.WorkspaceBuilder is the compatibility alias for
ClassicWorkspaceBuilder. Construct it with expanded session_config and a
libtmux server, call build, then read ClassicWorkspaceBuilder.session.
WorkspaceBuilderProtocol defines the interface used by the CLI, including
construction callbacks, building into an optional existing session, and
session discovery. The registry resolves named entry points or import paths.
Use the upstream builder API
and custom builder guide
when implementing an extension.
Export and CLILink to section
tmuxp.workspace.freezer.freeze(session) reads a live session into a
configuration dictionary. freezer.inline compacts that expanded structure
for a file. The freezer API
documents both operations.
The CLI reference covers loading, freezing, listing, searching, editing, importing, and converting workspaces. These are application commands, separate from the language-level workspace builder.
API declarations
Follow a declaration for its signature, members, documentation, and source.
Exports
tmuxp.exc.ActiveSessionMissingWorkspaceException- Active session cannot be found while loading tmuxp workspace.
tmuxp.workspace.builder.available_builders- Return the names of builders registered via entry points.
tmuxp.exc.BeforeLoadScriptError- Shell script execution error.
tmuxp.exc.BeforeLoadScriptNotExists- Raises if shell script could not be found.
tmuxp.workspace.builder.ClassicWorkspaceBuilder- Load workspace from workspace dict object.
tmuxp.cli.cli- Manage tmux sessions.
tmuxp.cli.CLI_DESCRIPTIONtmuxp.cli.debug_info.CLIDebugInfoNamespace- Typed argparse.Namespace for tmuxp debug-info command.
tmuxp.cli.freeze.CLIFreezeNamespace- Typed argparse.Namespace for tmuxp freeze command.
tmuxp.cli.load.CLILoadNamespace- Typed argparse.Namespace for tmuxp load command.
tmuxp.cli.ls.CLILsNamespace- Typed argparse.Namespace for tmuxp ls command.
tmuxp.cli.CLINamespace- Typed argparse.Namespace for tmuxp root-level CLI.
tmuxp.cli.search.CLISearchNamespace- Typed argparse.Namespace for tmuxp search command.
tmuxp.cli.shell.CLIShellNamespace- Typed argparse.Namespace for tmuxp shell command.
tmuxp.workspace.builder.classic.COLUMNS_FALLBACKtmuxp.cli.convert.command_convert- Entrypoint for tmuxp convert convert a tmuxp config between JSON and YAML.
tmuxp.cli.debug_info.command_debug_info- Entrypoint for tmuxp debug-info to print debug info to submit with issues.
tmuxp.cli.edit.command_edit- Entrypoint for tmuxp edit, open tmuxp workspace file in system editor.
tmuxp.cli.freeze.command_freeze- Entrypoint for tmuxp freeze, snapshot a tmux session into a tmuxp workspace.
tmuxp.cli.import_config.command_import- Import a teamocil/tmuxinator config.
tmuxp.cli.import_config.command_import_teamocil- Entrypoint for tmuxp import teamocil subcommand.
tmuxp.cli.import_config.command_import_tmuxinator- Entrypoint for tmuxp import tmuxinator subcommand.
tmuxp.cli.load.command_load- Load a tmux workspace from each WORKSPACE_FILE.
tmuxp.cli.ls.command_ls- Entrypoint for tmuxp ls subcommand.
tmuxp.cli.search.command_search- Entrypoint for tmuxp search subcommand.
tmuxp.cli.shell.command_shell- Entrypoint for tmuxp shell for tmux server, session, window and pane.
tmuxp.cli.search.compile_search_patterns- Compile search tokens into regex patterns.
tmuxp.plugin.Config- tmuxp plugin configuration mapping.
tmuxp.cli.convert.CONVERT_DESCRIPTIONtmuxp.cli.convert.ConvertUnknownFileType- Raise if tmuxp convert encounters an unknown filetype.
tmuxp.cli.convert.create_convert_subparser- Augment argparse.ArgumentParser with convert subcommand.
tmuxp.cli.debug_info.create_debug_info_subparser- Augment argparse.ArgumentParser with debug-info subcommand.
tmuxp.cli.edit.create_edit_subparser- Augment argparse.ArgumentParser with edit subcommand.
tmuxp.cli.freeze.create_freeze_subparser- Augment argparse.ArgumentParser with freeze subcommand.
tmuxp.cli.import_config.create_import_subparser- Augment argparse.ArgumentParser with import subparser.
tmuxp.cli.load.create_load_subparser- Augment argparse.ArgumentParser with load subcommand.
tmuxp.cli.ls.create_ls_subparser- Augment argparse.ArgumentParser with ls subcommand.
tmuxp.cli.create_parser- Create CLI argparse.ArgumentParser for tmuxp.
tmuxp.cli.search.create_search_subparser- Augment argparse.ArgumentParser with search subcommand.
tmuxp.cli.shell.create_shell_subparser- Augment argparse.ArgumentParser with shell subcommand.
tmuxp.cli.debug_info.DEBUG_INFO_DESCRIPTIONtmuxp.log.debug_log_template- Return the prefix for the log message. Template for Formatter.
tmuxp.log.DebugLogFormatter- Provides greater technical details than standard log Formatter.
tmuxp.plugin.DEFAULT_CONFIGtmuxp.cli.search.DEFAULT_FIELDStmuxp.shell.detect_best_shell- Return the best, most feature-rich shell available.
tmuxp.cli.edit.EDIT_DESCRIPTIONtmuxp.exc.EmptyWorkspaceException- Workspace file is empty.
tmuxp.cli.search.evaluate_match- Evaluate if workspace fields match search patterns.
tmuxp.workspace.loader.expand- Resolve workspace variables and expand shorthand style / inline properties.
tmuxp.workspace.loader.expand_cmd- Resolve shell variables and expand shorthands in a tmuxp config mapping.
tmuxp.workspace.loader.expandshell- Resolve shell variables based on user's $HOME and env.
tmuxp.cli.search.extract_workspace_fields- Extract searchable fields from a workspace file.
tmuxp.cli.search.FIELD_ALIASEStmuxp.workspace.finders.find_local_workspace_files- Find .tmuxp.* files by traversing upward from start directory.
tmuxp.cli.search.find_search_matches- Find workspaces matching search patterns.
tmuxp.workspace.finders.find_workspace_file- Return the real config path or raise an exception.
tmuxp.workspace.freezer.freeze- Freeze live tmux session into a tmuxp workspace.
tmuxp.cli.freeze.FREEZE_DESCRIPTIONtmuxp.shell.get_bpython- Return bpython shell.
tmuxp.shell.get_code- Launch basic python shell via code.
tmuxp.util.get_current_pane- Return Pane if one found in env.
tmuxp.workspace.builder.get_default_columns- Return default session column size use when building new tmux sessions.
tmuxp.workspace.builder.get_default_rows- Return default session row size use when building new tmux sessions.
tmuxp.shell.get_ipython- Return ipython shell.
tmuxp.shell.get_ipython_arguments- Return ipython shell args via IPYTHON_ARGUMENTS environment variables.
tmuxp.shell.get_launch_args- Return tmuxp shell launch arguments, counting for overrides.
tmuxp.util.get_pane- Get tmux pane for server by pane name, respects current pane, if passed.
tmuxp.shell.get_ptipython- Based on django-extensions.
tmuxp.shell.get_ptpython- Return ptpython shell.
tmuxp.util.get_session- Get tmux session for server by session name, respects current pane, if passed.
tmuxp.cli.import_config.get_teamocil_dir- Return teamocil configuration directory.
tmuxp.cli.import_config.get_tmuxinator_dir- Return tmuxinator configuration directory.
tmuxp.util.get_window- Get tmux window for server by window name, respects current pane, if passed.
tmuxp.workspace.finders.get_workspace_dir- Return tmuxp workspace directory.
tmuxp.workspace.finders.get_workspace_dir_candidates- Return all candidate workspace directories with existence status.
tmuxp.shell.has_bpython- Return True if bpython is installed.
tmuxp.shell.has_ipython- Return True if ipython is installed.
tmuxp.shell.has_ptipython- Return True if ptpython + ipython are both installed.
tmuxp.shell.has_ptpython- Return True if ptpython is installed.
tmuxp.cli.search.highlight_matches- Highlight regex matches in text.
tmuxp.cli.import_config.import_config- Import a configuration from a workspace_file.
tmuxp.cli.import_config.IMPORT_DESCRIPTIONtmuxp.workspace.importers.import_teamocil- Return tmuxp workspace from a teamocil__ YAML workspace.
tmuxp.workspace.importers.import_tmuxinator- Return tmuxp workspace from a tmuxinator__ YAML workspace.
tmuxp.cli.import_config.ImportConfigFn- Typing for import configuration callback function.
tmuxp.workspace.finders.in_cwd- Return list of workspace_files in current working directory.
tmuxp.workspace.finders.in_dir- Return a list of workspace_files in workspace_dir.
tmuxp.workspace.freezer.inline- Return workspace with inlined shorthands.
tmuxp.cli.search.InvalidFieldError- Raised when an invalid field name is specified.
tmuxp.workspace.validation.InvalidPluginsValidationError- Tmuxp configuration error for invalid plugins.
tmuxp.exc.InvalidWorkspaceBuilder- Resolved workspace_builder object is not a usable builder.
tmuxp.exc.InvalidWorkspaceBuilderOption- A workspace_builder_options value is invalid.
tmuxp.workspace.finders.is_pure_name- Return True if path is a name and not a file path.
tmuxp.workspace.finders.is_workspace_file- Return True if file has a valid workspace file type.
tmuxp.shell.launch- Launch interactive libtmux shell for tmuxp shell.
tmuxp.log.LEVEL_COLORStmuxp.plugin.LIBTMUX_MAX_VERSIONtmuxp.plugin.LIBTMUX_MIN_VERSIONtmuxp.cli.load.LOAD_DESCRIPTIONtmuxp.cli.load.load_plugins- Load and return plugins in workspace.
tmuxp.cli.load.load_workspace- Entrypoint for tmuxp load, load a tmuxp "workspace" session via config file.
tmuxp.workspace.finders.LOCAL_WORKSPACE_FILEStmuxp.log.LogFormatter- Format logs for tmuxp.
tmuxp.cli.ls.LS_DESCRIPTIONtmuxp.cli.search.normalize_fields- Normalize field names using aliases.
tmuxp.cli.nstmuxp.util.oh_my_zsh_auto_title- Give warning and offer to fix DISABLE_AUTO_TITLE.
tmuxp.exc.PaneNotFound- tmux pane not found.
tmuxp.workspace.options.PaneReadiness- Policy for whether the builder waits for a pane's shell prompt.
tmuxp.cli.search.parse_query_terms- Parse query terms into search tokens.
tmuxp.workspace.builder.prepended_sys_path- Temporarily prepend directories to sys.path, restoring it on exit.
tmuxp.cli.utils.prompt- Return user input from command line.
tmuxp.cli.utils.prompt_bool- Return True / False by prompting user input from command line.
tmuxp.cli.utils.prompt_choices- Return user input from command line from set of provided choices.
tmuxp.cli.utils.prompt_yes_no- prompt_bool() returning yes by default.
tmuxp.util.PY2tmuxp.workspace.builder.resolve_builder_class- Resolve the workspace builder class selected by session_config.
tmuxp.workspace.builder.resolve_builder_paths- Resolve and validate trusted workspace_builder_paths import roots.
tmuxp.workspace.options.resolve_session_shell- Resolve the effective interactive shell for a tmux session.
tmuxp.workspace.builder.classic.ROWS_FALLBACKtmuxp.util.run_before_script- Execute shell script, streaming output to callback or terminal (if TTY).
tmuxp.workspace.validation.SchemaValidationError- Tmuxp configuration validation base error.
tmuxp.cli.search.SEARCH_DESCRIPTIONtmuxp.cli.search.SearchPattern- Compiled search pattern with regex and metadata.
tmuxp.cli.search.SearchToken- Parsed search token with target fields and raw pattern.
tmuxp.exc.SessionMissingWorkspaceException- Session missing while loading tmuxp workspace.
tmuxp.workspace.validation.SessionNameMissingValidationError- Tmuxp configuration error for session name missing.
tmuxp.exc.SessionNotFound- tmux session not found.
tmuxp.log.set_style- Stylize terminal logging output.
tmuxp.log.setup_log_file- Attach a file handler to the tmuxp logger.
tmuxp.cli.setup_logger- Configure tmuxp's logging for CLI use.
tmuxp.plugin.setup_plugin_config- Initialize tmuxp plugin configuration.
tmuxp.cli.shell.SHELL_DESCRIPTIONtmuxp.workspace.options.shell_is_zsh- Return True when shell names the zsh shell.
tmuxp.cli.startup- Initialize CLI.
tmuxp.types.StrPath- os.PathLike or str
tmuxp.plugin.TMUX_MAX_VERSIONtmuxp.plugin.TMUX_MIN_VERSIONtmuxp.log.tmuxp_echo- Print user-facing CLI output.
tmuxp.plugin.TMUXP_MAX_VERSIONtmuxp.plugin.TMUXP_MIN_VERSIONtmuxp.cli.debug_info.tmuxp_pathtmuxp.exc.TmuxpException- Base Exception for Tmuxp Errors.
tmuxp.log.TmuxpLoggerAdapter- LoggerAdapter that merges extra dictionary on Python < 3.13.
tmuxp.plugin.TmuxpPlugin- Base class for a tmuxp plugin.
tmuxp.exc.TmuxpPluginException- Base Exception for Tmuxp Errors.
tmuxp.workspace.loader.trickle- Return a dict with "trickled down" / inherited workspace values.
tmuxp.cli.search.VALID_FIELDStmuxp.workspace.constants.VALID_WORKSPACE_DIR_FILE_EXTENSIONStmuxp.plugin.validate_plugin_config- Return True if tmuxp plugin configuration valid, also upcasts.
tmuxp.workspace.validation.validate_schema- Return True if workspace schema is correct.
tmuxp.workspace.validation.WindowListMissingValidationError- Tmuxp configuration error for window list missing.
tmuxp.workspace.validation.WindowNameMissingValidationError- Tmuxp configuration error for missing window_name.
tmuxp.exc.WindowNotFound- tmux window not found.
tmuxp.workspace.builder.WORKSPACE_BUILDERS_GROUP- Entry-point group packaged builders register under.
tmuxp.workspace.builder.WorkspaceBuildertmuxp.exc.WorkspaceBuilderError- Base error for resolving and validating a workspace builder.
tmuxp.exc.WorkspaceBuilderImportError- Configured workspace_builder failed to import.
tmuxp.exc.WorkspaceBuilderNotFound- Configured workspace_builder could not be resolved.
tmuxp.workspace.options.WorkspaceBuilderOptions- Parsed workspace_builder_options catalog.
tmuxp.exc.WorkspaceBuilderPathError- A workspace_builder_paths entry is not a usable directory.
tmuxp.workspace.builder.WorkspaceBuilderProtocol- Contract a builder must satisfy to be driven by tmuxp load.
tmuxp.exc.WorkspaceError- Error parsing tmuxp workspace data.
tmuxp.cli.search.WorkspaceFields- Extracted searchable fields from a workspace file.
tmuxp.cli.ls.WorkspaceInfo- Workspace file information for JSON output.
tmuxp.cli.search.WorkspaceSearchResult- Search result for a workspace that matched.