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; typing / triggers command completion (with descriptions) |
@path |
typing @ triggers file-reference completion inside the working directory (@dir/ descends level by level); the completion produces ordinary text, which the agent interprets itself |
| Up/Down arrow keys | browse this session's input history, supporting search while typing |
\/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 stitches four groups of commands together: the 11 built-in commands of with_defaults(), the policy command group (registered with the default tool set), the 4 commands of with_fs_extra_defaults() that read and write the workspace, and the terminal-specific long and exit. Extensions also add their own commands (such as /skills, /mcp).
| 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); with an argument it is replaced by that content directly, for example /revise ask about B instead |
compact |
compact the session; compact toolcall only compacts old tool results |
config |
print the currently effective configuration as JSON; config key.sub=value edits one entry in place (for example /config model.temperature=0.2), changing only this in-memory configuration |
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 event stream cached by the display layer into a self-contained HTML file written to the given path; a missing .html suffix is appended automatically, and the path must stay inside the workspace |
handoff [filename] |
have the agent package the current task into a handoff zip (default handoff_<timestamp>.zip, with AGENT_HANDOFF_README.md at the root), so the work can continue with another person or session |
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.