Skip to content

helix chat

Run an agent from a YAML file in an interactive terminal REPL with streaming, tool-call indicators, session persistence, and a small set of slash commands. The transport is readline — arrow-key history, in-line editing, and a persistent history file. This is the fastest way to drive an agent from your shell without standing up an HTTP endpoint.

Usage

helix chat <file.yaml> [--agent <id>] [--dir <path>] [--session-dir <path>] [--no-session]

Flags

Flag Default Description
--agent ID first agent in file Pick which agent to chat with when the file defines several.
--dir PATH, -C PATH cwd Set the agent's working directory. Filesystem tools are locked to it and os.Chdir is called.
--session-dir PATH ~/.helix/sessions/ Where to persist conversation transcripts.
--no-session off Don't load or save the conversation.

Slash commands (inside the REPL)

Command Action
/help Show the command list.
/tools List the agent's tools with descriptions.
/session Show the session file, message count, approximate token count.
/clear Clear conversation history + delete the session file.
/exit, /quit, exit, quit Save session and exit. Ctrl+C / Ctrl+D do the same.

Behavior notes

  • Requires $HELIX_LICENSE. Verified at process start.
  • The file is parsed with dsl.ParseYAMLFull after os.ExpandEnv — ${VAR} references work without explicit interpolation.
  • Agent resolution: looks at every step in every workflow for the first agent: step. If --agent <id> is given, the matching agent.ID must equal it.
  • Memory defaults to SmartMemory(100000) if the agent has no memory: block. The agent's declared memory type wins when set (smart, sliding-window, token-window, etc.).
  • Tools are built from the agent's tools: list. Three sources are resolved: MCP tools via dsl.BuildMCPTools, built-in functions via the global builtin registry, and explicit type: function tools.
  • Session persistence: the session file key is <agent_id>_<basename of cwd>.json. Loading restores the message history into the agent's memory and prints Restored N messages from previous session. Saving runs on every reply, on /exit, and on Ctrl+C.
  • Tool calls render as ⚡ <tool> <arg> with a one-line preview; tool results render as ✓ <tool> → N lines, B bytes (truncated forms for short or errored results). The display gives you a step-by-step trace without leaving the REPL.
  • Streaming: RunStream returns a *llm.StreamReader; chunks are printed as they arrive, with an elapsed-time footer.

Examples

Pick the only agent in the file:

helix chat app.yaml

Pick one by ID, run from a project root:

helix chat app.yaml --agent rag-agent --dir ./my-project

Ephemeral session (no persistence):

helix chat app.yaml --no-session

Drop the saved session and start fresh:

helix chat app.yaml
# > /clear

Source

cmd/helix/chat.go lines 48-137 (cmdChat), 139-261 (buildAgentFromDef), 279-464 (runChatREPL), 474-504 (session persistence).

See also