xx

small & fast

xx ships on mac and linux as a single <800K binary that starts instantly - perfect for pipelines or quickly launching sessions:

like other harnesses, -p runs and exits, printing agent output to stdout while tool calls go to stderr. --json is like -p but streams agent actions as json to stdout, tool calls to stderr.

xx only has five tools:

• bash: run shell commands in the container
• read: read a file entirely or a subset
• edit: replace specific text in a file
• write: create or replace a file
• docs: read a markdown doc in ~/.config/xx/docs/ or .xx/docs/

sandboxed

i once had an agent get confused and run rm -rf ~, so... yeah. xx runs every bash call in a long-lived linux container (via container on apple and podman on linux) which can only access specific paths on your host machine. by default it's ~/dev and ~/.rev, but you can change them or add more.

think of it as a safety net, not a security system: the goal is to prevent agents from accidentally running shell commands that impact your host system, not protection against rogue or malicious models.

you can run commands in the container from your host by using xx -x:

to run xx directly on your host computer, pass --jailbreak at startup. the prompt turns red so you don't forget:

to see information about the container, run /container:

hooks

hooks are executables in a directory ~/.config/xx/hooks/<event>/ or files named ~/.config/xx/hooks/<event> that run on the host in response to an agent event. write them in whatever language you want and update them without restarting xx. session info is passed to a hook via XX_ env variables.

for example, turn the tmux window yellow while the agent works:

#!/bin/sh
tmux set -t "$XX_TMUX" window-status-style bg=yellow

available hooks:

• start: xx started but hasn't done anything yet
• busy: agent is working
• idle: agent is not working
• cd: $ cd <path> changed the current working directory
• shutdown: any exit (ctrl-d, /quit, SIGHUP)
• heartbeat: triggers every five minutes on a long running task

session state:

• XX_EVENT: the hook name
• XX_TASK: (busy only) what the agent is doing: the prompt's first line or /compact
• XX_SESSION: the session's jsonl file
• XX_CWD: current working directory
• XX_PROVIDER: anthropic, openai, or openrouter
• XX_MODEL: model id in use
• XX_EFFORT: effort level (empty for the model's default)
• XX_THINKING: thinking mode (empty for the model's default)
• XX_CONTAINER: whether tools run in the container (true/false)
• XX_MODE: tui or print
• XX_TMUX: session:@window_id (empty outside tmux)

commands

slash commands either send markdown directly to the model or run a program and put its output in the scrollback, skipping the model. they live in ~/.config/xx/commands/ and can be edited without restarting xx:

above, review.md is a prompt command. /review the diff sends the file, then "the diff".

fork, set +x, is a program command. it runs on the host with the arguments you pass to the slash command and the XX_ env vars listed above in the hooks section. the output of fork goes directly into the scrollback, not the model.

to see all available slash commands, including the builtin ones, run /help:

$ shell commands

run a shell command in the container directly by typing $ on an empty line, then your command. typing $$ on an empty line locks you in "shell mode" where the input assumes shell commands until you ESC, ctrl-c, or backspace on an empty line. $ cd <path> will move xx's current working directory.

the shell commands you run and their output gets sent to the model with your next message:

xx.conf

override default settings with ~/.config/xx/xx.conf:

# claude* → anthropic, vendor/model → openrouter, anything else → openai
model claude-fable-5-1

# low | medium | high | max
effort high

# drop sessions idle longer than this (min, h, d, wk). 0 keeps forever
keep_sessions 30d

container {
  # you can switch between multiple containers
  # by using different names
  name xx

  # false runs tools on the host, like --jailbreak
  enabled true

  # use any image you want
  image alpine:latest

  # memory in MiB. 0 leaves it to the backend
  memory 8192
  cpus 0

  # host directories available in the container
  mounts ~/dev ~/.rev

  # install packages beyond the default set
  package jq
  package fd apk add --no-cache fd
  package honest curl -fsSL https://because.sh/honest | sh
}

you can also start xx with --model or --effort to override settings for a single session.

docs

docs are markdown files in ~/.config/xx/docs/ or .xx/docs/ explaining concepts. when xx starts, or when it runs the "docs" tool, it sees a list of available docs. running one enlightens it.

you can force xx to read a doc by sending /docs <name> or find out what's available with the /docs command.

besides the docs feature, xx (like all harnesses) sends ~/.config/xx/AGENTS.md and AGENTS.md (if they exist) with every request.

sessions

xx automatically tracks every transcript as an append-only jsonl file in ~/.config/xx/sessions. keyed by the current directory, they're deleted (by default) after 30 days.

you can continue the most recent session for the current directory or any session using -c. list them with -s:

provider-agnostic

xx works with anthropic, openai, or any anthropic/openai-compatible providers like openrouter. big whoop.

model format and env vars:

• claude-* → ANTHROPIC_API_KEY
• {vendor}/{model} → OPENROUTER_API_KEY
• anything else → OPENAI_API_KEY.

you can also point ANTHROPIC_BASE_URL, OPENAI_BASE_URL or OPENROUTER_BASE_URL at a proxy or local server

the /cost command hits the models.dev API to give you accurate pricing information for your model.

...and more

• queued input: type and hit enter while the agent is working to queue your message for when it finishes.
• multi-line input: use shift-enter to insert a new line
• $EDITOR support: hit ctrl-x when writing your prompt or launch xx with xx -e to edit in $EDITOR
• input history: use up/down or ctrl-p/ctrl-n to move through your prompt history, even across sessions
• /transcript: see exactly what was sent over the wire
• /status: see details about the current session
• auto-compaction: when your model's context window is 80% full, xx will compact the session history. run it at any time using /compact
• big pasta: big pastes collapse to one [paste #1: 40 lines] token
• tmux: xx knows when it's running inside tmux and renames the window to the project directory or rev change number
• capped tool output: tool output is capped at 60k chars to help keep things tight and right

get it

xx ships as a single binary for mac and linux:

curl -fsSL xx.sh | sh