felixm
7d851dcb7e
Adds a non-fatal bubblewrap check to the doctor command that reports whether the bwrap binary is available. This is necessary for sandboxed sessions and the check is displayed alongside other system requirement checks. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
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/excludeso 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.