Configuration Files

Overview

Vertical Tabs stores its data in two locations:

1. ~/.vertical-terminal/ - agent hooks, wrapper scripts, and shell integration
2. Application data directory - settings, workspace state, and window state

Both are created automatically on first launch.

The ~/.vertical-terminal/ Directory

This directory lives in your home folder and contains everything related to agent hook integration:

~/.vertical-terminal/
├── bin/                    # Agent wrapper scripts
│   ├── claude
│   ├── copilot
│   ├── codex
│   ├── gemini
│   ├── opencode
│   └── aider
├── hooks/
│   ├── agent-hook.sh       # Main lifecycle hook script
│   └── claude-hooks.json   # Claude Code hook configuration
└── shell-init.sh           # PATH setup for wrapper scripts

All files in this directory are auto-generated on app startup. Manual edits will be overwritten when Vertical Tabs detects a content change.

bin/ - Agent Wrapper Scripts

Each supported agent gets a thin wrapper script in bin/. These wrappers:

1. Find the real agent binary on your PATH (skipping themselves)
2. Inject the appropriate hook configuration for that agent
3. Execute the real binary with your original arguments

For example, the claude wrapper adds --settings pointing to the hooks config, while the codex wrapper passes a -c 'notify=...' flag. This allows Vertical Tabs to track agent lifecycle events (start, stop, permission requests) without per-agent manual configuration.

Wrapper	Hook mechanism
claude	--settings flag pointing to claude-hooks.json
copilot	Global hooks in ~/.copilot/config.json
codex	-c 'notify=[...]' flag
cursor	Writes to ~/.cursor/hooks.json
gemini	GEMINI_HOOKS_FILE environment variable
opencode	OPENCODE_HOOKS_FILE environment variable
aider	AIDER_HOOKS_FILE environment variable

hooks/agent-hook.sh

The central hook script that all agent wrappers call. When an agent fires a lifecycle event (start, stop, permission request), this script:

1. Parses the event payload (JSON from stdin or arguments, depending on the agent)
2. Extracts the event type and session ID
3. Forwards the event to Vertical Tabs via a local HTTP request on 127.0.0.1

The script only runs when inside a Vertical Tabs terminal session. If VTERM_TAB_ID and the session ID are both empty, it exits immediately.

hooks/claude-hooks.json

A JSON configuration file that tells Claude Code which lifecycle events to forward to the hook script. It covers UserPromptSubmit, Stop, PostToolUse, PostToolUseFailure, and PermissionRequest.

shell-init.sh

A small snippet that prepends ~/.vertical-terminal/bin to your PATH:

# vertical-terminal agent hooks - auto-generated
if [ -d "$HOME/.vertical-terminal/bin" ]; then
  export PATH="$HOME/.vertical-terminal/bin:$PATH"
fi

On first setup, Vertical Tabs also appends a source line to your ~/.zshrc and ~/.bashrc (if they exist) so the wrapper scripts are available in every new shell session. The source line looks like:

# vertical-terminal hooks
[ -f "$HOME/.vertical-terminal/shell-init.sh" ] && source "$HOME/.vertical-terminal/shell-init.sh"

Note

If you use a different shell (e.g., Fish), you may need to add the equivalent source command to your shell’s config file manually.

Settings File

Your preferences are stored as a JSON file in the application data directory:

Platform	Path
macOS	~/Library/Application Support/Vertical Tabs/settings.json
Windows	%APPDATA%/Vertical Tabs/settings.json
Linux	~/.config/Vertical Tabs/settings.json

Edit this file directly while the app is closed, or use the Settings panel (Cmd + ,).

Settings Reference

Key	Type	Default	Description
shell	string	/bin/zsh (macOS), powershell.exe (Windows)	Shell to launch in new tabs
fontSize	number	14	Terminal font size in pixels
fontFamily	string	'JetBrains Mono', 'Fira Code', 'SF Mono', Menlo, monospace	Font stack for the terminal
cursorBlink	boolean	true	Whether the cursor blinks
cursorStyle	string	block	Cursor shape: block, underline, or bar
scrollback	number	10000	Number of scrollback lines (500 to 100,000)
theme	string	catppuccin-mocha	Color theme name
defaultEditor	string	vscode	Editor opened by the editor button
autoUpdate	boolean | null	null	Auto-update preference (null = not yet chosen)
zoom	number	100	Zoom level as a percentage (70 to 130)
alertSound	boolean	false	Play a sound when commands finish
tabSortOrder	string	recent	Tab ordering: creation or recent
confirmDangerousActions	boolean	true	Show confirmation dialogs for destructive actions
runCommands	object	{}	Per-shell startup commands (reserved for future use)
defaultAgent	string	-	Pre-selected agent in the launcher
defaultModels	object	{}	Per-agent model preferences, e.g. { "claude-code": "opus" }

Example settings.json

{
  "shell": "/bin/zsh",
  "fontSize": 14,
  "fontFamily": "'JetBrains Mono', 'Fira Code', 'SF Mono', Menlo, monospace",
  "cursorBlink": true,
  "cursorStyle": "block",
  "scrollback": 10000,
  "theme": "catppuccin-mocha",
  "defaultEditor": "vscode",
  "autoUpdate": true,
  "zoom": 100,
  "alertSound": false,
  "tabSortOrder": "recent",
  "confirmDangerousActions": true,
  "defaultAgent": "claude-code",
  "defaultModels": {
    "claude-code": "opus",
    "copilot": "gpt-4.1"
  }
}

Tip

If you make a mistake editing the file, delete it and relaunch. Vertical Tabs recreates it with defaults.

Other Data Files

These files live alongside settings.json in the application data directory:

File	Purpose
workspace-state.json	Workspaces, tabs, and their order. Restored on launch.
window-state.json	Window size and position. Restored on launch.
diff-window-state.json	Git diff viewer window size and position.
tintage-auth.enc	Encrypted Tintage account device token and profile.

Note

Editing these files manually is not recommended. They are managed by the app and overwritten on every state change.

Environment Variables

These environment variables let you override default paths. Set them before launching Vertical Tabs.

VERTICAL_TERMINAL_USER_DATA

Override the application data directory. Settings, workspace state, and window state are read from and written to this path instead of the platform default.

VERTICAL_TERMINAL_USER_DATA=~/my-vterm-profile /Applications/Vertical\ Terminal.app/Contents/MacOS/Vertical\ Terminal

Useful for running multiple isolated profiles or for automated testing.

VERTICAL_TERMINAL_CONFIG_FILE

Override just the settings file path (without moving workspace/window state).

VERTICAL_TERMINAL_CONFIG_FILE=~/dotfiles/vertical-settings.json /Applications/Vertical\ Terminal.app/Contents/MacOS/Vertical\ Terminal

VTERM_DEBUG_HOOKS

Enable debug logging for the agent hook script. When set to any truthy value (1, true, yes, on, case-insensitive), the hook script prints event details and HTTP status codes to stderr.

export VTERM_DEBUG_HOOKS=1

You will see output like:

[agent-hook] event=Start sessionId=abc123 tabId=tab-1
[agent-hook] dispatched status=200

Useful when troubleshooting agent status tracking.

Resetting Everything

To fully reset Vertical Tabs to a clean state:

1. Quit the app
2. Delete ~/.vertical-terminal/
3. Delete the application data directory (e.g., ~/Library/Application Support/Vertical Tabs/ on macOS)
4. Remove the # vertical-terminal hooks block from ~/.zshrc and ~/.bashrc
5. Relaunch the app - all files are recreated with defaults