Plugins

Plugins are loaded from Lua with tpane.use.

tpane.use("sensible")
tpane.use("vim-navigator")
tpane.use("yank")
tpane.use("open-url")
tpane.use("themes")
tpane.use("pane-detection")
tpane.use("agents")

Built-in plugins

sensible

Common tmux defaults:

tpane.use("sensible")

Sets:

tpane.options {
  escape_time = 0,
  history_limit = 50000,
  display_time = 4000,
  status_interval = 5,
  focus_events = true,
  status_keys = "emacs",
  aggressive_resize = true,
}

vim-navigator

Use Vim-style pane navigation. If the active process looks like Vim, the key is sent to the pane. Otherwise tmux moves panes.

tpane.use("vim-navigator")

Binds C-h, C-j, C-k, and C-l.

yank

Copy-mode bindings for yanking selected text and pane paths.

tpane.use("yank")

open-url

Open the URL under the cursor without selecting it first.

tpane.use("open-url")

Binds <prefix> o in normal mode and C-o in copy mode. Recognizes https://, http://, www., bare domains with a TLD, IPv4 hosts, and localhost URLs.

agents

Show agent pane notifications directly in window tabs.

tpane.use("agents")
tpane.tabline({ label = "cwd" })

The plugin marks agent panes in window tabs. Built-in definitions detect claude, codex, opencode, gemini, and pi commands. By default, detected agents show as idle.

States:

State	Tab meaning
idle	agent is waiting for a prompt
working	agent is running
approval	agent needs approval
blocked	agent needs input or is blocked
done	agent finished while you were away

You can test it manually from inside an agent pane:

tpane set-state "$TMUX_PANE" working
tpane set-state "$TMUX_PANE" approval
tpane set-state "$TMUX_PANE" blocked
tpane set-state "$TMUX_PANE" done
tpane set-state "$TMUX_PANE" idle

Install available agent hooks:

tpane agents install

Preview without writing:

tpane agents install --dry-run

You can also target a tool explicitly:

tpane agents install claude
tpane agents install codex

Before uninstalling tpane, remove its hooks from Claude settings and the marked TPANE CODEX NOTIFY block from Codex configuration.

Window tabs only mark agents that need attention: a colored glyph for approval, blocked, or unseen-done, a spinner while working, and nothing when idle. A count appears when more than one agent in the window needs attention.

Custom agents can be added from Lua:

tpane.agents.register({
  name = "my-agent",
  label = "agent",
  commands = { "my-agent" },
})

themes

Bundled themes from the iTerm2 Color Schemes collection.

tpane.use("themes")
tpane.theme("Gruvbox Dark", { transparent = true })

List themes:

tpane themes

pane-detection

Basic pane labels and pane border titles by command.

tpane.use("pane-detection")

Git plugins

Use a git plugin by passing a spec:

tpane.use("tool", {
  repo = "https://github.com/example/tpane-tool.git",
  branch = "main",
})

If the plugin lives in a monorepo:

tpane.use("tool", {
  repo = "https://github.com/example/tools.git",
  path = "plugins/tpane-tool",
})

Manage installed git plugins:

tpane plugin status
tpane plugin sync
tpane plugin update
tpane plugin clean
tpane plugin list
tpane plugin remove NAME