Files
luxe/docs/guide/extending.md
Evan Whittaker 09a7de2520 Initial public release
Luxe 0.1.0: a coding agent harness for the terminal. See README.md to get started and CHANGELOG.md for releases.
2026-10-17 12:08:30 -05:00

5.3 KiB

title, summary, order, group
title summary order group
Extending Luxe Which kind of extension you need, how to install one, and what stays stable across updates. 1 Extend

Luxe extends through files and programs, never through code loaded into Luxe itself. A file carries instructions or settings; a program carries behavior, and runs with the same access you have. Installing an extension is copying a file.

Which one you need

To Use Runs
Change how Luxe looks, or which tools exist Configuration and themes Nothing
Teach the agent a procedure or house style Skills and AGENTS.md Nothing
Point the agent at your tracker or runbooks with @ Mention sources Your program, when its tab opens
Give the agent new tools An MCP server Your program, when the agent calls it
Block, rewrite, audit or react to what the agent does Hooks Your program, at points in a turn
Use an endpoint or model Luxe does not know Custom providers Nothing, or your !command for a key
Drive Luxe from your own program, or build a new front end: conversation, Guided Review and GitHub The RPC protocol Your program, driving Luxe
Open another terminal tool with a key Launchers Your program, on a key

The rows are in order of effort; the first that fits is usually right. Recipes puts several together: Asana in the @ picker, subagents, a classifier guard, running in Herdr, and a local model in LM Studio.

Where extensions live

~/.config/luxe/
├── config.json           settings, launchers, mention sources
├── keybindings.json      keys
├── models.json           endpoints and models
├── permissions.json      what the agent may do
├── agents.md             instructions for every project
├── skills/
│   └── <name>/           a skill
├── hooks.json            hooks
├── mcp.json              MCP servers
├── themes/
│   └── <name>.json       a theme
├── lsp-servers.json      language servers
└── debug-adapters.json   debug adapters

<project>/
├── .agents/skills/       skills committed with the repository
├── .mcp.json             MCP servers
└── .luxe/
    ├── config.json       settings, less what a project cannot change
    ├── keybindings.json
    ├── skills/
    │   └── <name>/
    ├── mcp.json
    ├── hooks.json        only with --trust-project
    └── permissions.json  can only tighten yours, unless --trust-project

What a project's config.json cannot change is listed in Configuration. On Windows, your own folder is %APPDATA%\luxe, and LUXE_CONFIG_DIR moves it anywhere. These paths do not change between releases.

.luxe/ writes its own .gitignore, which keeps everything in it out of Git except permissions.json, mcp.json, hooks.json and skills/. To share more with your team, such as the project's config.json, write that .gitignore yourself: Luxe rewrites its own copy, but leaves alone one it did not write.

Trust

A repository does not choose what runs on your machine. Its hooks and its loop gate.commands run only with --trust-project, and its permission rules can only make yours stricter. MCP servers, language servers and formatters it brings start, by default, only in an interactive session or with --trust-project; lsp.project_servers in your own config changes that, see Tools. This is about which programs Luxe starts. A language server itself may run project code, as rust-analyzer does with build.rs, so open an unfamiliar repository in Luxe the way you would build it.

A repository can still write instructions. Its AGENTS.md and skills reach the model. Luxe removes text a reviewer cannot see, but plain text is still instructions, so read an unfamiliar repository's AGENTS.md as you would its Makefile.

What stays stable across updates

Across updates
config.json, models.json, keybindings.json, lsp-servers.json, debug-adapters.json Only added to. An old file always loads. An unknown key is ignored, and no key changes meaning.
Sessions in .luxe/sessions/ A newer Luxe reads every older session. An older Luxe skips what it does not know in a newer one.
The RPC protocol Adding to it changes nothing. Removing or renaming anything changes protocol_version.
Hook points Added, never renamed. An unknown point skips that hook alone, with a warning in the log.
Tool arguments A renamed argument still accepts its old name.
Skills and AGENTS.md Plain markdown
The paths above Do not move

Before 1.0, a minor release may change the RPC protocol and the hook points, and its release notes will say so. Config files and sessions keep the stronger promise regardless, since they are the two you cannot regenerate.

What Luxe will not add

  • Plugins loaded into Luxe. A plugin would have all of Luxe's access, however it was sandboxed.
  • A network listener for RPC. It would turn a local program into a service that needs authentication.