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:
Evan Whittaker
2026-10-17 12:08:30 -05:00
commit 09a7de2520
1730 changed files with 412952 additions and 0 deletions

45
web/src/pages/404.astro Normal file
View File

@@ -0,0 +1,45 @@
---
import Base from "../layouts/Base.astro";
---
<Base title="Not found — Luxe" description="That page does not exist.">
<div class="page missing">
<p class="eyebrow">404</p>
<h1>Nothing here.</h1>
<p class="lede">
That page doesn't exist, or it moved.
</p>
<p>
The <a href="/docs">documentation</a> has a search box, and it covers every page of the guide.
If you followed a link from somewhere and it should have worked,
<a href="https://github.com/evanwhittaker/luxe/issues">say so</a> — a dead link is a bug like
any other.
</p>
<p class="missing__actions">
<a class="button" href="/">Home</a>
<a class="button button--quiet" href="/docs">Documentation</a>
</p>
</div>
</Base>
<style>
.missing {
padding-block: var(--space-8) var(--space-7);
max-width: var(--measure);
}
.missing h1 {
margin-bottom: var(--space-4);
}
.missing .lede {
margin-bottom: var(--space-4);
}
.missing__actions {
display: flex;
gap: var(--space-3);
margin-top: var(--space-5);
flex-wrap: wrap;
}
</style>

175
web/src/pages/brand.astro Normal file
View File

@@ -0,0 +1,175 @@
---
import Base from "../layouts/Base.astro";
import Wordmark from "../components/Wordmark.astro";
import wordmarkSvg from "../assets/generated/wordmark.svg?url";
import markSvg from "../assets/generated/mark.svg?url";
import tileSvg from "../assets/generated/tile.svg?url";
const files = [
{ href: wordmarkSvg, name: "wordmark.svg", note: "the logotype, one path per letter" },
{ href: markSvg, name: "mark.svg", note: "the L alone, cropped to its ink" },
{ href: tileSvg, name: "tile.svg", note: "the tile — favicons, avatars" },
];
---
<Base title="Brand — Luxe" description="The Luxe logotype, where it came from, and how to use it.">
<div class="page">
<section class="section section--head">
<p class="eyebrow">Brand</p>
<h1>One drawing.</h1>
<div class="prose">
<p>
The logotype is not a font and not a traced image. It's a grid of terminal cells — three
glyphs, the two half blocks and the full block — and those cells are the only copy that
exists. The vector on this page is generated from them.
</p>
<p>
Those three were chosen, not settled for. Every terminal with built-in box drawing
synthesizes that range against the cell box rather than scaling a font outline into it, so
the mark lands identically whether you have a patched font or the plainest monospace your
distribution shipped. An earlier version cut its corners with the Powerline triangles and
looked better on the terminals that draw those correctly — which is not all of them, and a
mark that needs a fallback is the wrong mark to open with. There is no setting for it:
one mark, everywhere, is the point.
</p>
</div>
</section>
<section class="section">
<div class="stage plate">
<div class="stage__inner">
<Wordmark shine class="stage__mark" />
</div>
</div>
<p class="muted stage__note">
The light crossing it is the same one the terminal draws: 1.6 seconds to cross, then five
seconds of rest. A shine that repeats promptly stops reading as light and starts reading as
a strobe.
</p>
</section>
<section class="section">
<h2>Files.</h2>
<ul class="files">
{
files.map(({ href, name, note }) => (
<li class="file">
<a class="file__link" href={href} download>
<code>{name}</code>
</a>
<span class="muted">{note}</span>
</li>
))
}
</ul>
<p class="muted">
Each letter takes its color from <code>--luxe-wordmark-1</code> through
<code>-4</code>, falling back to <code>currentColor</code>. Set them, or set nothing and let
it inherit.
</p>
</section>
<section class="section section--last">
<h2>Please, and please don't.</h2>
<div class="rules">
<div class="rule">
<p class="rule__head">Please</p>
<ul>
<li>Use the brass ramp, or one flat color, or <code>currentColor</code>.</li>
<li>Give it room — at least the height of the <code>l</code> on every side.</li>
<li>Use the tile where the wordmark would fall below about 100px wide.</li>
<li>Keep the full stop. It is part of the drawing, and it sets the tone.</li>
<li>Call it <b>Luxe</b> in prose and <code>luxe</code> in a command.</li>
</ul>
</div>
<div class="rule">
<p class="rule__head">Please don't</p>
<ul>
<li>Set it in a typeface. It is drawn on a cell grid; no font has these letterforms.</li>
<li>Add an outline, a shadow, or a gradient sweep of your own.</li>
<li>Stretch it. The 1:2.2 cell aspect is the proportion it is recognized at.</li>
<li>Capitalize it. The mark is <b>luxe.</b> and the product is <b>Luxe</b> — never LUXE.</li>
</ul>
</div>
</div>
</section>
</div>
</Base>
<style>
.section--head {
border-top: 0;
padding-top: var(--space-6);
}
.section--last {
border-bottom: 0;
}
.prose {
max-width: var(--measure);
margin-top: var(--space-4);
}
.stage__inner {
display: grid;
place-items: center;
padding: var(--space-7) var(--space-5);
}
.stage :global(.stage__mark) {
width: min(100%, 34rem);
}
.stage__note {
font-size: var(--step--1);
margin-top: var(--space-3);
max-width: var(--measure);
}
.files {
list-style: none;
padding: 0;
margin: var(--space-4) 0;
display: grid;
gap: var(--space-2);
}
.file {
display: flex;
align-items: baseline;
gap: var(--space-3);
flex-wrap: wrap;
font-size: var(--step--1);
padding-block: 0.5rem;
border-bottom: 1px solid var(--luxe-border-muted);
}
.file__link {
text-decoration: none;
}
.rules {
display: grid;
gap: var(--space-5);
grid-template-columns: repeat(auto-fit, minmax(20rem, 1fr));
margin-top: var(--space-4);
}
.rule__head {
font-family: var(--font-display);
font-size: var(--step-1);
color: var(--luxe-accent);
margin-bottom: var(--space-2);
}
.rule ul {
margin: 0;
padding-left: 1.1em;
font-size: var(--step--1);
color: var(--luxe-muted);
}
.rule li {
margin-bottom: var(--space-2);
}
</style>

View File

@@ -0,0 +1,297 @@
---
import { render } from "astro:content";
import Base from "../../layouts/Base.astro";
import DocsSearch from "../../components/DocsSearch.svelte";
import CopyMarkdown from "../../components/CopyMarkdown.svelte";
import { guidePages, grouped, pageHref, markdownHref } from "../../lib/guide";
import "../../styles/prose.css";
export async function getStaticPaths() {
const pages = await guidePages();
return pages.map((page, index) => ({
// The index page owns `/docs` itself, so its slug is empty rather than `/docs/index`.
params: { slug: page.id === "index" ? undefined : page.id },
props: {
page,
pages,
previous: pages[index - 1],
next: pages[index + 1],
},
}));
}
const { page, pages, previous, next } = Astro.props;
const { Content, headings } = await render(page);
const href = pageHref;
const sections = grouped(pages);
// Only H2s. A three-level table of contents on a page this size is a second sidebar.
const toc = headings.filter((heading) => heading.depth === 2);
---
<Base title={`${page.data.title} — Luxe`} description={page.data.summary}>
<div class="page docs">
<nav class="docs__nav" aria-label="Documentation">
<DocsSearch client:idle />
{/* Open, and closed by the script below on a phone, where the list would otherwise sit
between the reader and the page they opened. Without JavaScript it stays open. */}
<details class="docs__menu" open data-docs-menu>
<summary class="docs__menu-toggle">Contents</summary>
{
sections.map((section) => (
<section class="docs__group">
<p class="docs__group-name">{section.group}</p>
<ol class="docs__list">
{section.pages.map((entry) => (
<li>
<a
href={href(entry.id)}
class:list={["docs__link", { "is-current": entry.id === page.id }]}
aria-current={entry.id === page.id ? "page" : undefined}
>
{entry.data.title}
</a>
</li>
))}
</ol>
</section>
))
}
</details>
</nav>
<script>
const menu = document.querySelector<HTMLDetailsElement>("[data-docs-menu]");
if (menu && matchMedia("(max-width: 48rem)").matches) menu.open = false;
</script>
<article class="docs__body" data-pagefind-body>
<header class="docs__head">
<h1 class="docs__title">{page.data.title}</h1>
<p class="lede docs__summary">{page.data.summary}</p>
<CopyMarkdown client:idle href={markdownHref(page.id)} />
</header>
<div class="prose-body">
<Content />
</div>
<nav class="docs__pager" aria-label="Pagination">
{
previous ? (
<a class="pager pager--prev" href={href(previous.id)}>
<span class="pager__dir">Previous</span>
<span class="pager__title">{previous.data.title}</span>
</a>
) : (
<span />
)
}
{
next && (
<a class="pager pager--next" href={href(next.id)}>
<span class="pager__dir">Next</span>
<span class="pager__title">{next.data.title}</span>
</a>
)
}
</nav>
</article>
{
toc.length > 1 && (
<nav class="docs__toc" aria-label="On this page">
<p class="eyebrow">On this page</p>
<ol>
{toc.map((heading) => (
<li>
<a href={`#${heading.slug}`}>{heading.text}</a>
</li>
))}
</ol>
</nav>
)
}
</div>
</Base>
<style>
.docs {
display: grid;
gap: var(--space-5);
/* The middle track is capped rather than fluid. `--page` is set for the front page's two-column
sections, and a documentation column that grows to match it is 1200px of prose. */
grid-template-columns: 15rem minmax(0, 52rem) 13rem;
justify-content: center;
align-items: start;
padding-block: var(--space-5) var(--space-7);
}
.docs__nav,
.docs__toc {
position: sticky;
top: 5.5rem;
font-size: var(--step--1);
}
/* Taller than a laptop screen once grouped, and sticky: it scrolls on its own rather than
leaving its last pages below the fold for good */
.docs__nav {
max-height: calc(100vh - 6.5rem);
overflow-y: auto;
scrollbar-width: thin;
}
.docs__list,
.docs__toc ol {
list-style: none;
padding: 0;
margin: var(--space-3) 0 0;
}
.docs__menu-toggle {
display: none;
}
.docs__group + .docs__group {
margin-top: var(--space-4);
}
.docs__group-name {
margin: var(--space-4) 0 0;
font-size: var(--step--1);
letter-spacing: 0.14em;
text-transform: uppercase;
color: var(--luxe-dim);
}
.docs__group .docs__list {
margin-top: var(--space-2);
}
.docs__link {
display: block;
padding: 0.32em 0 0.32em 0.8em;
text-decoration: none;
color: var(--luxe-muted);
border-left: 2px solid var(--luxe-border-muted);
}
.docs__link:hover {
color: var(--luxe-text);
border-left-color: var(--luxe-dim);
}
.docs__link.is-current {
color: var(--luxe-accent);
border-left-color: var(--luxe-accent);
}
.docs__head {
margin-bottom: var(--space-5);
}
.docs__title {
font-size: var(--step-3);
}
.docs__summary {
margin-top: var(--space-2);
max-width: var(--measure);
}
.docs__toc ol {
margin-top: var(--space-2);
}
.docs__toc li {
margin-bottom: var(--space-2);
}
.docs__toc a {
text-decoration: none;
color: var(--luxe-muted);
}
.docs__toc a:hover {
color: var(--luxe-accent);
}
.docs__pager {
display: grid;
grid-template-columns: 1fr 1fr;
gap: var(--space-3);
margin-top: var(--space-7);
padding-top: var(--space-4);
border-top: var(--border);
}
.pager {
display: grid;
gap: var(--space-1);
padding: var(--space-3);
text-decoration: none;
background: var(--luxe-user-msg-bg);
}
.pager--next {
text-align: right;
}
.pager__dir {
font-size: var(--step--1);
letter-spacing: 0.14em;
text-transform: uppercase;
color: var(--luxe-muted);
}
.pager__title {
color: var(--luxe-text);
}
.pager:hover .pager__title {
color: var(--luxe-accent);
}
@media (max-width: 68rem) {
.docs {
grid-template-columns: 13rem minmax(0, 1fr);
}
.docs__toc {
display: none;
}
}
@media (max-width: 48rem) {
.docs {
grid-template-columns: minmax(0, 1fr);
}
.docs__nav {
position: static;
max-height: none;
}
.docs__menu-toggle {
display: block;
margin-top: var(--space-3);
padding: var(--space-2) var(--space-3);
background: var(--luxe-user-msg-bg);
color: var(--luxe-muted);
font-size: var(--step--1);
letter-spacing: 0.14em;
text-transform: uppercase;
cursor: pointer;
}
.docs__list {
display: flex;
flex-wrap: wrap;
gap: var(--space-1) var(--space-3);
}
.docs__link {
border-left: 0;
padding-left: 0;
}
.docs__link.is-current {
border-bottom: 2px solid var(--luxe-accent);
}
}
</style>

View File

@@ -0,0 +1,11 @@
import type { APIRoute, GetStaticPaths } from "astro";
import { guidePages, asMarkdown, type GuidePage } from "../../lib/guide";
/** Every page of the guide as plain markdown, at `/docs/<page>.md`, for agents and copying. */
export const getStaticPaths = (async () =>
(await guidePages()).map((page) => ({ params: { id: page.id }, props: { page } }))) satisfies GetStaticPaths;
export const GET: APIRoute = ({ props }) =>
new Response(asMarkdown((props as { page: GuidePage }).page), {
headers: { "Content-Type": "text/markdown; charset=utf-8" },
});

View File

@@ -0,0 +1,24 @@
import type { APIRoute, GetStaticPaths } from "astro";
import { readdirSync, readFileSync } from "node:fs";
import { join, resolve } from "node:path";
/**
* The guide's screenshots, generated into `docs/guide/images/` by `scripts/site-assets.sh`.
*
* Resolved from where Astro runs, `web/`, not from this module: the build bundles it elsewhere.
*/
const directory = resolve("../docs/guide/images");
/**
* Each screenshot at `/docs/images/<name>.svg`, which is where a link in a page's markdown copy
* (`/docs/<page>.md`) resolves `images/<name>.svg` to. The rendered pages draw them inline.
*/
export const getStaticPaths = (() =>
readdirSync(directory)
.filter((file) => file.endsWith(".svg"))
.map((file) => ({ params: { name: file.slice(0, -4) } }))) satisfies GetStaticPaths;
export const GET: APIRoute = ({ params }) =>
new Response(readFileSync(join(directory, `${params.name}.svg`)), {
headers: { "Content-Type": "image/svg+xml" },
});

1284
web/src/pages/index.astro Normal file

File diff suppressed because it is too large Load Diff

View File

@@ -0,0 +1,9 @@
import type { APIRoute } from "astro";
import { guidePages, asMarkdown } from "../lib/guide";
/** The whole guide as one markdown document, in reading order, for a model to take in at once. */
export const GET: APIRoute = async () => {
const pages = await guidePages();
const body = pages.map(asMarkdown).join("\n---\n\n");
return new Response(body, { headers: { "Content-Type": "text/plain; charset=utf-8" } });
};

28
web/src/pages/llms.txt.ts Normal file
View File

@@ -0,0 +1,28 @@
import type { APIRoute } from "astro";
import { guidePages, grouped, markdownHref } from "../lib/guide";
/**
* The guide's table of contents for a language model, per llmstxt.org: what Luxe is, then every
* page as a markdown link with its summary, under its group.
*/
export const GET: APIRoute = async ({ site }) => {
const origin = site?.origin ?? "https://luxe.dev";
const sections = grouped(await guidePages()).map(
({ group, pages }) =>
`## ${group}\n\n` +
pages
.map((page) => `- [${page.data.title}](${origin}${markdownHref(page.id)}): ${page.data.summary}`)
.join("\n"),
);
const body = [
"# Luxe",
"",
"> A coding agent for your terminal: write, review and ship code in one workflow, with Guided Review, Git and GitHub, and any model.",
"",
`Every page is plain markdown. The whole guide in one file: ${origin}/llms-full.txt`,
"",
sections.join("\n\n"),
"",
].join("\n");
return new Response(body, { headers: { "Content-Type": "text/plain; charset=utf-8" } });
};

View File

@@ -0,0 +1,97 @@
---
/**
* The Open Graph card, as a page.
*
* Not a design file: it is rendered from the same tokens, fonts and logotype as the rest of the
* site, so it cannot drift from what it is advertising. Regenerate the PNG with:
*
* npm run build && npx astro preview &
* # capture http://localhost:4321/social-card at exactly 1200×630
* # save it to web/public/social.png
*
* Kept out of the sitemap and out of the navigation; it exists to be photographed.
*/
import "../assets/generated/tokens.css";
import "../styles/grain.css";
import "../styles/base.css";
import Wordmark from "../components/Wordmark.astro";
---
<html lang="en" data-theme="dark">
<head>
<meta charset="utf-8" />
<title>Luxe — social card</title>
<meta name="robots" content="noindex" />
</head>
<body class="card">
<div class="card__inner">
<div class="card__mark"><Wordmark drift={false} /></div>
<p class="card__line">Built for agents.<br /><em>Refined</em> for humans.</p>
<p class="card__meta">
Rust · terminal · plan → build → review · <span class="card__url">luxe.dev</span>
</p>
</div>
<style is:global>
body.card {
width: 1200px;
height: 630px;
margin: 0;
overflow: hidden;
display: grid;
place-items: center;
}
.card__inner {
width: 100%;
height: 100%;
padding: 92px;
box-sizing: border-box;
display: flex;
flex-direction: column;
justify-content: center;
gap: 34px;
/* A hairline frame inset from the edge, cut at the corners — the same gesture as everything
else, at the one size where a card has room for it. */
position: relative;
}
.card__inner::after {
content: "";
position: absolute;
inset: 40px;
border: 1px solid var(--luxe-border-muted);
}
.card__mark {
width: 380px;
}
.card__line {
font-family: var(--font-display);
font-size: 62px;
line-height: 1.05;
margin: 0;
max-width: none;
color: var(--luxe-text);
}
.card__line em {
font-style: italic;
color: var(--luxe-accent);
}
.card__meta {
margin: 0;
max-width: none;
font-size: 21px;
letter-spacing: 0.06em;
color: var(--luxe-muted);
}
.card__url {
color: var(--luxe-accent);
}
</style>
</body>
</html>

182
web/src/pages/themes.astro Normal file
View File

@@ -0,0 +1,182 @@
---
import Base from "../layouts/Base.astro";
import ThemePreview from "../components/ThemePreview.astro";
import themeCss from "../assets/generated/tokens.css?raw";
/**
* The palette, with its numbers attached.
*
* Swatches are read out of the generated stylesheet rather than typed here, so this page cannot
* disagree with the theme the terminal loads.
*/
const readTokens = (block: string) =>
[...block.matchAll(/--luxe-([a-z-]+):\s*(#[0-9a-f]{6});/g)].map(([, name, hex]) => ({ name, hex }));
const modes = [
{ label: "luxe", note: "warm graphite, champagne brass", tokens: readTokens(themeCss) },
];
/** Relative luminance, so each chip can print its own contrast rather than claim one. */
function contrast(a: string, b: string) {
const lum = (hex: string) => {
const parts = [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16) / 255);
const [r, g, bl] = parts.map((c) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4));
return 0.2126 * r + 0.7152 * g + 0.0722 * bl;
};
const [hi, lo] = [lum(a), lum(b)].sort((x, y) => y - x);
return (hi + 0.05) / (lo + 0.05);
}
---
<Base title="Themes — Luxe" description="Luxe's palette, and the community favorites it ships with.">
<div class="page">
<section class="section section--head">
<p class="eyebrow">Themes</p>
<h1>Color that means something.</h1>
<div class="prose">
<p>
Luxe's own palette is warm graphite with a champagne-brass accent, and its hues come from a
set of paint colors rather than a terminal convention. Those are mid-luminance by nature,
so the hues were kept and the lightness re-derived against a contrast floor.
</p>
<p>
Three rules do the work, and each one is asserted in the test suite rather than eyeballed:
every background and gray shares one neutral hue, every accent sits on one lightness
plateau so none of them shouts, and nothing drops below 4.5:1 on its own background.
</p>
</div>
</section>
{
modes.map(({ label, note, tokens }) => {
const background = tokens.find((t) => t.name === "background")!.hex;
return (
<section class="section">
<div class="theme__head">
<h2 class="theme__name">{label}</h2>
<p class="muted theme__note">{note}</p>
</div>
<ul class="swatches">
{tokens
.filter(
(t) =>
!t.name.startsWith("wordmark") &&
!t.name.startsWith("capture") &&
t.name !== "tile-ink",
)
.map(({ name, hex }) => (
<li class="swatch">
<span class="swatch__chip" style={`background:${hex}`} />
<span class="swatch__name">{name}</span>
<span class="swatch__hex">{hex}</span>
<span class="swatch__ratio">
{name === "background" ? "—" : `${contrast(hex, background).toFixed(1)}:1`}
</span>
</li>
))}
</ul>
</section>
);
})
}
<section class="section section--last">
<h2>And plenty you may already use.</h2>
<div class="prose">
<p>
Ports that stay true to their originals. Luxe only steps in where a color is too faint to
read a word in, or where a theme's "red" isn't red, since a failed test shown in green
says the opposite of what happened.
</p>
<p>
Point at one to see it. That's how <code>/theme</code> works in the terminal too: the
cursor moves and the whole app repaints, because a palette isn't something you can judge
from its name.
</p>
</div>
<ThemePreview swatches />
<p class="muted">
Set one with <code>"theme": "nord"</code> in <code>~/.config/luxe/config.json</code>, or
override individual tokens with a <code>colors</code> map. On Omarchy, Luxe wears your
desktop's theme and changes with it when you switch.
</p>
</section>
</div>
</Base>
<style>
.section--head {
border-top: 0;
padding-top: var(--space-6);
}
.section--last {
border-bottom: 0;
}
.prose {
max-width: var(--measure);
margin-top: var(--space-4);
}
.theme__head {
display: flex;
align-items: baseline;
gap: var(--space-3);
flex-wrap: wrap;
}
.theme__name {
font-family: var(--font-mono);
font-size: var(--step-1);
letter-spacing: 0;
}
.theme__note {
margin: 0;
font-size: var(--step--1);
}
.swatches {
list-style: none;
padding: 0;
margin: var(--space-4) 0 0;
display: grid;
gap: var(--space-2) var(--space-4);
grid-template-columns: repeat(auto-fill, minmax(17rem, 1fr));
}
.swatch {
display: grid;
grid-template-columns: 1.6rem 1fr auto auto;
align-items: center;
gap: var(--space-2);
font-size: var(--step--1);
padding-block: 0.3rem;
border-bottom: 1px solid var(--luxe-border-muted);
}
.swatch__chip {
width: 1.6rem;
height: 1.6rem;
box-shadow: inset 0 0 0 1px color-mix(in oklab, var(--luxe-text) 18%, transparent);
}
.swatch__name {
color: var(--luxe-text);
}
.swatch__hex,
.swatch__ratio {
color: var(--luxe-muted);
font-variant-numeric: tabular-nums;
}
.swatch__ratio {
min-width: 4ch;
text-align: right;
}
</style>

695
web/src/pages/tools.astro Normal file
View File

@@ -0,0 +1,695 @@
---
import Base from "../layouts/Base.astro";
import bench from "../data/tool-bench.json";
import agentCost from "../data/agent-cost.json";
/**
* Each tool against the shell command it replaces.
*
* The bars are measured, not typed: `scripts/tool-bench.sh` runs both sides in a checkout and
* writes `tool-bench.json`, which names the repository and the commit. Each shell command is also
* put through the other agents' own output limits, because no agent sends its model a raw 8 MB
* `git log`: the honest comparison is with what they forward. A tool whose win is behavior rather
* than size gets the two behaviors side by side instead.
*/
type Contrast = { shell: string; luxe: string };
type Tool = { name: string; instead: string; text: string; bench?: string; contrast?: Contrast };
type Group = { id: string; name: string; tools: Tool[] };
const groups: Group[] = [
{
id: "files",
name: "Files",
tools: [
{
name: "read",
instead: "`cat`, `head`, `sed -n`",
text: "Several files in one call, with numbered lines. An image comes back as a picture.",
contrast: {
shell: "Sends the whole file, however long, and the model can't see an image.",
luxe: "A page at a time, stopping at a line boundary and saying where to pick up.",
},
},
{
name: "edit",
instead: "`sed -i`",
text: "Changes exact text, several edits in one call, all or none. It won't touch a file the agent hasn't read, or one that changed since.",
contrast: {
shell: "Exits 0 when the pattern matches nothing, so a missed edit looks like a done one.",
luxe: "Refuses a miss and points at the closest line, refuses an ambiguous match, and shows the diff after formatting.",
},
},
{
name: "write",
instead: "`cat > file`",
text: "Creates or replaces a whole file, and shows what it wrote.",
contrast: {
shell: "Replaces whatever was there, unseen.",
luxe: "Won't overwrite a file the agent hasn't read, keeps its line endings, and formats it.",
},
},
],
},
{
id: "search",
name: "Search",
tools: [
{
name: "glob",
instead: "`find`",
bench: "glob",
text: "Skips whatever `.gitignore` skips, so build output and dependencies stay out. Sorted by path, capped at 200, with a count of the rest.",
},
{
name: "grep",
instead: "`grep -rn`, `rg`",
bench: "grep",
text: "Capped per file and overall, with long lines trimmed. It can return just the files that match or just the counts, and says so when there's more.",
},
{
name: "ast_grep",
instead: "`grep` on code",
text: "Search and replace by code structure. A rewrite shows a preview before it writes.",
contrast: {
shell: "Matches text, so comments and strings count too.",
luxe: "Matches syntax: `$X.unwrap()` finds the calls and nothing else.",
},
},
],
},
{
id: "shell",
name: "Shell and tests",
tools: [
{
name: "bash",
instead: "`sh`",
bench: "bash",
text: "Long output comes back as the lines that matter, with every gap marked and the untouched text saved to a file, each stream whole up to 8 MB. A command that runs out of time returns what it printed so far.",
},
{
name: "test",
instead: "`cargo test`, `npm test`, `pytest`",
bench: "test",
text: "One line when everything passes. When something fails, each failure with its `file:line`, and which ones your change broke. Tests run the project's way, through its own `.venv` or package manager.",
},
],
},
{
id: "git",
name: "Git",
tools: [
{
name: "git",
instead: "`git`, `gh`",
bench: "git",
text: "The last ten commits, with a note when there are more. Diffs are capped and say how to narrow them. Pull requests, issues and CI checks come through `gh`.",
},
],
},
{
id: "code",
name: "Code intelligence",
tools: [
{
name: "read_symbol",
instead: "`cat`",
bench: "read_symbol",
text: "One function, struct or method by name, instead of the file it lives in.",
},
{
name: "module_report",
instead: "`cat`",
bench: "module_report",
text: "A file's outline: each symbol and the lines it spans, so the agent reads only what it needs.",
},
{
name: "symbol_search",
instead: "`rg 'fn name'`",
text: "Where something is defined, from its name or part of it.",
contrast: {
shell: "Matches text, and the pattern changes with every language.",
luxe: "Finds definitions by name in any language, ranked, with what kind of thing each one is.",
},
},
{
name: "impact",
instead: "nothing",
text: "What else a change touches, before the agent makes it.",
contrast: {
shell: "Callers of callers is a search per hop, and tests don't say what they cover.",
luxe: "Lists what calls a symbol, what depends on a file, and which tests cover it, a few hops out.",
},
},
{
name: "lsp_diagnostics",
instead: "`cargo check`, `tsc`",
text: "Errors and warnings for the files you name. They also come back on their own after every edit.",
contrast: {
shell: "Builds the whole project, one language at a time.",
luxe: "Asks the language server about one file, in any language that has a server.",
},
},
{
name: "lsp_navigation",
instead: "`grep` for a name",
text: "Definitions, references, types and renames, from the language server.",
contrast: {
shell: "Every line that spells the same name.",
luxe: "The definition and the real references, by meaning rather than spelling.",
},
},
],
},
{
id: "debug",
name: "Debugging",
tools: [
{
name: "debug",
instead: "print statements",
text: "Drives a real debugger, with breakpoints, stepping and variables, for Rust, C, C++, Python and Go.",
contrast: {
shell: "Add a print, rebuild, rerun, repeat.",
luxe: "Stops at a breakpoint and shows the frame and its locals, with library frames folded away.",
},
},
],
},
{
id: "web",
name: "The web",
tools: [
{
name: "web_fetch",
instead: "`curl`",
bench: "web_fetch",
text: "Pages come back as markdown, not HTML. A GitHub repository is cloned into the project, with its links flattened and no language server started in it, so the agent can search the real files.",
},
{
name: "web_search",
instead: "`curl` a search page",
text: "Searches the web through the provider you have a key for, or a free one.",
contrast: {
shell: "A page of HTML built for a browser.",
luxe: "Titles, links and the passage that matched.",
},
},
{
name: "screenshot",
instead: "`chrome --headless --screenshot`",
text: "Captures a page, so the agent can check the UI it just built.",
contrast: {
shell: "Writes a file the model never sees.",
luxe: "Returns the picture to the model, from your dev server or any page.",
},
},
],
},
];
const beyond = [
{ name: "todo", text: "A checklist that survives compaction, shown in the dock's PLAN." },
{ name: "question", text: "Stops to ask you, with choices, instead of guessing." },
{ name: "skill", text: "Loads a skill's instructions when the task calls for them." },
{ name: "mcp", text: "Your MCP servers behind one tool, every call checked against your permissions." },
];
// The primary repository draws the bars; a tool it has no case for (`web_fetch` is not about a
// repository) falls back to the next one that does
const [primary] = bench.repositories;
const rows = new Map(
[...bench.repositories].reverse().flatMap((repo) => repo.rows.map((row) => [row.id, row])),
);
for (const row of primary.rows) rows.set(row.id, row);
/** The tightest of the four other agents' limits on the same output: Codex's. */
const tightest = (row: { forwarded: Record<string, number> }) =>
Math.min(...Object.values(row.forwarded));
/** `code` spans in copy, with everything else escaped. */
const inline = (text: string) =>
text
.replace(/&/g, "&amp;")
.replace(/</g, "&lt;")
.replace(/>/g, "&gt;")
.replace(/`([^`]+)`/g, "<code>$1</code>");
/** About four bytes a token, which is close enough to show the scale. */
const tokens = (bytes: number) => {
const count = bytes / 4;
if (count < 1000) return `${Math.max(1, Math.round(count / 10) * 10)} tokens`;
if (count < 10_000) return `${(count / 1000).toFixed(1)}k tokens`;
return `${Math.round(count / 1000)}k tokens`;
};
const times = (shell: number, tool: number) => {
const ratio = shell / tool;
if (ratio < 1.1) return "the same";
return ratio < 10 ? `${ratio.toFixed(1)}× less` : `${Math.round(ratio).toLocaleString("en-US")}× less`;
};
/** Luxe against the tightest cut another agent makes, said both ways round. */
const versus = (cut: number, tool: number) => {
if (tool <= cut * 1.05 && tool >= cut * 0.95) return "about what the tightest cut sends";
if (tool < cut) return `${times(cut, tool)} than the tightest cut`;
const ratio = tool / cut;
return `${ratio.toFixed(1)}× more than the tightest cut, with nothing cut out`;
};
/**
* Whole tasks against the other agents: each agent's cost on the same task as a multiple of
* Luxe's, charged as a cold start.
*/
type Other = { warm: number; cold: number; passed: number; runs: number };
type CostRow = { model: string; luxe: { passed: number; runs: number } } & Partial<
Record<"claude" | "codex" | "opencode" | "pi", Other>
>;
const costRows = agentCost.rows as CostRow[];
const vendorAgent = (row: CostRow) => row.claude ?? row.codex;
const multiple = (other?: Other) => (other ? `${other.cold.toFixed(2)}×` : "–");
/** A bar's share of its row, never so thin it disappears. */
const share = (shell: number, tool: number) => `${Math.max((tool / shell) * 100, 0.6)}%`;
---
<Base
title="Tools — Luxe"
description="Every tool in Luxe has to beat the shell command it replaces. Here's how each one does, measured."
>
<div class="page">
<section class="section section--head">
<p class="eyebrow">Tools</p>
<h1>Better than the shell.</h1>
<div class="prose">
<p>
An agent can do almost anything with a shell, and that's the trouble. A <code>find</code> in
a real project returns half a megabyte, a <code>sed</code> that matches nothing reports
success, and the model pays for all of it in tokens and turns.
</p>
<p>
So every tool in Luxe has to beat the command it replaces: by sending less, by getting it
right the first time, or by doing something the shell can't.
</p>
<p class="muted note">
Measured in a checkout of {primary.name} at <code>{primary.commit}</code>, the codebase
the harness eval runs in, with its virtualenv in place. The shell row is the command's
raw output; <em>tightest cut</em> is the least any other agent sends its model of it,
which is Codex's 10 KB, head and tail kept. Pi and OpenCode keep up to 50 KB and Claude
Code 30,000 characters. A token is about four bytes.
</p>
<p class="muted note">
Those are single calls, and across a whole task the bars shrink, because most calls are
small to begin with. What a whole task costs is <a href="#tasks">below</a>.
</p>
</div>
</section>
<section class="section group" id="tasks">
<h2 class="group__name">Whole tasks</h2>
<div class="prose">
<p>
Luxe, Claude Code, Codex, OpenCode and Pi each ran the first twelve Django tasks of
SWE-bench Verified Mini, with the same model, the same prompt and the same keys, every
call metered at the network and priced from one list. Each figure is what the other agent
spent on the same task, as a multiple of what Luxe spent: above 1× costs more than Luxe.
</p>
</div>
<table class="costs">
<thead>
<tr>
<th scope="col">Model</th>
<th scope="col">Claude Code or Codex</th>
<th scope="col">OpenCode</th>
<th scope="col">Pi</th>
</tr>
</thead>
<tbody>
{
costRows.map((row) => (
<tr>
<th scope="row">
<code>{row.model}</code>
</th>
<td>{multiple(vendorAgent(row))}</td>
<td>{multiple(row.opencode)}</td>
<td>{multiple(row.pi)}</td>
</tr>
))
}
</tbody>
</table>
<div class="prose">
<p class="muted note">
Every run is charged as a cold start, the way a session begins after a break. Run side
by side on a warm cache, Claude Code and OpenCode cost up to 2.6× what Luxe does on
Claude models. Pass rates overlapped on every model. Pi is the cheapest by design: four
tools and a short prompt, with web search, MCP and the rest left to extensions. Graded
on one machine rather than in SWE-bench's own containers, so these are not leaderboard
scores. Measured at <code>{agentCost.commit}</code>.
</p>
</div>
</section>
{
groups.map((group) => (
<section class="section group" id={group.id}>
<h2 class="group__name">{group.name}</h2>
{group.tools.map((tool) => {
const row = tool.bench ? rows.get(tool.bench) : undefined;
return (
<article class="tool" id={tool.name}>
<div class="tool__text">
<h3 class="tool__name">{tool.name}</h3>
<p class="tool__instead">
instead of <span set:html={inline(tool.instead)} />
</p>
<p set:html={inline(tool.text)} />
</div>
{row && (
<figure class="bench">
<div class="bench__row">
<code class="bench__label">$ {row.shell}</code>
<span class="bench__track">
<span class="bench__bar" style="width: 100%" />
</span>
<span class="bench__value">{tokens(row.shellBytes)}</span>
</div>
<div class="bench__row bench__row--cut">
<span class="bench__label">tightest cut</span>
<span class="bench__track">
<span
class="bench__bar"
style={`width: ${share(row.shellBytes, tightest(row))}`}
/>
</span>
<span class="bench__value">{tokens(tightest(row))}</span>
</div>
<div class="bench__row bench__row--tool">
<code class="bench__label">{row.tool}</code>
<span class="bench__track">
<span
class="bench__bar"
style={`width: ${share(row.shellBytes, row.toolBytes)}`}
/>
</span>
<span class="bench__value">{tokens(row.toolBytes)}</span>
</div>
<figcaption class="bench__ratio">
{times(row.shellBytes, row.toolBytes)}
<span class="bench__versus">
{times(row.shellBytes, row.toolBytes) === "the same" ? "as" : "than"} the
shell · {versus(tightest(row), row.toolBytes)}
</span>
</figcaption>
</figure>
)}
{tool.contrast && (
<dl class="contrast">
<div class="contrast__row">
<dt>Shell</dt>
<dd set:html={inline(tool.contrast.shell)} />
</div>
<div class="contrast__row contrast__row--luxe">
<dt>Luxe</dt>
<dd set:html={inline(tool.contrast.luxe)} />
</div>
</dl>
)}
</article>
);
})}
</section>
))
}
<section class="section group" id="beyond">
<h2 class="group__name">Beyond the shell</h2>
<ul class="beyond">
{
beyond.map(({ name, text }) => (
<li class="beyond__item">
<h3 class="tool__name">{name}</h3>
<p>{text}</p>
</li>
))
}
</ul>
</section>
<section class="section section--last group" id="every">
<h2 class="group__name">Every tool</h2>
<ul class="beyond">
<li class="beyond__item">
<h3>Time limits</h3>
<p>Every call has one, and <code>ctrl+esc</code> stops the whole batch.</p>
</li>
<li class="beyond__item">
<h3>Forgiving</h3>
<p>A call with an argument the tool doesn't know still runs, and says which it ignored.</p>
</li>
<li class="beyond__item">
<h3>Yours to change</h3>
<p>
<code>/tools</code> shows what the agent can use, and any tool but the core four can be
turned off. See <a href="/docs/tools">the guide</a>.
</p>
</li>
</ul>
</section>
</div>
</Base>
<style>
.section--head {
border-top: 0;
padding-top: var(--space-6);
}
.section--last {
border-bottom: 0;
}
.prose {
max-width: var(--measure);
margin-top: var(--space-4);
}
.note {
font-size: var(--step--1);
}
.costs {
margin-top: var(--space-5);
border-collapse: collapse;
font-variant-numeric: tabular-nums;
}
.costs th,
.costs td {
padding: var(--space-2) var(--space-4);
border-bottom: 1px solid var(--luxe-border-muted);
text-align: right;
}
.costs th[scope="row"],
.costs thead th:first-child {
text-align: left;
}
.costs thead th {
font-weight: 500;
}
.group__name {
font-size: var(--step-2);
margin-bottom: var(--space-5);
}
/* The words on the left, the evidence on the right, one tool to a row */
.tool {
display: grid;
grid-template-columns: minmax(0, 30rem) minmax(0, 1fr);
gap: var(--space-3) var(--space-6);
align-items: center;
}
.tool + .tool {
margin-top: var(--space-5);
padding-top: var(--space-5);
border-top: 1px solid var(--luxe-border-muted);
}
.tool__text p {
margin: 0;
}
.tool__name {
font-family: var(--font-mono);
font-size: var(--step-1);
letter-spacing: 0;
color: var(--luxe-accent);
margin: 0 0 var(--space-1);
}
.tool__instead {
color: var(--luxe-muted);
font-size: var(--step--1);
margin-bottom: var(--space-2) !important;
}
/* === Measured === */
.bench {
margin: 0;
display: grid;
gap: var(--space-2);
}
.bench__row {
display: grid;
grid-template-columns: minmax(0, 15rem) minmax(0, 1fr) 7.5rem;
align-items: center;
gap: var(--space-3);
font-size: var(--step--1);
}
.bench__label {
color: var(--luxe-muted);
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
}
.bench__row--tool .bench__label {
color: var(--luxe-accent);
}
.bench__track {
display: block;
height: 0.9rem;
background: var(--luxe-user-msg-bg);
}
.bench__bar {
display: block;
height: 100%;
background: var(--luxe-dim);
}
.bench__row--tool .bench__bar {
background: var(--luxe-accent);
}
.bench__row--cut .bench__bar {
background: var(--luxe-muted);
}
.bench__versus {
display: block;
margin-top: var(--space-1);
font-family: var(--font-body);
font-size: var(--step--1);
color: var(--luxe-muted);
text-align: right;
}
.bench__value {
color: var(--luxe-muted);
text-align: right;
font-variant-numeric: tabular-nums;
}
.bench__row--tool .bench__value {
color: var(--luxe-text);
}
.bench__ratio {
justify-self: end;
font-family: var(--font-display);
font-size: var(--step-2);
line-height: 1;
color: var(--luxe-accent);
}
/* === Behavior === */
.contrast {
margin: 0;
display: grid;
gap: var(--space-2);
}
.contrast__row {
display: grid;
grid-template-columns: 4rem minmax(0, 1fr);
gap: var(--space-3);
padding: var(--space-2) var(--space-3);
background: var(--luxe-user-msg-bg);
border-left: 2px solid var(--luxe-dim);
}
.contrast__row--luxe {
border-left-color: var(--luxe-accent);
}
.contrast dt {
font-size: var(--step--1);
letter-spacing: 0.2em;
text-transform: uppercase;
color: var(--luxe-muted);
padding-top: 0.15em;
}
.contrast__row--luxe dt {
color: var(--luxe-accent);
}
.contrast dd {
margin: 0;
}
/* === The rest === */
.beyond {
list-style: none;
padding: 0;
margin: 0;
display: grid;
grid-template-columns: repeat(auto-fit, minmax(15rem, 1fr));
gap: var(--space-4);
}
.beyond__item {
padding: var(--space-4);
background: var(--luxe-user-msg-bg);
border: var(--border);
}
.beyond__item h3:not(.tool__name) {
font-family: var(--font-display);
font-weight: 400;
font-size: var(--step-2);
line-height: 1.1;
margin: 0 0 var(--space-2);
}
.beyond__item p {
margin: 0;
}
@media (max-width: 68rem) {
.tool {
grid-template-columns: minmax(0, 1fr);
}
}
@media (max-width: 40rem) {
.bench__row {
grid-template-columns: minmax(0, 1fr) 6.5rem;
}
.bench__label {
grid-column: 1 / -1;
}
}
</style>