hqt/.hq/2026-06-09-plan-hq-terminal.md

HQ Terminal — Implementation Plan

Reference spec: .hq/2026-06-09-spec-hq-terminal.md

Phase 1: Project Scaffold

Set up the new workspace with tooling, dependencies, and basic structure.

Steps

1. Create workspace at ~/dev/hqt/ with uv init --lib --name hqt
2. Configure pyproject.toml:
   • Python ≥ 3.12
   • Dependencies: textual>=2.0, sqlalchemy>=2.0, click>=8.0
   • Dev dependencies: pytest, pytest-asyncio, ruff
   • Entry point: [project.scripts] hqt = "hqt.cli:main"
3. Create package structure per spec: src/hqt/ with all subdirectories
4. Create .hq/PROJECT.md for the new project
5. Verify: uv run hqt --help produces output

Phase 2: Database Layer

SQLite models, engine, and schema management.

Steps

1. src/hqt/config.py — Settings dataclass with paths:
   • db_path: ~/.local/share/hqt/hqt.db
   • config_dir: ~/.config/hqt/
   • skills_dir: ~/.config/hqt/skills/
   • tmux_path: tmux
   • tui_session_name: hqt-main
2. src/hqt/db/models.py — SQLAlchemy models: Project, Harness, Session, McpServer, ProjectMcpServer, ProjectSkill
3. src/hqt/db/session.py — Engine factory, session factory, ensure_db() (creates dir + tables)
4. src/hqt/db/migrate.py — Additive migration helper (add missing columns)
5. Tests: model creation, ensure_db on fresh + existing databases
6. Verify: uv run pytest tests/test_db.py -q passes

Phase 3: TmuxRunner

The async tmux command abstraction. Largely ported from HQ.

Steps

1. src/hqt/tmux/runner.py — Port TmuxRunner from HQ:
   • new_session(name, cwd, command, width, height)
   • has_session(name) -> bool
   • kill_session(name)
   • send_text(name, text)
   • send_enter(name)
   • capture_pane(name) -> str
   • switch_client(target) ← NEW (not in HQ)
   • list_sessions() -> list[str] ← NEW
2. src/hqt/tmux/manager.py — Higher-level session lifecycle:
   • spawn_session(session: Session, config: SpawnConfig) -> None
   • resume_session(session: Session, config: SpawnConfig) -> None
   • kill_session(session: Session) -> None
   • attach_session(session: Session) -> None (switch-client)
   • is_alive(session: Session) -> bool
   • poll_all_sessions(sessions: list[Session]) -> dict[int, bool]
3. Tests: mock _exec function, verify command construction
4. Verify: uv run pytest tests/test_tmux.py -q passes

Phase 4: Harness Abstraction Layer

The configurator protocol and concrete implementations.

Steps

1. src/hqt/harnesses/base.py — HarnessConfigurator protocol, SpawnConfig, HarnessIdentity dataclasses
2. src/hqt/harnesses/claude.py — Claude Code configurator:
   • UUID generation via uuid5
   • Spawn: claude --session-id {uuid} --model {model}
   • Resume: claude --resume {uuid}
   • MCP: write project .mcp.json
   • Skills: write/append CLAUDE.md
   • Ready/busy regexes from terminal profiles
3. src/hqt/harnesses/kiro.py — Kiro CLI configurator (stub for now):
   • Basic spawn command
   • MCP: Kiro-managed (no injection in v1)
4. src/hqt/harnesses/aider.py — Aider configurator:
   • Spawn: aider --model {model} --restore-chat-history
   • Skills: --read {skill_file} flags
   • No MCP support
5. src/hqt/harnesses/generic.py — Fallback for unknown harnesses:
   • Env-var based config only
6. src/hqt/harnesses/registry.py — Discover available harnesses (shutil.which), return configurator instances
7. Tests: each configurator produces correct SpawnConfig for given inputs
8. Verify: uv run pytest tests/test_harnesses.py -q passes

Phase 5: Skills & MCP Services

Skill registry and MCP server management.

Steps

1. src/hqt/skills/registry.py — Port from HQ: scan skills_dir, parse frontmatter, return Skill objects
2. src/hqt/skills/injection.py — Port from HQ: wrap_prompt_with_skills()
3. src/hqt/mcp/service.py — CRUD for MCP servers and project bindings (DB operations)
4. src/hqt/projects/service.py — Project CRUD: add, list, archive, git status reading
5. Tests: skill discovery with fixture directory, MCP CRUD, project CRUD
6. Verify: uv run pytest tests/test_skills.py tests/test_mcp.py tests/test_projects.py -q passes

Phase 6: Session Service (Orchestration Core)

The service that ties together DB, tmux, and harness configurators.

Steps

1. src/hqt/sessions/service.py — Session lifecycle:
   • create_session(project_id, harness_name, nickname, model, skill_names, mcp_ids) -> Session
     • Generates harness UUID via configurator
     • Builds SpawnConfig
     • Calls tmux manager to spawn
     • Persists session row
   • resume_session(session_id) -> None
     • Loads session from DB
     • Builds resume SpawnConfig with stored UUID
     • Calls tmux manager to spawn
   • stop_session(session_id) -> None
     • Kills tmux session
     • Updates DB (last_activity_at)
   • delete_session(session_id) -> None
     • Kills tmux if alive
     • Removes DB row
   • attach_session(session_id) -> None
     • Calls tmux switch-client
   • list_sessions(project_id) -> list[SessionInfo]
     • Joins DB data with tmux liveness
2. Tests: mock tmux manager, verify session lifecycle
3. Verify: uv run pytest tests/test_sessions.py -q passes

Phase 7: Textual TUI

The user interface.

Steps

1. src/hqt/tui/app.py — Textual App subclass:
   • Bindings: q=quit, n=new session, a=add project, /=filter
   • Compose: Header, ProjectList, SessionList, Footer
   • Timer: poll tmux liveness every 3s
2. src/hqt/tui/widgets/project_list.py — ListView of projects:
   • Shows name, path, branch
   • Selection updates session list
   • Keybindings: Enter=select, a=add, d=archive
3. src/hqt/tui/widgets/session_list.py — ListView of sessions for selected project:
   • Shows harness icon, nickname, alive/dead status
   • Keybindings: Enter=attach, n=new, d=delete, r=rename, R=resume (if dead)
4. src/hqt/tui/screens/new_session.py — Modal screen:
   • Harness selector (dropdown)
   • Nickname input
   • Model selector (populated from configurator.supported_models)
   • Skills multi-select
   • MCP servers multi-select
   • Create / Cancel buttons
5. src/hqt/tui/screens/add_project.py — Modal:
   • Path input (with directory completion if feasible, or paste)
   • Name override (optional)
6. src/hqt/tui/styles.tcss — Textual CSS for layout
7. Integration test: App mounts, projects display, key bindings respond
8. Verify: uv run pytest tests/test_tui.py -q passes (headless Textual testing)

Phase 8: CLI Entry Point & tmux Bootstrap

Wire everything together.

Steps

1. src/hqt/cli.py — Click CLI:
   • hqt (default) — bootstrap into tmux + launch TUI
   • hqt list — print projects/sessions table
   • hqt attach <id> — switch to session
   • hqt new <project> <harness> — create session non-interactively
   • hqt doctor — check tmux, harness availability
2. src/hqt/__main__.py — python -m hqt support
3. tmux bootstrap logic:

   def bootstrap():
       if not in_tmux():
           # Create hqt-main session with TUI as the command
           exec tmux new-session -s hqt-main "hqt --inside-tmux"
       else:
           # Already in tmux, just run the TUI
           run_tui()
   

4. First-run setup: suggest tmux keybinding, create config dir/skills dir
5. Verify: hqt doctor works, hqt launches TUI inside tmux

Phase 9: Integration Testing & Polish

Steps

1. End-to-end test: create project → create session → verify tmux session exists → attach → kill → verify dead
2. Handle edge cases:
   • tmux not installed → clear error
   • Harness not found → show in UI, disable create
   • DB locked → retry pattern
   • Session name collision → fail gracefully
3. README.md with quick start
4. Verify: full test suite passes, manual smoke test with claude-code

Dependency Graph

Phase 1 (scaffold)
    │
    ├── Phase 2 (database)
    │       │
    │       ├── Phase 5 (skills + MCP)
    │       │       │
    │       │       └──────┐
    │       │              │
    │       └── Phase 6 (session service) ◄── Phase 4 (harness abstraction)
    │               │
    ├── Phase 3 (tmux runner) ──────────────┘
    │                                        │
    │                                        ▼
    └── Phase 7 (TUI) ◄──────────── Phase 6
            │
            ▼
        Phase 8 (CLI + bootstrap)
            │
            ▼
        Phase 9 (integration + polish)

Estimated Effort

Phase	Complexity	Approx. LOC
1. Scaffold	Low	~50 (config)
2. Database	Low	~150
3. TmuxRunner	Low	~120 (mostly port)
4. Harness abstraction	Medium	~300
5. Skills + MCP	Low	~150 (mostly port)
6. Session service	Medium	~200
7. TUI	Medium-High	~400
8. CLI + bootstrap	Low	~100
9. Integration	Medium	~150
Total		~1,620

Implementation Order (sequential for a single agent)

1. Phase 1 → 2. Phase 2 → 3. Phase 3 → 4. Phase 4 → 5. Phase 5 → 6. Phase 6 → 7. Phase 7 → 8. Phase 8 → 9. Phase 9

Each phase produces a working, testable increment. The TUI (Phase 7) is the largest single piece but depends on everything below it being solid.