# libtmux.neo._token_scope

- **Module:** libtmux.neo
- **Package:** libtmux
- **Language:** Python
- **Kind:** function
- **Source:** https://github.com/tmux-python/libtmux/blob/036c521c4b83ce6e434eb50afe2a0d08a6a05e46/src/libtmux/neo.py#L180
- **Page:** https://libtmux.org/reference/py/libtmux-neo-_token_scope/

```
libtmux.neo._token_scope(field_name: str) -> str
```

Resolve a format token's scope from its name.

Returns ``"universal"`` for cross-scope tokens (e.g. ``version``,
``socket_path``, ``host``). Returns ``"event"`` for runtime-only tokens
that never appear in a ``list-*`` output (mouse, cursor, selection,
popup). Returns ``"context"`` for tokens registered outside
``format.c``'s static table (only resolve in a specific command or
mode context). Returns ``"pane"`` / ``"window"`` / ``"session"`` /
``"client"`` / ``"buffer"`` for scope-prefixed tokens.

Fields that don't match any prefix, override, or known-token table
fall back to ``"unknown"``. ``"unknown"`` is intentionally absent from
every :data:`SCOPES_BY_LIST_CMD` entry, so an unclassified field is
excluded from every ``list-*`` ``-F`` template — preventing a future
untracked field from being silently emitted under a list command
where it might crash older tmux. Add such a field to
:data:`_SCOPE_OVERRIDES` (or the appropriate prefix / known-token
table) to admit it.

## Example

```python
>>> from libtmux.neo import _token_scope
>>> _token_scope("pane_id")
'pane'
>>> _token_scope("window_zoomed_flag")
'window'
>>> _token_scope("client_name")
'client'
>>> _token_scope("version")
'universal'
>>> _token_scope("mouse_x")
'event'
```

## Example

Tokens whose name doesn't carry a scope prefix can still be scope-gated via :data:`_SCOPE_OVERRIDES` (verified against tmux's ``format_cb_*``). The override also corrects prefix-misclassified tokens — e.g. ``mouse_all_flag`` is a per-pane mode bit, not a runtime mouse event:

```python
>>> _token_scope("mouse_all_flag")
'pane'
>>> _token_scope("active_window_index")
'session'
```

## Example

Context-only tokens (registered outside ``format.c``'s static table) route to the ``"context"`` scope and are excluded from every ``list-*`` ``-F`` template:

```python
>>> _token_scope("command_list_alias")
'context'
>>> _token_scope("search_match")
'context'
```

## Example

Unclassified tokens fall back to ``"unknown"``, also excluded from every list command:

```python
>>> _token_scope("libtmux_test_nonexistent_token")
'unknown'
```