# Xal documentation

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

- [Installation and beta releases](https://xal.sh/docs/install/index.md): The installer downloads the latest beta as one native executable, verifies its SHA-256 checksum, and places it in `~/.local/bin`.
- [Configuration](https://xal.sh/docs/configs/index.md): 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](https://xal.sh/docs/tui/index.md): Customize Xal's terminal interface, keyboard shortcuts, transcript details, and terminal notifications.
- [Permissions and security](https://xal.sh/docs/permissions/index.md): Control which tools can run, define permission modes, and prevent sensitive values from reaching models or stored output.
- [Providers and models](https://xal.sh/docs/providers/index.md): Connect a built-in or plugin-provided model service, select a model, and configure provider-specific behavior.
- [Integrations](https://xal.sh/docs/integrations/index.md): 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](https://xal.sh/docs/api/index.md): 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](https://xal.sh/docs/plugins/index.md): Extend Xal with trusted in-process plugins that can register tools, providers, UIs, commands, and lifecycle hooks.
- [Commands and skills](https://xal.sh/docs/commands-and-skills/index.md): Reuse common instructions through project guidance, lightweight Markdown prompt commands, or richer skill packages that the model loads on demand.
- [Goals](https://xal.sh/docs/goals/index.md): Use goal automation when Xal should keep working until it can prove one measurable completion condition.
- [Scheduler](https://xal.sh/docs/scheduler/index.md): 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](https://xal.sh/docs/background-work/index.md): 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](https://xal.sh/docs/tools/index.md): 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.