felixm
f5c97d1fe0
Add tool windows: tool registry, styled aux tmux windows (TmuxRunner.new_aux_window / TmuxManager.open_aux_window), SessionService tool-window + clone-for-window methods, and hqt tool / hqt palette CLI subcommands (fzf tool launcher). # Conflicts: # src/hqt/cli.py # src/hqt/tmux/manager.py # tests/test_cli.py # tests/test_sessions.py
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.