Skip to content

About

No description, website, or topics provided.

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

311 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

harness-cli-normalizer

CI npm license: MIT

A unified interface across multiple coding agents.

hcn is a command-line tool for scripts and agents that hand work to coding-agent CLIs. hcn calls each of these CLIs a harness. It currently supports Claude Code, Codex, pi, Muse, Cursor CLI, Antigravity CLI, popeye, and OpenCode CLI. You choose the harness and model for each task and pass the same options to any of them. hcn translates the options into that harness's flags and reports the result as the same JSON events and exit codes. If a harness has no equivalent for an option, hcn exits without starting it and lists the harnesses that do.

$ hcn inspect claude --argv --access read --context-window 200000 --prompt "find bugs in src/"
...
argv: claude -p --effort medium --autocompact 200000 --permission-mode dontAsk --disallowedTools mcp__* --tools Read,Grep,Glob,WebFetch,WebSearch ...

$ hcn inspect codex --argv --access read --context-window 200000 --prompt "find bugs in src/"
...
argv: codex exec --json ... -c model_context_window=200000 --disable memories --sandbox read-only ...

$ hcn inspect pi --argv --access read --context-window 200000 --prompt "find bugs in src/"
pi cannot express option "contextWindow" (200000); supported: effort, provider, ... - drop the option or route this work to a harness that supports it
supported on: claude (--autocompact), codex (-c), popeye (--context-window)

hcn inspect --argv prints the command hcn would run. hcn run takes the same flags and runs it. To have the harness and model chosen for you, put model-router in front of hcn, as described in How the three packages fit.

Install

hcn needs Node 24 or newer. For CLI-backed harnesses, install and sign in to a CLI linked under Thanks; hcn uses that CLI's login.

Cursor is the exception: hcn run cursor and hcn session cursor run through the Cursor SDK (a dependency the hcn package installs) in a worker process hcn owns. The SDK needs its own authentication - a CURSOR_API_KEY, or a key stored by the SDK's browser login at ~/.cursor/sdk/auth.json - and a login to the native Cursor CLI does not satisfy it. See Cursor's SDK authentication.

npm install -g @dungle-scrubs/harness-cli-normalizer

hcn ls lists the harnesses and the CLI version hcn was verified against for each:

$ hcn ls
claude@2.1.312 (npm:@anthropic-ai/claude-code)
codex@0.165.0 (npm:@openai/codex)
pi@1.4.0 (npm:@earendil-works/pi-coding-agent)
muse@1.4.2 (installed:muse)
cursor@1.0.38 (npm:@cursor/sdk)
antigravity@1.3.3 (installed:agy)
popeye@0.2.0 (npm:@dungle-scrubs/popeye)
opencode@1.19.5 (npm:opencode-ai)

To teach your coding agents hcn's flags, events and refusals, install its agent skill:

npx skills add dungle-scrubs/harness-cli-normalizer --skill hcn -g

Usage

Run a turn

$ hcn run claude "name three primes, nothing else" --model haiku
provenance: effort = "medium" (profile)
...
divergence: profile "sandbox" not expressible on claude; harness default applies
env: CLAUDE_CODE_DISABLE_AUTO_MEMORY=1
spawn: claude -p --effort medium [prompt:969ch] --output-format stream-json --verbose --include-partial-messages --model claude-haiku-5-5
provenance: questions = ask (default)
  ● session d8b139a5-14d4-40dc-852e-3ae87d23b221 (harness-minted)
2, 3, 5
  ○ clean (exit 0)

To use another harness, replace claude with codex, pi, muse, cursor, antigravity, popeye, or opencode and keep the other flags. hcn checks --model and --effort against the harness first. On claude, --setting-sources <list> (user, project, local) picks which settings scopes the child loads; runs pass nothing by default and sessions pin project. For example, --model haiku on codex exits 2 and lists the codex models. The stderr lines show where each setting came from (provenance:), what the harness cannot express (divergence:), and the command hcn ran (spawn:). The prompt is longer than what you typed because hcn adds a preamble that tells the model how to ask you a question. See Answer a question from the model.

Limit tools and access

hcn run codex "find bugs in src/" --access read
hcn run claude "update the parser" --access write --no-autonomy
hcn run claude "find bugs in src/" --tools read,grep,glob
hcn run claude "find bugs in src/" --context-window 200000

--access read becomes a closed --tools Read,Grep,Glob,WebFetch,WebSearch set plus --permission-mode dontAsk and an explicit mcp__* deny on Claude Code, --sandbox read-only on Codex, and --tools on pi. --tools and --exclude-tools use the same tool names on every harness: read, write, edit, shell, grep, glob, list, web-fetch, web-search, subagent, and skill. --skills limits skills in the same way.

On Claude Code, --access write selects --permission-mode acceptEdits and requests a strict native sandbox that auto-approves sandboxed Bash. hcn keeps filesystem isolation on, disables unsandboxed retries, and requests that Claude stop if the sandbox cannot start. The sandbox covers Bash, not native file or web tools. Native permission checks and managed policy still apply.

Strict mode also limits network access. Unless managed policy overrides strict mode, Claude ignores project-level domain allowlists. Dependency installs and tests may need trusted user or managed network policy and writable paths. hcn adds neither domains nor extra writable roots. With --access write --autonomy, Claude keeps the explicit Bash sandbox while its permission mode becomes bypassPermissions. That mode can approve hosts outside the network allowlist unless strictAllowlist, allowManagedDomainsOnly, or native denied-domain policy blocks them. Claude documents that matrix for interactive terminal sessions, and hcn has not verified it headless. A native httpProxyPort or socksProxyPort moves filtering to that custom proxy, outside Claude's own domain controls. Keeping the filesystem sandbox does not promise network confinement. Autonomy alone does not request this sandbox. See the access mappings and native limits.

On Cursor, --access read selects the SDK's read-only toolset (read, grep, glob, ls, webFetch, webSearch, with task and mcp disallowed). That is tool selection, not a filesystem or network sandbox. Cursor write access is unconfined: --access write runs the SDK's native toolset with its sandbox explicitly off. A bare run or bare session sets no hcn restriction - the SDK's native defaults apply (its standard toolset runs without approval, and its sandbox ships disabled) - so use hcn run cursor --access read for the restricted toolset; a Cursor session has no restricted preset and refuses --access with exit 2. On a run, an explicit read stays read even together with --autonomy; only write, or autonomy without an explicit read, gains the unconfined toolset. The SDK does not provide the native CLI's workspace-trust refusal; a bare SDK run can execute in a directory the CLI has not trusted. See the Cursor access mapping.

Read results as JSON

$ hcn run claude "name three primes, nothing else" --model haiku --json
{"kind":"identity","sessionId":"7e3712eb-76cf-4c00-a72a-ba08ab1f78db","authority":"harness-minted","capabilities":{...}}
...
{"kind":"message","role":"assistant","text":"2, 3, 5"}
{"kind":"done","exitCode":0,"cause":"clean","escalation":{"mode":"ask","detection":"none"}}

--json prints one JSON event per line. Native tool outputs arrive as tool-result events, including structured extension results and error flags when reported. Native token counts and cost estimates arrive as scoped usage events. A clean done does not mean every tool succeeded; check the tool results. Native tool-denial reports can also produce error.denial observations. hcn reports each valid entry in Claude's final permission_denials with the tool name, optional call ID, and a bounded input summary. A turn with denial observations adds a positive done.denialCount; human output adds [denials: N]. The count reports observations, not unique calls or task correctness. A missing count does not establish success: a failed command can produce only tool-result.isError. See the event contract. The format is the same for every harness, and the last line is always done. A TypeScript consumer can import the wire types instead of handwriting them: import type { RunEvent } from "@dungle-scrubs/harness-cli-normalizer/protocol" (also SessionEvent and SessionCommand for hcn session --json). They describe the installed version's wire format; no client ships with them. On a nonzero run exit, done.completion preserves output evidence: native-terminal means the harness reported successful turn completion; message-delivered means assistant text arrived without confirmed turn completion. The process failure remains in cause/failure, and exitCode keeps the harness's actual status. If the run failed, done.failure.retryable says whether a retry can help, and done.failure.class gives the reason, such as rate-limit, auth, transport, or rejected. A refusal also lists the harnesses that support the option:

$ hcn run pi "find bugs in src/" --context-window 200000 --json
{"kind":"failure","class":"rejected","retryable":false,...,"supportedBy":[{"harness":"claude","spelling":"--autocompact"},{"harness":"codex","spelling":"-c"},{"harness":"popeye","spelling":"--context-window"}]}
{"kind":"done","exitCode":null,"cause":"failed","failure":{...}}

Run a route from model-router

$ model-router '{"task":"code-review","stakes":"normal","privacy":"normal"}' \
    | jq -c '.routes[0] | {harness, modelId, effort}'
{"harness":"pi","modelId":"zai/glm-5.3","effort":"xhigh"}
$ hcn run pi --model zai/glm-5.3 --effort xhigh --access read "review the diff on this branch"

A route has a harness, a model id, an effort, and for some routes a provider. Pass them to hcn run as the harness argument, --model, --effort, and --provider. If the run fails with retryable: true, run the next route in .routes. The routes come from your registry, so yours will differ.

Keep a session open

$ printf '%s\n' '{"op":"send","id":"in-1","text":"name three primes, nothing else"}' \
    | hcn session claude --model haiku --json
{"kind":"session","sessionId":"230f0d30-47d8-49bd-bcfc-ba2c5008776c","harness":"claude","hcn":"0.9.8","questions":"ask","origin":"fresh"}
{"kind":"disposition","id":"in-1","disposition":"started"}
{"kind":"turn","turnId":"230f0d30-47d8-49bd-bcfc-ba2c5008776c:turn-1","id":"in-1"}
...
{"kind":"message","role":"assistant","text":"2, 3, 5"}
{"kind":"done","exitCode":null,"cause":"clean",...}
{"kind":"closed","exitCode":0,"cause":"clean"}

With --json, you write commands to stdin, one JSON object per line (send, answer, interrupt, settings, approval, close), and read events from stdout. Each send gets one disposition; turns opened by a send carry its id. Check the session packet's controls before choosing delivery queue or steer, or interrupting and sending a replacement after confirmation. On a Claude session, --native-approvals forwards each permission request, AskUserQuestion and plan approval to you as approval-request events; on a pi session it forwards each extension select and input dialog (a dialog stays open across turns), plus an extension's marked [hcn-question] editor dialog, which asks hcn's own question set (checkboxes, free text, per-question notes). See the reference. On Claude and pi sessions, the settings op changes model and effort mid-session, and send takes "verbatim": true to type the harness's own slash command untouched (Claude slash commands; on pi only extension commands such as /skill:x run); see the reference. Sessions work with Claude Code, Codex, pi, Cursor, Antigravity CLI, and popeye. Cursor sessions run the SDK in hcn's worker: a busy send is rejected by the SDK (no queue), interrupt is best-effort cancellation, and the session surface takes no access options, so a Cursor session runs at the SDK's native defaults. Without --json, hcn session claude opens an interactive prompt.

Read saved sessions

$ hcn transcript ls --limit 1
{"schemaVersion":1,"kind":"session-list-source","hcnVersion":"0.9.8","harnesses":["claude","codex","pi","muse","cursor","antigravity","popeye"],...}
{"schemaVersion":1,"kind":"session","harness":"claude","id":"1daeb0ec-1d9c-4461-8e5c-84ca8c6ee3f6",...,"mode":"interactive","readable":true,"blocked":null}
{"schemaVersion":1,"kind":"session-list-result","exitCode":0,"status":"complete","rowsReturned":1,"more":true,...}
$ hcn transcript read claude --id 1daeb0ec-1d9c-4461-8e5c-84ca8c6ee3f6 > transcript.jsonl

hcn transcript ls lists the saved sessions of every harness for the current directory, newest first, in one format. hcn transcript read exports the messages and tool results of one session without starting the harness. For Cursor, the reader covers historical CLI chats; new SDK conversations are not listed or readable here. Support differs by harness; see docs/transcripts.md.

Answer a question from the model

$ hcn run claude "Add a database to the new service. Postgres or SQLite are both fine and the choice is mine, not yours." --model haiku --access read --json
...
{"kind":"question","question":"Which database should the new service use, ...","options":["SQLite","Postgres"],"recommended":"SQLite"}
{"kind":"done","exitCode":0,"cause":"awaiting-input","escalation":{"mode":"ask","detection":"block"}}
$ hcn run claude --resume 98ba94a4-f51b-49ef-b515-2e2202a4fc0e --prompt "Postgres"

By default, hcn's preamble tells the model how to ask a question when it cannot make a decision itself. The turn then ends with a question event and a done event with cause awaiting-input (exit 0). Ask your user, then resume the session with the answer, using the sessionId from the identity event. With --questions assume, the model states its assumption and continues instead.

Concepts

How the three packages fit

task ──▶ model-router ──▶ routes, best first ──▶ hcn run <harness> --model <id> --effort <level>
              ▲                                              │
              │                                              └─ retryable failure: next route
       model-registry

Together, the three packages route each job to a model and harness automatically, following your preferences. model-registry defines the registry file: the models you can use, the harnesses that reach them, and ratings for each. model-router reads the registry, takes a task, and returns routes ranked best first. Each route is a harness, a model, and an effort. hcn runs the route. If the run fails with retryable: true, run the next route. popeye is a harness built for hcn to drive, and a registry can list routes through it like any other harness. Each package also works on its own. hcn runs any harness and model you give it, and model-router ranks routes without running anything.

Refusal and divergence

If you pass an option the harness cannot express, hcn exits 2 without starting the harness and lists the harnesses that support the option. If the option comes from hcn's defaults instead of from you, hcn prints a divergence: line to stderr, and the harness uses its own default.

Reference

Commands

hcn run <harness> [prompt]     Run one headless turn
hcn session <harness>          Keep one process open across turns (--json for programs)
hcn interactive <harness>      Resume a native session in your terminal, with a control pipe
hcn inspect <harness>          Preview argv, capabilities, runtime, context, or saved settings
hcn transcript ls              List saved native sessions, newest first
hcn transcript read <harness>  Export one saved session as JSONL
hcn ls                         List harnesses and the CLI version each was verified against
hcn check                      Compare those versions with the latest releases

<harness> is one of claude, codex, pi, muse, cursor, antigravity (binary agy), popeye, or opencode. Cursor runs through the Cursor SDK in a worker process, not the native agent binary, which remains available for historical native terminal operations and CLI version inspection. hcn <command> --help lists every flag.

Session send and answer commands accept delivery: "queue" or "steer" where supported. The session controls reference covers per-harness support and the interrupt request and confirmation receipts.

Exit codes

Code Meaning
0 The turn finished, including a turn that ends with a question
1 The harness or the transport failed; done.failure says why
2 Usage error or refusal; the harness did not start
4 A bug in hcn; a --json stream still ends with failure and done

Config

hcn takes each setting from the first source that sets it:

flags > .hcn/config.json (git root) > ~/.config/hcn/config.json > hcn defaults > harness default
{ "version": 1, "effort": "high", "access": "read", "toolsets": { "review": ["read", "grep"] } }

Keys: effort, model, provider, sandbox, contextWindow, tools, excludeTools, autonomy, write, shell, memory, maxSteps, toolsets, timeout, questions, systemPrompt, appendSystemPrompt, toolMap, and access.

The user config also accepts claudeConfigDir, an absolute path for Claude's launch context. Inherited CLAUDE_CONFIG_DIR and per-run --env choices take precedence. See configuration and account context.

hcn's defaults are effort medium, autonomy off, memory off, and discovery on. Codex and Antigravity CLI also get sandbox workspace-write, and Codex and popeye get a 272,000-token context window. In a project config, tools also caps what --tools can grant, and a request for more exits 2. An unknown key or invalid JSON exits 2 with the problem in the message.

Security

  • hcn stores no credentials. Each harness signs in with your own account.
  • hcn masks secret-like strings from harness stderr in failure messages: sk- keys and token=, key=, secret=, and password= pairs.
  • Each invocation appends a start line and an end line to hcn/commands.jsonl under $HCN_STATE_DIR, $XDG_STATE_HOME, or ~/.local/state.
  • If HCN_OBSERVER is set to an executable, hcn run sends its events to that program's stdin. See docs/observer.md. If it is not set, hcn sends nothing.

docs/reference.md has the full flag table, the tool names for each harness, the event and failure fields, the session protocol, and the native-session commands (terminal resume, Codex approvals, and saved settings).

Contributing

You need Node 24 or newer, pnpm, and Bun.

pnpm install
pnpm setup:hooks           # once, from the primary checkout root: installs the Git hooks
pnpm check                 # full verification, including hook readiness and placement
bun run demo claude "hi"   # run a harness and print its event stream

Do not break the layer rules that test/interpretation/purity.test.ts and test/no-chat-imports.test.ts enforce, and do not edit test/fixtures/. Commits follow Conventional Commits. See CONTRIBUTING.md for the rest, and docs/harness-updates.md for how to verify a harness against a new CLI version.

Status

hcn is pre-1.0. It is not a harness and does not run a model itself. It adds a layer between your program and the harness, so if you use only one CLI, you may prefer to call that CLI directly. ROADMAP.md lists planned work, including new harnesses. Support differs by harness:

  • Sessions work with Claude Code, Codex, pi, Cursor, Antigravity CLI, and popeye. Muse and OpenCode CLI run single turns only. Cursor sessions run at the SDK's native defaults (writable tools, no sandbox): the session surface takes no access options, and --resume-last refuses on Cursor because the SDK has no most-recent-conversation path.
  • hcn interactive supports Codex only.
  • --native-approvals supports Codex one-shot responses and Claude and pi sessions. Saved-settings inspection supports Codex and pi.
  • The weekly version check in CI covers the harnesses published to npm. Muse, Cursor CLI, and Antigravity CLI are checked locally with their own version commands.

Thanks

hcn runs these CLIs: Claude Code, Codex, pi, Muse (installed from source, not on a registry), Cursor through the Cursor TypeScript SDK (the native CLI, installed via script as binary agent, is no longer run headless and is not on a registry), Antigravity CLI, popeye, and OpenCode CLI.

License

MIT. See LICENSE.

About

No description, website, or topics provided.

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages