Files
luxe/docs/guide/recipes.md
Evan Whittaker a0666d6c81 luxe 0.1.4: remembered models, wheel-driven lists, and a steadier phone app
- luxe starts on the model you last chose in this project, then the last one anywhere. Signing in
  opens the model picker instead of choosing for you.
- Every list in a modal takes the mouse wheel and a draggable scrollbar.
- The phone app shows reasoning in full, stays put while you read back through a long session, and
  shows a question's answer on its card.
- On Windows, luxe update replaces the running luxe, and a signed-in install no longer sees setup
  again.
- The file tree no longer shows "engine busy" in a large project, loop output is easier to follow,
  and the name is written lowercase.

The CHANGELOG has the full list.
2026-10-20 13:51:34 -05:00

327 lines
12 KiB
Markdown

---
title: "Recipes"
summary: "Extensions put together: Asana, subagents, a classifier guard, Herdr, your phone, and a local model."
order: 8
group: "Extend"
---
## Asana
Two ways to bring Asana in, and they work together: its MCP server, so the agent can read and update
tasks, and a mention source, so you can point at one task with `@`.
### The MCP server
Asana registers each app, so each person makes one of their own.
1. **Register an MCP app** in Asana's developer console (**My apps**). Set its redirect URL to
`http://127.0.0.1:8765/callback`, and leave **This is a native or command-line app** unchecked.
Share it with your workspace. Your organization may need an admin to approve it.
2. **Keep the secret in your environment.** In `~/.zshrc` or `~/.bashrc`, then open a new
terminal:
```bash
export ASANA_MCP_CLIENT_SECRET='…'
```
3. **Add the server**, with your app's client ID, and hide the tools Asana marks as internal:
```json title="~/.config/luxe/mcp.json"
{
"mcpServers": {
"asana": {
"url": "https://mcp.asana.com/v2/mcp",
"auth": {
"kind": "oauth",
"client_id": "1209…",
"client_secret": "${ASANA_MCP_CLIENT_SECRET}",
"redirect_uri": "http://127.0.0.1:8765/callback"
},
"exclude_tools": [
"get_project_internal", "search_objects_internal", "log_widget_event",
"create_task_confirm", "save_task_changes_confirm", "create_project_confirm",
"create_project_confirm_populate", "save_project_changes_confirm"
]
}
}
}
```
4. **Sign in** and check what you can use:
```bash
luxe mcp login --id asana
luxe mcp tools
```
5. **Decide what the agent may do.** Task names and comments go to your model provider when a tool
returns them. To let reads through and ask before anything changes:
```json title="~/.config/luxe/permissions.json"
{
"permission": {
"mcp": {
"asana/create_*": "ask",
"asana/update_*": "ask",
"asana/delete_*": "ask",
"asana/add_*": "ask"
}
}
}
```
If Asana's data may only go to a provider your organization approves, use
`"asana/*": "deny"` until you are on one. In a headless or loop run, make the writes `deny`:
nobody is there to answer an `ask`.
6. **Use it:** *@[mcp:asana] what is due this week?*
### Your tasks in the `@` picker
This needs a personal access token (**My apps → Personal access tokens**), since the MCP sign-in's
token works only for the MCP server. Your workspace's ID is in
`https://app.asana.com/api/1.0/workspaces`, read with the same token.
```bash title="~/bin/asana-mentions"
#!/bin/sh
curl -sSf -H "Authorization: Bearer $ASANA_PAT" -G https://app.asana.com/api/1.0/tasks \
--data-urlencode assignee=me --data-urlencode "workspace=$ASANA_WORKSPACE" \
--data-urlencode completed_since=now --data-urlencode limit=100 \
--data-urlencode opt_fields=name,due_on,permalink_url |
jq -c '.data[] | (if .due_on then "due \(.due_on)" else "no due date" end) as $due | {
id: .gid,
label: .name,
detail: $due,
text: "Asana task \"\(.name)\" (\($due)) \(.permalink_url)"
}'
```
```json title="~/.config/luxe/config.json"
{ "mentions": [{ "name": "Asana", "command": "asana-mentions" }] }
```
A task you pick goes in as `@[asana:1209…]` and reaches the agent as its name, due date and link,
and the agent can look it up through the MCP server. See [Mention sources](mention-sources.md).
## Subagents
A subagent is a separate context that does one job and returns a summary, which is what a headless
luxe run is:
```bash
luxe --headless --read-only --model openai/gpt-5.6 --format json \
-p "review src/parser.rs for edge cases" |
jq -rs 'map(select(.type == "message" and .text != "")) | last.text'
```
`--read-only` keeps the subagent from changing anything, and `--model` lets it be a different model
from the one doing the work. The `jq` filter keeps the last message with text in it, which is the
summary. For a review of your own uncommitted work, [`/review`](agent.md#a-second-opinion) does
this without the wrapper.
To let the agent start one itself, wrap that command in an MCP server with a
`delegate(task, model)` tool. Then:
- Rule it like any tool: `"mcp": { "delegate/*": "ask" }` in `permissions.json` puts each one in
front of you.
- Give the server a `timeout_secs` longer than a review takes. A call gets 60 seconds by default,
and one that runs out stops the subagent.
- Return the subagent's stderr when it fails, so the agent sees why.
- Give a subagent that writes its own worktree, with `git worktree add`, so it stays out of yours.
luxe refuses to nest more than two levels deep, since an agent that starts two subagents per turn
would multiply fast. `LUXE_MAX_DEPTH` raises the limit.
## A guard that asks a model
A `BeforeToolUse` [hook](hooks.md) can ask a small classifier model whether a command is
destructive, and ask you when it might be. This one calls a typed decision model running on your
own machine, and the request follows that model's API; any model that returns a probability works.
```bash title="~/.config/luxe/hooks/risk-gate.sh"
#!/usr/bin/env bash
set -euo pipefail
command=$(jq -r '.ToolUse.args.command')
risk=$(jq -n --arg c "$command" '{
state: { command: $c },
questions: { destructive: { type: "noul",
instructions: "Would running this command cause irreversible data loss?" } }
}' |
curl -sS --max-time 2 "${DECISION_URL:-http://localhost:8000}/v1/systemone" \
-H 'Content-Type: application/json' --data @- |
jq -r '.answers.destructive.noul')
if awk "BEGIN{exit !($risk > 0.8)}"; then
jq -n --arg r "scored $risk for irreversible data loss" '{decision:"ask", reason:$r}'
else
echo '{"decision":"allow"}'
fi
```
```json title="~/.config/luxe/hooks.json"
{
"BeforeToolUse": [
{
"matcher": "bash",
"command": ["/home/you/.config/luxe/hooks/risk-gate.sh"],
"timeout_ms": 2500,
"on_timeout": "ask"
}
]
}
```
- **It asks rather than blocks.** A hook can only make a call harder, so the worst a wrong answer
costs is a prompt.
- **It adds to your rules, not replaces them.** Keep what must always hold in
[`permissions.json`](security.md).
- **It runs before every matching call.** The `matcher` keeps it off `read` and `grep`; narrow it
further, such as `{ "bash": "rm *" }`, to cost less.
- **`on_timeout: "ask"`** puts the question to you if the classifier is down.
- **Nobody answers in a headless run**, so its `ask` is allowed there. Use `--on-ask deny`, or
`"hook_ask": "deny"` in `permissions.json`, to make it hold.
## Run luxe in Herdr
[Herdr](https://herdr.dev) keeps coding agents in panes and shows which ones are working, waiting
on you, or done. luxe reports its state to Herdr on its own when it runs in a Herdr pane:
**working** during a turn, **blocked** when it needs you, and **done** when the turn ends.
```bash
curl -fsSL https://herdr.dev/install.sh | sh
herdr
luxe # in a pane
```
To let the agent drive Herdr, such as splitting panes or starting other agents, add Herdr's skill:
```bash
mkdir -p ~/.config/luxe/skills/herdr
curl -fsSL https://raw.githubusercontent.com/ogulcancelik/herdr/master/SKILL.md \
-o ~/.config/luxe/skills/herdr/SKILL.md
```
`LUXE_HERDR=0` or `{ "herdr": false }` in luxe's config turns the reporting off.
### luxe colors in Herdr
Herdr has no theme files — it takes a built-in theme plus per-token overrides. This is luxe's
own palette in those tokens, so the pane and the multiplexer around it read as one program:
```toml title="~/.config/herdr/config.toml"
[theme]
name = "vesper" # the closest built-in; every token below is overridden anyway
[theme.custom]
accent = "#ddc084" # champagne, the one color luxe leads with
text = "#e4dfd6"
subtext0 = "#97938c"
overlay0 = "#4d4a45"
overlay1 = "#97938c"
sidebar_bg = "#12100e" # the base surface, same as luxe's background
panel_bg = "#12100e" # the tab bar sits on it too, so the chrome is one field
surface0 = "#201e1a"
surface1 = "#2e2b27"
surface_dim = "#201e1a"
active_row_bg = "#201e1a" # the current space, at rest
selection_bg = "#2e2b27" # the Navigate cursor, which should be the brighter of the two
mauve = "#d2a5cd" # branch names
yellow = "#ddc084" # working — an agent at work glows in the accent
green = "#81caa0" # idle / done
red = "#e68485" # blocked, needs you
peach = "#faaa51" # interrupted
blue = "#85c7d7" # luxe has one cool hue, so blue and teal share it
teal = "#85c7d7"
[ui]
accent = "#ddc084" # borders and navigation chrome, which read off their own key
```
Reload it in place with `prefix+shift+r`, or `herdr server reload-config`. For any of the other
[themes](appearance.md) luxe ships, the hexes are in its theme file and the token names above do
not change.
The one token worth a second thought is `panel_bg`: Herdr draws the active tab as `panel_bg` text
on an `accent` fill, so it has to stay dark enough to read there. Lifting it to `#201e1a` gives the
tab bar a surface of its own if you prefer the chrome delineated.
## luxe from your phone
Your sessions keep running on your computer, and your phone or tablet reaches them over
[Tailscale](https://tailscale.com), a private network between your own devices. Nothing is opened to
the internet. This is the terminal over SSH; [luxe on your phone](remote.md) is luxe's own way in.
1. Install Tailscale on the computer and on the phone, and sign in to the same account on both.
2. On the computer, turn on SSH. On Linux and macOS, Tailscale can do it for you:
```bash
sudo tailscale up --ssh
```
On Windows, turn on the OpenSSH Server in Settings, under Optional features.
3. Run luxe in [Herdr](#run-luxe-in-herdr), so your sessions outlive the terminal you started
them in.
4. On the phone, connect with an SSH app such as Blink Shell or Termius, using the computer's
Tailscale name, and run `herdr`. It attaches to the panes you left, with luxe where it was.
```bash
mosh you@desk -- herdr
```
[Mosh](https://mosh.org) keeps the connection through a locked screen or a switch from Wi-Fi to
cellular. It needs `mosh` installed on the computer too, which Linux and macOS have and Windows
does not; plain `ssh` works everywhere.
On an iPad with a keyboard, this is luxe as you know it. On a phone, luxe fits a narrow screen,
and Herdr marks which session is waiting on you.
### A notification when luxe needs you
[luxe on your phone](remote.md#notifications) has notifications built in. Without it, a
[hook](hooks.md) can post to [ntfy](https://ntfy.sh), whose app shows it on your phone:
```json title="~/.config/luxe/hooks.json"
{
"PermissionRequested": [
{ "command": ["curl", "-s", "-d", "luxe is waiting for an approval", "https://ntfy.sh/your-topic"] }
],
"BeforeToolUse": [
{ "matcher": "question", "command": ["curl", "-s", "-d", "luxe has a question", "https://ntfy.sh/your-topic"] }
],
"AgentEnd": [
{ "command": ["curl", "-s", "-d", "luxe finished", "https://ntfy.sh/your-topic"] }
]
}
```
- **Anyone who knows an ntfy.sh topic can read it**, so pick a long random name, or run ntfy
yourself on your Tailscale network. The messages above say only that something is waiting, never
the command.
- **`AgentEnd` fires after every turn**, at your desk too. Leave it out if that is too many.
## A local model in LM Studio
1. Load a model in LM Studio and start its server.
2. In luxe, open **Configuration** and choose **Connect a local or custom model**, then
**LM Studio**. Leave the endpoint blank for the default.
3. Choose the model in the picker that opens.
LM Studio ignores the chat-template settings luxe sends a local server by default, so for
thinking levels to reach the model, send them as `reasoning_effort`, and start each session at a
sensible level. Connecting already wrote an `lmstudio` provider to `models.json`, so add these keys
to it rather than replacing the file:
```json title="~/.config/luxe/models.json"
{
"providers": {
"lmstudio": { "compat": { "thinking_format": "openai" } }
},
"models": {
"lmstudio/qwen3.8-27b": { "reasoning": true, "thinking": "medium" }
}
}
```
[Custom providers](custom-providers.md) covers samplers and request formats.