Extending Luxe

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.