`helix code`¶

Interactive coding-agent REPL for the current working directory. Unlike helix chat, no flow YAML is required: code constructs an agent in code (provider auto-detected from environment), wires the standard filesystem, shell, and Helix-specific tools, and launches a full-screen Bubble Tea TUI with streaming, tool indicators, markdown rendering, and per-tool approval prompts.

Usage¶

helix code [flags]

Flags¶

Flag	Default	Description
`--dir PATH`, `-C PATH`	cwd	Working directory. Filesystem tools are locked here; `os.Chdir` is called.
`--provider NAME`	auto	LLM provider (`anthropic`, `openai`, `xai`, `ollama`). Auto-detected from env if unset.
`--model NAME`	provider default	Model name. Defaults: `claude-sonnet-4-20250514`, `gpt-4o`, `grok-beta`, `llama3.1`.
`--prd PATH`, `--spec PATH`, `--attach PATH`	unset	Preload a requirements doc into the agent's context. Repeatable.
`--auto`, `--yolo`	off	Skip per-tool approval prompts (mutating tools run unattended).
`--no-sandbox`	off	Disable the Landlock filesystem sandbox for the shell tool (Linux only).
`--system-prompt-file PATH`	built-in	Replace the built-in system prompt with the file's contents.
`--session-dir PATH`	`~/.helix/sessions/`	Where to persist conversations and per-session log files.
`--no-session`	off	Don't load or save the conversation.
`--help`, `-h`	—	Print usage and exit.

Built-in tools¶

The agent is wired with two tool families:

Filesystem + shell: read_file, write_file, edit_file, list_dir, glob, grep, mkdir, shell. The shell tool is hard-blocked from a small list of catastrophic commands (rm -rf /, fork bombs, mkfs, etc.) and on Linux is wrapped in a Landlock sandbox that limits filesystem reads/writes to the workspace + toolchain caches unless --no-sandbox is set.
Helix-specific: helix_init, helix_schema, write_workflow, write_agent, write_test, write_pipeline, fix_starlang, write_rag_ingest, write_rag_retrieve, propose_architecture, track_requirements, check_env, write_env_template, write_app, helix_validate, helix_run, helix_test, helix_docs_search, helix_examples_search.

Behavior notes¶

Requires $HELIX_LICENSE. Verified at process start.
Provider auto-detection picks the first matching environment variable: ANTHROPIC_API_KEY → anthropic, OPENAI_API_KEY → openai, XAI_API_KEY → xai, OLLAMA_HOST → ollama. With no match it errors before launching the TUI.
Filesystem tools are allowed to read the Helix docs and examples corpora (if installed) so helix_docs_search and helix_examples_search can hand the agent paths it can read_file later.
Mutating tools (shell, write_file, edit_file, mkdir, helix_init) prompt for y/n/a approval unless --auto is set.
On Linux, the shell sandbox routes every command through helix __sandbox-exec which applies a Landlock confinement to the child. The parent process is not affected. Pass --no-sandbox to disable.
Memory: SmartMemory(200000). MaxIterations: 80 — coding sessions routinely take 25-60 turns when scaffolding a vertical slice.
Project memory: the first of CLAW.md, CLAUDE.md, AGENTS.md found in the working directory is injected into the system prompt (truncated at 12 000 chars), the same way Claude Code loads its CLAUDE.md.
The TUI takes over the alt screen. Agent internals are logged to <session-dir>/code_<workdir>.log so the display doesn't get scrambled; tail that file for the agent's internal debug stream.

Examples¶

Drop into a coding session for the current directory:

export ANTHROPIC_API_KEY=...
helix code

Different directory, explicit model:

helix code --dir ./customer-bot --provider openai --model gpt-4o

Drive a spec end-to-end without prompts:

helix code --prd ./requirements.md --auto

Disable the sandbox (e.g. on a non-Linux dev box):

helix code --no-sandbox

Source¶

cmd/helix/code.go lines 28-288 (cmdCode), 299-344 (pickCodingModel), 346-612 (codingSystemPrompt), cmd/helix/sandbox.go + sandbox_linux.go (the __sandbox-exec re-exec wrapper).

helix code¶