Configuration

teru reads a simple key = value config file at ~/.config/teru/teru.conf. No Lua, no TOML, no JSON — plain key-value pairs with # comments. All settings are optional; teru falls back to sensible defaults when the file is missing or individual keys are absent.

Config File Location

~/.config/teru/teru.conf

teru creates no config file on first run. Create it manually when you want to customize behavior.

Complete Reference

Appearance

Key	Default	Description
`font_path`	system default	Path to a `.ttf` font file
`font_size`	`16`	Font size in points

font_size = 14
font_path = /usr/share/fonts/TTF/Hack-Regular.ttf

Colors

All colors are hex RGB values (6 digits, # prefix). Defaults use the miozu base16 color scheme.

Key	Default	Description
`bg`	`#1D1D23`	Background color
`fg`	`#FAF8FB`	Foreground (text) color
`cursor_color`	`#FF9922`	Cursor color
`selection_bg`	`#38384C`	Text selection highlight
`border_active`	`#FF9922`	Active pane border color
`border_inactive`	`#38384C`	Inactive pane border color

bg = #1D1D23
fg = #FAF8FB
cursor_color = #FF9922
selection_bg = #38384C
border_active = #FF9922
border_inactive = #38384C

Terminal

Key	Default	Description
`scrollback_lines`	`10000`	Lines of scrollback to keep
`shell`	`$SHELL`	Shell to run (overrides environment variable)

scrollback_lines = 50000
shell = /usr/bin/fish

Keybindings

Key	Default	Description
`prefix_key`	`ctrl+space`	Prefix key for multiplexer commands

Accepted values: ctrl+a through ctrl+z, ctrl+space, or a raw integer keycode.

prefix_key = ctrl+b

Window

Key	Default	Description
`initial_width`	`960`	Initial window width in pixels
`initial_height`	`640`	Initial window height in pixels

initial_width = 1200
initial_height = 800

Hooks

Hooks are external commands executed when teru events occur. The command is run via fork + exec — it does not block teru.

Key	Trigger
`hook_on_spawn`	A new pane is created
`hook_on_close`	A pane is closed
`hook_on_agent_start`	An AI agent declares itself via OSC 9999
`hook_on_session_save`	Session is saved (detach)

hook_on_spawn = notify-send "teru" "New pane opened"
hook_on_close = notify-send "teru" "Pane closed"
hook_on_agent_start = ~/.config/teru/hooks/agent.sh
hook_on_session_save = ~/.config/teru/hooks/backup.sh

Hook scripts receive event metadata as environment variables.

Example Config

A complete example for a typical development setup:

# Appearance
font_size = 14
font_path = /usr/share/fonts/TTF/JetBrainsMonoNL-Regular.ttf
bg = #1D1D23
fg = #FAF8FB
cursor_color = #FF9922

# Terminal
scrollback_lines = 50000
shell = /usr/bin/fish

# Window
initial_width = 1400
initial_height = 900

# Keybindings
prefix_key = ctrl+space

# Hooks
hook_on_agent_start = ~/.config/teru/hooks/agent-notify.sh
hook_on_session_save = ~/.config/teru/hooks/session-backup.sh

Notes

Lines starting with # are comments
Unknown keys are silently ignored
Config is read once at startup — restart teru to apply changes
Maximum config file size: 64KB (configs should be tiny)