REPL

Run hlvm with no command to start the interactive shell.

hlvm

The shell starts in the current directory. Start it elsewhere with the same workspace convention as Codex:

hlvm -C ~/dev/my-project
hlvm --cd ~/dev/my-project
hlvm --global

--global is the explicit Siri-like assistant mode. It is distinct in the public API from selecting a directory, even though the core represents its filesystem reach from the root.

The REPL routes input by shape:

Input	Route
`(expression)`	HQL evaluation
`(js "code")`	JavaScript evaluation
`/command`	REPL command
Anything else	AI conversation

Working Directory

The footer shows the active working directory. Change it without restarting the REPL:

/path                 # Show current scope
/path ../other-repo   # Resolve from the current scope, then switch
/path ~/dev/project   # Switch with an absolute/home-relative path
/path --global        # Return to global-assistant scope

The change applies to future HQL evaluation, @file completion, attachments, and agent turns. An already-running turn keeps the directory it started with. Changing scope does not call process-wide chdir, so the design can support different scopes for different agents.

HQL Evaluation

hlvm> (+ 1 2)
3
hlvm> (map inc [1 2 3])
(2 3 4)

AI Conversation

hlvm> explain this directory structure

The REPL keeps conversation context. Use hlvm ask --stateless for isolated one-shot runs.

Permissions And Planning

Shift+Tab cycles the three persistent permission presets: Ask, Auto, and Full access. /permissions opens the same three-state picker and updates the same core config value. /permission remains a hidden compatibility alias.

/plan independently enters or leaves plan mode and restores the prior permission preset on exit. Plan and read-only are workflow constraints, not additional permission levels, so they never appear in the Shift+Tab cycle.

Core owns the preset IDs, labels, descriptions, order, and default in one versioned permission catalog. Other clients, including HLVM for macOS, render the catalog returned by /api/config; they do not maintain a second list.

Developer Options

hlvm --debug
hlvm --no-banner
hlvm --port 18442

--debug is the canonical REPL debug switch. Use hlvm --debug for direct REPL repros and make repl REPL_ARGS=--debug for rebuilt local REPL repros. It shows internal trace rows and writes per-prompt debug evidence to:

~/.hlvm/repl-main-thread-trace.jsonl
~/.hlvm/repl-agent-wire-debug.jsonl

Product behavior must not depend on these files. If this debug surface is no longer useful, remove the CLI flag, trace wiring, tests, and this REPL doc entry together.