Codex HQ Toolkit

Reusable multi-repo HQ orchestration toolkit for Codex-driven workspaces.

Purpose

This project extracts the reusable parts of the linoleumHQ orchestration setup into a separate project.

Use it to scaffold a new HQ workspace that can:

• register worker agents for selected repo directories
• run worker Codex sessions in tmux
• route user requests through HQ
• maintain handoff and reply state on disk
• distinguish between in-flight waiting and items that need HQ attention now

Initialize a Workspace

From this toolkit directory:

node ./bin/hq-toolkit.mjs init /path/to/my-hq

This will scaffold:

• hq
• package.json
• scripts/
• docs/
• state/
• AGENTS.md
• .gitignore

Then inside the target workspace:

source ~/.zshrc
hq onboard repo-agent /path/to/my-hq/some-repo worker-role --owns "developer experience"
hq run "investigate build failures"
hq wait
hq needs-attention

Notes

• The generated workspace stores only the HQ coordinator by default.
• Worker repos are added later with hq onboard or hq register.
• owns is free-form human-language routing guidance, not a strict enum.
• hq wait reports whether HQ is waiting on outstanding handoffs.
• hq needs-attention reports replies or blocked handoffs that need review.

Current Repo State

• This repository is the toolkit source of truth, not a generated HQ workspace.
• The current template includes the HQ command surface for run, ask, reply, inbox, trace, wait, and needs-attention.
• template/ contains the scaffolded workspace layout, scripts, docs, and initial state files used by hq-toolkit init.
• The configured git remote for this repository is https://github.com/ebadac/hq-toolkit.git.