# 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

```bash
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](https://git-scm.com/docs/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.