felixm
5f29418186
Address three integration gaps found in review: - Bind ~/.gitconfig read-only in the sandbox base layer so `git commit` finds user.name/email inside the jail (spec §3). - Bind a worktree session's repo common .git dir writable: the worktree's real gitdir lives at <repo>/.git/worktrees/<branch>, outside the bound cwd, so git was broken in sandboxed worktree sessions. - doctor now gates on sandbox.is_available() (the single source of truth shared with the New Session dialog) rather than a raw shutil.which, so it agrees with the service on non-Linux platforms (spec §6). 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.