No description
  • Go 93%
  • Python 6%
  • JavaScript 1%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-10-16 20:45:55 +09:00
.forgejo ci: separate native tool reference checks from portable release gate 2026-10-16 20:41:46 +09:00
cmd feat: time out stalled provider response waits 2026-10-15 18:45:34 +09:00
dist Move standard tools to QuickJS stdlib and isolate artifact modules 2026-10-16 14:17:44 +09:00
docs docs: record v1.0.0 CI release and downloaded artifact checks 2026-10-16 20:45:55 +09:00
examples/hooks Release hjh v1.0.0 with Forgejo CI packaging 2026-10-16 20:36:43 +09:00
internal Release hjh v1.0.0 with Forgejo CI packaging 2026-10-16 20:36:43 +09:00
scripts ci: separate native tool reference checks from portable release gate 2026-10-16 20:41:46 +09:00
spikes fix: preserve provider cache affinity per agent context 2026-10-16 00:05:22 +09:00
tmp Move standard tools to QuickJS stdlib and isolate artifact modules 2026-10-16 14:17:44 +09:00
.gitignore Move standard tools to QuickJS stdlib and isolate artifact modules 2026-10-16 14:17:44 +09:00
AGENTS.md Initialize hjh through I-05 with I-06 plan and S-06 spikes 2026-10-11 00:48:06 +09:00
go.mod feat: add async child control and improve TUI presentation 2026-10-12 15:57:01 +09:00
go.sum feat: add async child control and improve TUI presentation 2026-10-12 15:57:01 +09:00
LICENSE docs: add MIT license and clarify runtime and tested platforms 2026-10-13 11:10:25 +09:00
README.ja.md Release hjh v1.0.0 with Forgejo CI packaging 2026-10-16 20:36:43 +09:00
README.md Release hjh v1.0.0 with Forgejo CI packaging 2026-10-16 20:36:43 +09:00

henji-harness(hjh)

日本語

hjh is short for henji-harness. Henji (返事) means "reply" in Japanese.

A terminal AI agent for working with files, commands, and web sources. Use it interactively or from the command line, keep your session history, and delegate work to child agents.

Built in Go, hjh embeds go-quickjs, a pure Go implementation of QuickJS-NG, to run JavaScript tools, hooks, and run_js scripts. No Node.js or Deno installation is needed for JavaScript execution.

The build produces two executables, hjh and hjh-tui; runtime testing has been performed on Linux/amd64.

Features

  • Interactive TUI and command-line tasks, with resumable sessions.
  • OpenRouter, OpenCode Go, OpenAI API, and ChatGPT OAuth connections.
  • File and command tools, web fetching, and Exa web search.
  • Child agents with parallel execution, progress reports, and follow-up instructions.
  • Editable JavaScript tools and hooks, roles, workspace instructions, and skills.

Get started

Download the Linux/amd64 bundle and SHA256SUMS from Releases. Verify and extract the archive, then start the TUI:

sha256sum -c SHA256SUMS
tar -xzf hjh-linux-amd64.tar.gz
./hjh-linux-amd64/hjh-tui

The bundle includes both executables, editable extensions, and dependency licenses. Go is needed only when building from source.

Build from source with Go 1.27 or later; dependencies are listed in go.mod. Content search uses ripgrep (rg) when installed, otherwise GNU grep. Git inspection requires Git.

git clone https://forge.harakara.site/littleisland/hjh.git
cd hjh
go build -o dist/hjh ./cmd/hjh
go build -o dist/hjh-tui ./cmd/hjh-tui
./dist/hjh-tui

The TUI starts a local Core when needed and reuses an existing one. Keep hjh and hjh-tui in the same directory. Use ./dist/hjh-tui --continue to resume the latest session in the same workspace.

In the TUI, use /login to configure credentials, then /provider and /model to choose a connection and model. OpenRouter is the default connection. Press Enter to send a request while idle. During a run, Enter keeps the draft; F2 queues a follow-up and F3 sends steering. Type / to browse commands; use arrows to select, Tab to complete, and Enter to choose.

Command Action
/sessions /new /rename Open, start, or rename a session
/resume Resume a session by ID or latest, or attach to its running execution
/model /provider /effort Choose the model, connection, or reasoning effort for the next run
/login /auth Set up credentials or show authentication status
/roles /role List roles with their tools or choose the next role
/history /executions /inspect Review the conversation and saved executions
/inputs /tools /tool Review input receipt statuses and saved tool calls
/context Show context sources and usage
/recall Use a stopped execution’s records as reference for the next run
/detach Close the TUI while the Core keeps running
/quit Stop the Core and close the TUI
/help Show commands and keyboard shortcuts

Command line

After configuring credentials, run tasks and inspect their history:

./dist/hjh run "Summarize README.md" > summary.txt
./dist/hjh sessions
./dist/hjh run --session SESSION_ID "Continue the previous task"
./dist/hjh history --session SESSION_ID

The final answer goes to stdout; progress and session IDs go to stderr. Use --stream for incremental output. Flags go before the task text. Session IDs accept unique prefixes, normally eight characters.

To delete a saved session locally, stop the Core and any standalone runs first:

./dist/hjh core stop --connect http://127.0.0.1:8765
./dist/hjh sessions delete SESSION_ID

This removes the session, its execution history, and content and configuration records that are no longer referenced. Freed database space is reusable; the database file is not compacted automatically.

To run through an existing Core and open the same session in the TUI:

./dist/hjh run --connect http://127.0.0.1:8765 "Summarize README.md"
./dist/hjh-tui --session SESSION_ID

Use the session ID printed by run. The default Core endpoint is http://127.0.0.1:8765. Beyond run, history, and sessions, the CLI provides auth, models, providers, roles, inspect, and Core management with serve and core. Run ./dist/hjh --help for the full command and option list.

Configuration

Workspace configuration and editable tools live in .hjh/extensions/. Changes to tools, hooks, and role settings take effect on the next run. Generated JavaScript can use go-quickjs stdlib timers, fetch, and built-in modules; standard tool processing is implemented in editable JavaScript. Existing edited extensions need an explicit update—see the stdlib cutover guide. History is stored locally in .hjh/history.sqlite3. The TUI remembers your provider, model, and effort for new sessions in the same workspace, including after a restart. Favorite models are kept in ~/.local/state/hjh/model-favorites/, or $XDG_STATE_HOME/hjh/model-favorites/ when set.

Credentials are stored in ~/.config/hjh/credentials/ on Linux, or under $XDG_CONFIG_HOME/hjh/credentials/ when set. API keys stay outside workspace configuration and Git history.

To replace the built-in base instructions, create ~/.config/hjh/instructions/base.md on Linux (or $XDG_CONFIG_HOME/hjh/instructions/base.md). Role, tool, and workspace instructions are still combined with it. Edits take effect on the next run.

Add workspace instructions in AGENTS.md and skills in .hjh/skills/<name>/SKILL.md. Skill descriptions are loaded at run start; their full instructions are read when needed. Exa search can use EXA_API_KEY.

The English README is the source of truth; README.ja.md is its Japanese translation.

License

MIT. Third-party dependencies retain their own licenses.