xun · Terminal session¶

Talk to the agent in a REPL inside the current directory.

xun                                   # Interactive
xun "Write a hello world python script and save it to hello.py"
xun --non-interactive "one shot prompt"

Parameters¶

Parameter	Form	Default	Description
`instruction`	positional, optional	empty	first instruction; required in non-interactive mode
`--non-interactive`	flag	`False`	run a single turn and then exit instead of entering the REPL

Interactive mode is entered only when both stdin and stdout are TTYs and --non-interactive is not given; otherwise an instruction is required, and a missing one reports Instruction is required in non-interactive mode.. Pipes, redirection and CI environments all fall into the non-interactive branch automatically.

The corresponding Python API:

from xun import setup_agent, interactive_session

agent = setup_agent(default_tools=True, default_commands=True)   # initialize() has been called
interactive_session(agent, task="")

Input syntax¶

Input	Meaning
any text	sent as a user message (see the next row when it includes images)
`[image:cat.png image:https://example.com/dog.png] compare these two images`	attach images; every token must start with `image:`, a missing `]` raises `Invalid image syntax: missing closing ']'.` — it happens while the input is read, outside the loop's error handling, so the session exits. Only PNG/JPEG/WebP/GIF are accepted, at most 10 MB per resource, and a violation surfaces as an ordinary error
`/command arguments`	run a session command, see the table below
`\/not a command`	a leading `\/` marks an ordinary message, used to avoid the command prefix
Ctrl+C	cancel the current run: pops the last user message and prints `Execution interrupted by user.`

Any command accepts -h / --help for the long help, for example /policy -h.

Session commands¶

xun registers three kinds of commands: the built-in default commands, the policy command group (when the default tool set is used), and three commands specific to the terminal.

Command	Description
`help`	show the command list
`tokens`	show the number of tokens the session has used
`history`	show the message history
`clear`	clear the history (the system prompt is kept); `clear all` also removes the files in the temporary directory
`continue`	continue execution
`retry`	restart from the last user message and run it immediately
`revise`	go back to the last user message (edit it, then use `continue` to resume)
`compact`	compact the session; `compact toolcall` only compacts old tool results
`config`	print the currently effective configuration as JSON
`tools`	list the registered tools (including the model capabilities they require)
`extensions`	list discovered extensions with their status (`loaded` / `uninitialized` / `skipped` / `failed`)
`save`	save the current session history
`load latest` / `load 000003`	load the most recent history, or the one with the given number (the number is matched verbatim against the directory name, so it must be zero-padded to 6 digits)
`yolo`	toggle automatic confirmation (You Only Look Once)
`long [end marker]`	enter multi-line input mode, terminated by a lone `.` line by default
`render <path>`	render the session history to HTML and write it to the given file
`exit`	exit

policy: permission allowlists¶

Write operations and command execution are constrained by allowlists (see the tool system).

Subcommand	Description
`policy path_allowlist_add <path>`	allow writing to a file or directory
`policy path_allowlist_remove <path>`	remove a write allowlist entry
`policy path_allowlist`	list the write allowlist (directories end with `/`)
`policy cmd_allowlist_add <command>`	allow a command to run without confirmation
`policy cmd_allowlist_remove <command>`	remove a command allowlist entry
`policy cmd_allowlist`	list the command allowlist

History and persistence

save / load use Store; the on-disk path is {XUN_HOME}/conversation/{NNNNNN}.conversation/conversation.json, and load latest takes the directory with the highest number.