hqt — HQ Terminal

A TUI for orchestrating AI coding harness sessions (Claude Code, Kiro, Aider, etc.) via tmux. Manage multiple AI sessions across projects from a single terminal interface.

Quick Start

uv pip install -e .
hqt

Commands

Command	Description
hqt	Launch the TUI (inside tmux)
hqt doctor	Check system requirements
hqt list	List projects and sessions

Key Bindings

Key	Action
q	Quit
n	New session
a	Add project
e	Edit project
Tab	Switch panel
d	Delete session
Enter	Attach to session (auto-resumes if not running)
r	Rename session
s	Stop session

Worktree-isolated sessions

The New Session dialog (n) has an Isolate in worktree checkbox. When the selected project is a git repository, checking it runs the session in a dedicated git worktree instead of the project root, so concurrent sessions don't step on each other's working tree.

• The worktree lives at <project>/.worktrees/<branch> and is automatically added to the repo's .git/info/exclude so it never shows up as untracked.
• The branch is created off the current HEAD. If you leave the branch field blank it defaults to a slugified form of the session nickname.
• For non-git projects the checkbox is disabled.

Deleting a worktree session (d) opens a confirmation dialog with an Also remove worktree option. As a safety check, if the worktree has uncommitted changes or unmerged commits a warning is shown and the removal box is left unchecked — checking it then forces removal and discards that work.

Known limitation: submodules are not initialized in freshly created worktrees; run git submodule update --init inside the worktree if your project needs them.

Architecture

hqt uses a layered architecture: a Click CLI bootstraps into a Textual TUI, which drives service classes (ProjectService, SessionService) backed by SQLite via SQLAlchemy. Sessions are spawned as tmux windows through TmuxManager, with harness-specific configuration provided by pluggable HarnessConfigurator implementations discovered at runtime.