Agents

An agent is a process launched from a profile into a terminal scoped to a worktree. DevHQ keeps the agent list per worktree and tells you which one needs attention.

Create an agent

Run devhq:create-agent. Name the agent and pick a profile. DevHQ launches it in a Ghostty-backed terminal tab with repository-aware environment variables, opened in the active worktree. For remote mirrors, the terminal SSHes to the host and enters the real remote worktree path before launching the process.

Profiles

A profile defines the command an agent runs. While this would typically be your agent cli, it could be any long-running process you want.

$REPO resolves to the parent repo, $PWD is the active worktree directory.

Default ships with a codex profile, you can easily add more profiles in Lite XL settings.

local claude = "/Users/manujbhatia/.local/bin/claude"
config.plugins.devhq.agents["claude"] = {
  start = claude .. " --add-dir $REPO",
  resume = claude .. " --add-dir $REPO --resume",
}

Attention state

When an agent emits a terminal notification or bell, DevHQ marks it as needing input in the sidebar. The marker clears when you focus or type into that agent’s terminal. The signal is meant to be glanced at across many concurrent agents.

Session lifecycle

Pair DevHQ with a session manager such as shpool or atch so agent sessions reattach across restarts of Lite XL.