Documentation

Learn how to install, configure, extend, and operate xal.

Installation and beta releases
The installer downloads the latest beta as one native executable, verifies its SHA-256 checksum, and places it in ~/.local/bin.
Configuration
Configure Xal globally for your user or locally for one project. This page explains configuration files, merge behavior, and the top-level schema. Follow the links in the option table for detailed behavior and examples.
TUI
Customize Xal's terminal interface, keyboard shortcuts, transcript details, and terminal notifications.
Permissions and security
Control which tools can run, define permission modes, and prevent sensitive values from reaching models or stored output.
Providers and models
Connect a built-in or plugin-provided model service, select a model, and configure provider-specific behavior.
Integrations
Connect Xal to local usage dashboards, language servers for semantic code intelligence, and MCP servers for external tools, resources, and prompts.
Xal public website API
The Xal website publishes a small, public REST API for agents and developer tooling that need canonical product metadata. It is separate from the local coding harness and does not provide remote access to a user's terminal, files, sessions, plugins, or configured AI providers.
Plugins and hooks
Extend Xal with trusted in-process plugins that can register tools, providers, UIs, commands, and lifecycle hooks.
Commands and skills
Reuse common instructions through project guidance, lightweight Markdown prompt commands, or richer skill packages that the model loads on demand.
Goals
Use goal automation when Xal should keep working until it can prove one measurable completion condition.
Scheduler
The built-in scheduler tool waits for a model-selected duration. When the wait completes, the tool returns to the same turn and the model receives another inference opportunity with the elapsed wall-clock time.
Background work
Background work comes in two vocabularies. A background session is a whole session that keeps working after you leave the terminal: /bg hands the running conversation to a detached worker process and returns you to the shell. Background jobs are work inside a live session: task agents dispatched with the task tool, processes started with bash background:true, and waits started by scheduler. Jobs are tracked per session and share one set of TUI surfaces. Agent and process results are delivered into the conversation automatically; a schedule resumes its waiting model turn directly.
Built-in tools
Xal registers its built-in tools at startup, but the model is only offered the ones that apply to the current session. Availability is evaluated on every provider request from the session kind, whether the session is interactive, and the active permission mode. A tool that is registered but unavailable is not silently unknown: if the model calls one anyway, the call fails with a message naming the session state rather than reporting an unknown tool.