taskflow-hosts

taskflow-hosts

Shared host-runner collection for taskflow.

This package holds the SubagentRunner implementations for taskflow's non-pi hosts — codex, claude, opencode, grok, and hermes — plus their pure argv builders (buildCodexArgs / buildClaudeArgs / buildOpencodeArgs / buildGrokArgs / buildHermesArgs) and event-stream parsers. It is the single place host runners live; a new host adds a <host>-runner.ts here.

Why a separate package

Each host has two halves:

• The runner — spawn that host's CLI, fold its JSON event stream into a host-neutral RunResult, classify the outcome. + the pure argv builder + permission/model helpers.
• The delivery — the per-host MCP server + bin + plugin scaffold, which is that host ecosystem's install target (codex plugin add, claude plugin install, OpenCode config, grok plugin install, Hermes mcp_servers).

Half #1 is nearly identical in shape across hosts and changes for the same reasons (a taskflow-core contract change, or a host CLI flag change). Half #2 is genuinely host-specific (different install mechanisms, different plugin manifests). So #1 is collected here; #2 stays in codex-taskflow / claude-taskflow / opencode-taskflow / grok-taskflow / hermes-taskflow, which import their runner from this package.

Install

You usually don't install this directly — install the host delivery package:

npm install -g codex-taskflow     # or claude-taskflow / opencode-taskflow / grok-taskflow / hermes-taskflow

For code-level use:

npm install taskflow-hosts

Usage

// one host, tree-shaken:
import { codexSubagentRunner, buildCodexArgs } from "taskflow-hosts/codex";
import { grokSubagentRunner, buildGrokArgs } from "taskflow-hosts/grok";
import { hermesSubagentRunner, buildHermesArgs } from "taskflow-hosts/hermes";

// or the barrel:
import {
	claudeSubagentRunner,
	opencodeSubagentRunner,
	grokSubagentRunner,
	hermesSubagentRunner,
} from "taskflow-hosts";

Each runner export includes: the SubagentRunner (codexSubagentRunner / …), the runXxxAgentTask function, the pure buildXxxArgs builder, the foldXxxEventLine parser + newXxxAccumulator, and the permission/model helpers (sandboxForTools, permissionArgsForTools / permissionArgsForGrokTools, isReadOnlyPhase, resolveXxxModel, xxxBin).

Hosts

Host	CLI spawn	Delivery package
Codex	codex exec --json	codex-taskflow
Claude Code	claude -p --output-format stream-json	claude-taskflow
OpenCode	opencode run --format json	opencode-taskflow
Grok Build	grok -p --output-format streaming-json	grok-taskflow
Hermes Agent	hermes chat -q -Q --source tool	hermes-taskflow

Adding a host

• Add <host>-runner.ts in src/ (model it on an existing one — a pure buildXxxArgs + the event parser + a SubagentRunner export).
• Add an export entry in src/index.ts (watch for name collisions on shared helper names like permissionArgsForTools).
• Add *-runner.test.ts (event-stream parser) + *-args.test.ts (argv contract — CI-locked) in test/.
• The host's delivery (MCP server/bin + plugin scaffold) goes in a taskflow-hosts-depending package of its own.

See AGENTS.md and DECISIONS.md in the repo root for the full architecture and the packaging decision.

License

MIT