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.
This commit is contained in:
272
docs/guide/recipes.md
Normal file
272
docs/guide/recipes.md
Normal file
@@ -0,0 +1,272 @@
|
||||
---
|
||||
title: "Recipes"
|
||||
summary: "Extensions put together: Asana, subagents, a classifier guard, Herdr, 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.
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user