NAME¶

hax - minimalist terminal-native coding agent

SYNOPSIS¶

hax [options] [prompt...]
hax {-p|--json} [options] [prompt]
hax {-c|--resume[=ID]} [options] [prompt]

DESCRIPTION¶

hax is a single small binary that acts as a coding agent in the terminal. It talks to OpenAI, Anthropic, OpenRouter and compatible providers, to a ChatGPT/codex account, or to local models through llama.cpp and ollama. Unlike a web chat it runs in the native terminal scrollback, keeps the working directory as the unit of context, reads and edits files, and runs commands as a subprocess.

It extends through configuration, markdown files and subprocesses rather than a plugin runtime. There are no MCP marketplaces, no IDE panels, and no per-command permission prompts.

With no arguments hax starts an interactive REPL. In one-shot mode the final answer goes to standard output, while the provider banner, usage statistics, errors and the resume hint go to standard error, so hax -p is safe to pipe without losing diagnostics.

hax is not a security boundary. It executes shell commands on the model's behalf without per-command approval. Use operating-system-level isolation for untrusted work.

OPTIONS¶

-p, --print

Run non-interactively to completion and print the final assistant message to standard output. The prompt is taken from the positional arguments, joined with spaces, or from standard input when no argument is given and standard input is not a terminal.

--json

One-shot mode that implies -p, writing the run's session records to standard output as JSON Lines, one record per line, closed by a result record carrying the outcome, final text, usage and session id. The standard error banner and statistics are omitted; errors and warnings still go there.

-c, --continue

Resume the most recent conversation recorded for the current directory.

--resume[=ID]

Resume a past conversation in the current directory, restoring the provider, model, effort and preset it last used. Without an argument a picker is shown, which requires a terminal; with an id, or a unique prefix of one, the run continues without prompting. A command line selection flag overrides the restored choice and is recorded in the resumed session.

--no-session

Do not record this conversation. Nothing is left to resume afterwards, and prompts are not added to the Ctrl-R recall. Earlier sessions and prompts stay readable.

--raw

Send only the prompt text: no base system prompt, no environment section, no AGENTS.md, no skills and no tools. Useful as a barebones chat interface.

--bare

Run without project and delegation context: no AGENTS.md, no skills, no subagent section. The environment section, the tools and the base system prompt remain, unlike --raw.

--provider=NAME

Select the backend for this run. One of codex, openai, anthropic, openrouter, opencode-zen, opencode-go, llamacpp, ollama, or a provider defined in the configuration file.

--model=ID

Select the model for this run.

--effort=LEVEL

Select the reasoning effort for this run, where the provider supports it.

--preset=NAME

Apply the named preset, a presets.NAME selection from the configuration file. A preset is applied first and explicit provider, model and effort flags are layered over it.

-h, --help

Show usage information and exit.

-v, --version

Show the version and exit.

The four selection flags apply to the current process only, are not persisted, and take priority over every other source. Settings are resolved in this order, first defined value winning:

INTERACTIVE COMMANDS¶

Type /help inside the REPL for the authoritative live list.

/new [preset]

Start a fresh conversation, optionally with a preset. /clear is an alias.

/resume

Pick a past session for this directory.

/fork [n]

Create a new session branching before an earlier prompt. /fork 0 clones the current tip. Prefer it over /undo when trying an alternative, since the original session stays intact.

/undo [n]

Permanently truncate this session before an earlier prompt. It rewrites both the conversation memory and the session file, and has no redo.

/provider

Choose a provider, model and effort.

/model

Choose a model and effort for the current provider.

/effort

Choose the reasoning effort, where supported.

/preset [name]

Apply a configuration-defined preset.

/preset-save name [tint]

Save the current provider, model and effort as a preset.

/config [key [value]]

Show the resolved value, source and description of each setting, or set one for this process. Provider, model, effort and preset have their own commands, and API keys are only ever reported as set or unset.

/compact [focus]

Summarize older context, optionally emphasising something the summary must preserve.

/copy

Copy the most recent assistant response.

/tasks [kill id... | kill all ]

List background tasks, or stop them.

/session

Show the current session and local usage totals.

/usage

Query provider account or subscription usage, where supported.

/login [provider]

Log in to a provider account with a hax-managed token, for ChatGPT/codex.

/logout [provider]

Revoke and remove a hax-managed login.

KEYS¶

Enter

Submit. At a paused, empty prompt, continue without adding a message. Shift-Enter inserts a newline when the terminal sends LF for it.

Up, Down

Recall the previous or next prompt. Ctrl-R searches the persistent prompt history.

Esc

Pause after the current step so the conversation can be steered. Esc twice interrupts the model or a running tool immediately.

Ctrl-C

Clear the current prompt; twice on an empty prompt quits. Ctrl-D quits on an empty prompt.

Ctrl-L

Clear the screen and redraw the prompt.

Ctrl-G

Edit the prompt in $EDITOR.

Ctrl-O

Open the rendered conversation in $PAGER. This is the best view for reviewing what happened.

Ctrl-T

Open the model-facing transcript in $PAGER: the system prompt, tool schemas, tool calls and results, and post-compaction context.

Ctrl-V

Paste a clipboard image, or clipboard text when no image is available.

@ + Tab

Choose a project file with fzf(1) and insert its path. The model reads the file only if it needs to.

CONFIGURATION¶

Configuration is optional: the interactive pickers work without a file and remember provider and model choices. See config.json below for the settings reference.

PROVIDERS¶

codex

Run /login inside hax.

openai

Set OPENAI_API_KEY.

anthropic

Set ANTHROPIC_API_KEY.

openrouter

Set OPENROUTER_API_KEY.

opencode-zen, opencode-go

Set OPENCODE_API_KEY.

llamacpp

Run llama-server.

ollama

Run ollama serve.

Any OpenAI-compatible endpoint can be added as a custom provider through the providers block of config.json.

EXIT STATUS¶

0

The run finished.

1

The run failed.

130

A one-shot run was interrupted by SIGINT or SIGTERM. Completed work is saved and the session stays resumable. A second signal kills the process.

In one-shot mode SIGUSR1 pauses cleanly at the next turn boundary instead, and reports the outcome as paused.

EXAMPLES¶

Start a conversation in the current repository:

hax

Run a single task and capture only the answer:

answer=$(hax -p "summarize the public API")

Keep diagnostics out of the captured result:

hax -p "produce JSON only" >result.json 2>run.log

Observe a run as it happens:

hax --json "fix the failing test" | jq 'select(.kind == "tool_call" or .type == "result")'

Continue yesterday's conversation here, on a different model:

hax --resume --model=other-model

Ask a plain model question with no tools and no project context:

hax -p --raw "explain this error message"

SEE ALSO¶

git(1), fzf(1), less(1), ollama(1)

The full manual ships alongside the binary as README.md, CHANGELOG.md and the docs directory, including configuration.md, providers.md, sessions.md and usage.md.

Project homepage: https://usehax.dev

AUTHOR¶

Oleksandr Chekhovskyi and contributors.