Automation

Coding Agents

Agents running in Hyla can use the hyla command like you do: start a dev server in a pane below them, hand a review to a second agent, wait for tests, and tell you when they're blocked.

Install the skill

sh
hyla skill setup

This installs two things:

  • A skill that teaches agents the CLI. Claude Code reads it from ~/.claude/skills/hyla; Codex, OpenCode and other agents from ~/.agents/skills/hyla.
  • A hook that runs as an agent starts a session. It tells the agent which Hyla session and pane it's in, so it doesn't spend time finding out, and has it name an unnamed session after its task, such as fix-login-redirect, so you don't have to. It also tells Hyla the agent's own session, so that after hylad restarts, as after a reboot, the agent picks up its conversation.

The hook goes where each agent looks for one, for the agents you have installed:

Agent Where the hook goes
Claude Code A SessionStart hook in ~/.claude/settings.json
Codex A SessionStart hook in ~/.codex/hooks.json
Pi An extension, ~/.pi/agent/extensions/hyla.ts
OpenCode A plugin, ~/.config/opencode/plugins/hyla

Hyla follows CLAUDE_CONFIG_DIR, CODEX_HOME, PI_CODING_AGENT_DIR and XDG_CONFIG_HOME when they move an agent's files, and leaves the rest of each settings file as it was.

For Feishu chats, Claude Code gets a Stop hook as well. As each turn ends, the hook writes the agent's final message to the file the bot gives the pane. The bot replies with that message, not with the terminal's frames. To turn it on, run hyla skill setup again. The other agents keep the terminal's text.

Pass --agent with claude, codex, pi or opencode to set up one agent only. Setup is once: the skill is a link to Hyla's own copy, which follows Hyla as it updates, and Hyla keeps the Pi and OpenCode plugins current too. hyla skill status tells you whether each part is current.

sh
hyla skill status    # what's installed, and whether it's current
hyla skill show      # print the skill
hyla skill remove    # uninstall the skill and the hooks

The hook works only in agent sessions started after setup, and agents may ask first:

  • Claude Code runs hooks only in folders you trust.
  • Codex asks you to approve a new hook: approve Hyla's with /hooks.
  • OpenCode loads plugins as its background service starts: run opencode service restart once, when no session is busy.

OpenCode runs an agent's commands in its background service rather than in the pane, so they don't have HYLA_SESSION and HYLA_PANE. Hyla tells the agent its pane instead, for it to name as the target. For the same reason, hyla report from an OpenCode agent doesn't reach its pane.

Outside Hyla, the hook does nothing.

What agents can do

Run something beside themselves:

sh
hyla split --down -- npm run dev
hyla new -n review -- claude

Drive it and read the result:

sh
hyla prompt review "review the changes in src/auth"
hyla wait tests --for idle,error --timeout 10m
hyla read tests -n 60

Run tests beside themselves and read what failed:

sh
pane=$(hyla split --down -- go test ./...)
hyla wait "$pane" --exit || hyla read "$pane" -n 80

Tell you what's going on:

sh
hyla report working "Migrating the database" --progress 40
hyla report blocked "Approve the production deploy?"
hyla report done "Deployed to staging"

A blocked report turns the session to waiting and notifies you, so agents should use it only when they can't continue without you.

Remote Control

With Remote Control on (the default, in Settings › Agents), agents can also drive the app itself: show a session with hyla focus, or run menu actions with hyla do. Turn it off with remote-control = false to keep agents to their own sessions.

Environment

Every pane gets:

Variable Value
HYLA_SESSION The id of the pane's session
HYLA_PANE The id of the pane

Check $HYLA_PANE to tell whether a script runs inside Hyla.