felixm
f6ed53ce23
Adds sandbox_available param to NewSessionScreen, renders Switch/Select/ Switch widgets for sandbox on/off, filesystem access (rw/ro), and network toggle. When bwrap is unavailable the switch is disabled and a warning label is shown. The _policy_from staticmethod maps widget values to SandboxPolicy. The result tuple gains SandboxPolicy | None as its fifth element. app.py passes sandbox_available=sandbox.is_available() when opening the dialog and unpacks the new element to forward sandbox= to create_session. 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.