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

View File

@@ -0,0 +1,243 @@
//! Subcommands — the arguments each `luxe <command>` takes.
use clap::{Parser, Subcommand};
/// Subcommands for luxe.
#[derive(Subcommand, Debug)]
pub(crate) enum SubCommand {
/// Sign in to a provider, check credentials, or sign out.
Auth(AuthArgs),
/// Read Luxe's user guide, for this version.
Docs(DocsArgs),
/// Check which language servers, debug adapters and tools work on this machine.
Doctor,
/// Set Luxe up: a theme, a provider, the tools and the start screen.
Init(InitArgs),
/// Run the agent through a phased plan on its own.
Loop(LoopArgs),
/// Add, list and sign in to MCP servers.
Mcp(McpArgs),
/// List models, show one's details, or refresh the catalog.
Models(ModelsArgs),
/// List this project's sessions.
Sessions(SessionsArgs),
/// Summarize a `LUXE_WIRE_LOG` capture.
Wire(WireArgs),
}
/// Docs arguments.
#[derive(Parser, Debug)]
pub(crate) struct DocsArgs {
/// A page to print, such as `install` or `hooks`. Without one, lists every page.
pub(crate) page: Option<String>,
/// Print the lines across every page that contain all of these words.
#[arg(long)]
pub(crate) search: Option<String>,
}
/// Wire arguments.
#[derive(Parser, Debug)]
pub(crate) struct WireArgs {
/// Path to a log written by `LUXE_WIRE_LOG=<path> luxe ...`.
pub(crate) log: std::path::PathBuf,
/// Break the tool-schema total down per tool.
#[arg(long)]
pub(crate) tools: bool,
}
/// Auth arguments.
#[derive(Parser, Debug)]
pub(crate) struct AuthArgs {
#[command(subcommand)]
pub(crate) command: AuthCommand,
}
/// Auth subcommand — provider credentials.
#[derive(Subcommand, Debug)]
pub(crate) enum AuthCommand {
/// Sign in to a provider (API key or subscription).
Login {
/// Provider id (e.g. `openai`, `anthropic`, `github-copilot`). Omit to choose from a list.
provider: Option<String>,
/// Which login to run: `api-key` or `subscription`. Only needed when a provider has both.
#[arg(long)]
method: Option<String>,
/// Supply the API key directly instead of being prompted. Beware shell history.
#[arg(long, conflicts_with = "stdin")]
api_key: Option<String>,
/// Read the API key from stdin (`pass show openai | luxe auth login openai --stdin`).
#[arg(long)]
stdin: bool,
/// Skip the "does this key work" request — for an air-gapped or proxied setup.
#[arg(long)]
no_verify: bool,
},
/// List every provider and how each one is configured.
List,
/// Show credential detail (kind, source, expiry) for one provider or all configured ones.
Status {
/// Provider id. Omit for every configured provider.
provider: Option<String>,
},
/// Remove a stored credential. Environment variables are left alone.
Logout {
/// Provider id.
provider: String,
},
}
/// Models arguments.
#[derive(Parser, Debug)]
pub(crate) struct ModelsArgs {
#[command(subcommand)]
pub(crate) command: ModelsCommand,
}
/// Models subcommand — what Luxe knows about a model, and where it learned it.
#[derive(Subcommand, Debug)]
pub(crate) enum ModelsCommand {
/// List known models for the providers Luxe can route to.
List {
/// Only this provider.
#[arg(long)]
provider: Option<String>,
/// Only models pinned in `models.json` / `auth.json`.
#[arg(long)]
configured: bool,
},
/// Show one model's resolved metadata and which layer supplied each field.
Show {
/// `provider/id`, or a bare id to use the active provider.
model: String,
},
/// Revalidate the models.dev cache now.
Refresh {
/// Fetch even when the cache is still current.
#[arg(long)]
force: bool,
},
}
/// Init arguments.
#[derive(Parser, Debug)]
pub(crate) struct InitArgs {
/// Start over: remove the existing config before setting up.
#[arg(long)]
pub(crate) force: bool,
/// Write a config that chooses nothing, without asking, so every default applies.
#[arg(long)]
pub(crate) defaults: bool,
}
/// Sessions arguments.
#[derive(Parser, Debug)]
pub(crate) struct SessionsArgs {
#[command(subcommand)]
pub(crate) command: SessionsCommand,
}
/// Sessions subcommand — inspect resumable sessions.
#[derive(Subcommand, Debug)]
pub(crate) enum SessionsCommand {
/// List sessions for the current project (newest first).
List,
}
/// Loop arguments.
#[derive(Parser, Debug)]
pub(crate) struct LoopArgs {
#[command(subcommand)]
pub(crate) command: LoopCommand,
}
/// MCP arguments.
#[derive(Parser, Debug)]
pub(crate) struct McpArgs {
#[command(subcommand)]
pub(crate) command: McpCommand,
}
/// Loop subcommand — manage continuous development loops.
#[derive(Subcommand, Debug)]
pub(crate) enum LoopCommand {
/// Start a new continuous loop.
Start {
/// Print nothing but the banner: no per-turn activity. The log and the journal are
/// written either way.
#[arg(long)]
quiet: bool,
/// Maximum turns per run (default: 50).
#[arg(long, default_value_t = 50)]
max_turns: u32,
/// Compact at this percentage of the usable window (default: `compaction.at`, else 75).
#[arg(long, value_parser = clap::value_parser!(u8).range(1..=100))]
compact_percent: Option<u8>,
/// Pause at this percentage of context window (default: 90).
#[arg(long, default_value_t = 90)]
pause_percent: u8,
},
/// Stop the current loop.
Stop,
/// Pause the current loop.
Pause,
/// Resume a paused loop.
Resume,
/// Show loop status.
Status,
/// Show loop phase (and optionally set it).
Phase {
/// Set phase to this number.
#[arg(long)]
set: Option<u32>,
},
/// Reset the run's turn count, so the next `luxe loop start` gets all of `--max-turns` again.
Fresh,
}
/// MCP subcommand — manage MCP servers and tools.
#[derive(Subcommand, Debug)]
pub(crate) enum McpCommand {
/// List configured MCP servers.
List,
/// Add an MCP server.
Add {
/// Server ID.
#[arg(long)]
id: String,
/// Server name.
#[arg(long)]
name: String,
/// Command to run (for stdio transport).
#[arg(long)]
command: Option<String>,
/// URL (for HTTP/SSE transport).
#[arg(long)]
url: Option<String>,
},
/// Remove an MCP server.
Remove {
/// Server ID to remove.
#[arg(long)]
id: String,
},
/// List tools from all MCP servers.
Tools,
/// Authorize an OAuth-protected MCP server (opens a browser flow).
Login {
/// Server ID to authorize.
#[arg(long)]
id: String,
},
}

View File

@@ -0,0 +1,109 @@
//! Permission mode — CLI policy validation before startup.
use clap::builder::{EnumValueParser, PossibleValue, TypedValueParser};
use clap::ValueEnum;
use luxe_core::permission::PermissionMode;
/// Permission presets accepted on the command line.
#[derive(ValueEnum, Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum PermissionModeArg {
/// Keep the built-in guardrails without asking before every mutation.
Default,
/// Ask before mutating tools.
Strict,
/// Deny mutating tools.
#[value(alias = "readonly", alias = "ro")]
ReadOnly,
/// Disable the built-in guardrails.
Yolo,
}
impl From<PermissionModeArg> for PermissionMode {
fn from(arg: PermissionModeArg) -> Self {
match arg {
PermissionModeArg::Default => Self::Default,
PermissionModeArg::Strict => Self::Strict,
PermissionModeArg::ReadOnly => Self::ReadOnly,
PermissionModeArg::Yolo => Self::Yolo,
}
}
}
#[derive(Clone)]
pub(super) struct PermissionModeParser;
impl TypedValueParser for PermissionModeParser {
type Value = PermissionModeArg;
fn parse_ref(
&self,
cmd: &clap::Command,
arg: Option<&clap::Arg>,
value: &std::ffi::OsStr,
) -> Result<Self::Value, clap::Error> {
// Keep the core parser's normalization without accepting an unknown policy
let normalized = value.to_str().map(|raw| raw.trim().replace(['_', ' '], "-"));
let value = normalized.as_deref().map(std::ffi::OsStr::new).unwrap_or(value);
EnumValueParser::<PermissionModeArg>::new().parse_ref(cmd, arg, value)
}
fn possible_values(&self) -> Option<Box<dyn Iterator<Item = PossibleValue> + '_>> {
Some(Box::new(
PermissionModeArg::value_variants().iter().filter_map(ValueEnum::to_possible_value),
))
}
}
#[cfg(test)]
mod tests {
use super::super::{permission_mode_from_args, Args};
use clap::{error::ErrorKind, Parser};
use luxe_core::permission::PermissionMode;
/// A policy typo must stop startup instead of falling back to permissive defaults.
#[test]
fn an_unknown_permission_mode_is_refused() {
for typo in ["strcit", "read-onyl", "", "unknown"] {
let error = Args::try_parse_from(["luxe", "--permission-mode", typo])
.expect_err("an invalid policy must stop startup");
assert_eq!(error.kind(), ErrorKind::InvalidValue, "{typo:?}");
}
}
/// CLI validation must preserve the mode parser's accepted spellings.
#[test]
fn accepted_permission_modes_keep_their_meaning() {
for spelling in [
"default",
"strict",
"read-only",
"readonly",
"ro",
"yolo",
"read_only",
"read only",
"STRICT",
" Read_Only ",
] {
let args = Args::try_parse_from(["luxe", "--permission-mode", spelling])
.expect("a supported mode");
assert_eq!(permission_mode_from_args(&args), PermissionMode::parse(spelling));
}
}
/// Shortcuts retain precedence over a valid named mode; absence defers to config.
#[test]
fn permission_shortcuts_keep_their_precedence() {
for (flags, expected) in [
(vec![], None),
(vec!["--permission-mode", "strict"], Some(PermissionMode::Strict)),
(vec!["--permission-mode", "strict", "--read-only"], Some(PermissionMode::ReadOnly)),
(vec!["--permission-mode", "strict", "--yolo"], Some(PermissionMode::Yolo)),
(vec!["--read-only", "--yolo"], Some(PermissionMode::Yolo)),
] {
let args =
Args::try_parse_from(std::iter::once("luxe").chain(flags)).expect("valid flags");
assert_eq!(permission_mode_from_args(&args), expected);
}
}
}

View File

@@ -0,0 +1,257 @@
use super::*;
use clap::Parser;
/// What a command line classifies as, for the two questions startup asks before dispatch.
///
/// The classification is an exhaustive match, so a new [`SubCommand`] variant does not compile
/// until somebody answers for it; this pins the answers that are already given. The stakes are
/// asymmetric: a session wrongly classed as reporting loses its project log, and a reporting
/// command wrongly classed as a session leaves a `.luxe/` that silently re-roots every
/// repository beneath it.
#[test]
fn only_the_commands_that_own_project_state_may_create_one() {
let parse = |line: &[&str]| Args::try_parse_from(line).expect("a valid command line");
for session in [
vec!["luxe"],
vec!["luxe", "--headless", "-p", "hi"],
vec!["luxe", "--rpc"],
vec!["luxe", "loop", "start"],
vec!["luxe", "loop", "status"],
vec!["luxe", "mcp", "add", "--id", "x", "--name", "x", "--command", "x"],
vec!["luxe", "mcp", "remove", "--id", "x"],
] {
assert!(parse(&session).owns_project_state(), "{session:?} writes into the project");
}
for reporting in [
vec!["luxe", "auth", "list"],
vec!["luxe", "doctor"],
vec!["luxe", "init"],
vec!["luxe", "models", "list"],
vec!["luxe", "sessions", "list"],
vec!["luxe", "wire", "/tmp/log"],
vec!["luxe", "mcp", "list"],
vec!["luxe", "mcp", "tools"],
] {
assert!(
!parse(&reporting).owns_project_state(),
"{reporting:?} only reads, so it must leave no .luxe/ behind"
);
}
}
/// `--github-writes` is a grant to an RPC client, so it means nothing anywhere else.
///
/// Accepting it on the TUI or headless would read as "the agent may now publish", which it
/// does not say and does not do.
#[test]
fn github_writes_is_only_for_an_rpc_client() {
let parse = |line: &[&str]| Args::try_parse_from(line).expect("a valid command line");
let granted = parse(&["luxe", "--rpc", "--github-writes"]);
assert!(granted.github_writes && !granted.github_writes_misplaced());
assert!(!parse(&["luxe", "--rpc"]).github_writes, "off by default");
assert!(!parse(&["luxe"]).github_writes_misplaced(), "absent is never misplaced");
for elsewhere in [
vec!["luxe", "--github-writes"],
vec!["luxe", "--headless", "-p", "hi", "--github-writes"],
vec!["luxe", "--rpc", "--github-writes", "doctor"],
] {
assert!(parse(&elsewhere).github_writes_misplaced(), "{elsewhere:?}");
}
}
/// `--on-ask` settles the answer for a run with nobody to ask, so the surfaces that *can* ask
/// have to be told apart from the ones that cannot — on the TUI and RPC the flag would read as
/// a policy and do nothing, which is the shape of mistake nobody finds until an agent has been
/// running unwatched.
#[test]
fn only_a_run_with_nobody_to_ask_can_be_told_what_an_ask_becomes() {
let parse = |line: &[&str]| Args::try_parse_from(line).expect("a valid command line");
for interactive in [vec!["luxe"], vec!["luxe", "--rpc"]] {
assert!(parse(&interactive).prompts_a_human(), "{interactive:?}");
}
for unattended in [
vec!["luxe", "--headless", "-p", "hi"],
vec!["luxe", "loop", "start"],
vec!["luxe", "doctor"],
] {
assert!(!parse(&unattended).prompts_a_human(), "{unattended:?}");
}
// A misspelled policy stops the run rather than being ignored — unlike `--thinking`, which
// warns and carries on, because that is a preference and this is not.
assert!(
Args::try_parse_from(["luxe", "--headless", "-p", "hi", "--on-ask", "dney"]).is_err(),
"an unreadable policy must not resolve to the permissive answer"
);
assert_eq!(
parse(&["luxe", "--headless", "-p", "hi", "--on-ask", "deny"]).on_ask,
Some(OnAskArg::Deny)
);
// The two flags are opposite answers to one question; asking for both is a mistake.
assert!(
Args::try_parse_from(["luxe", "--auto-approve", "--on-ask", "allow"]).is_err(),
"--auto-approve and --on-ask cannot both be in force"
);
}
/// A notice reaches the reader through the engine where there is one, and is printed where
/// there is not. Getting this wrong writes on the TUI's drawing surface.
#[test]
fn a_startup_notice_goes_through_the_engine_only_where_one_runs() {
let parse = |line: &[&str]| Args::try_parse_from(line).expect("a valid command line");
for engine in
[vec!["luxe"], vec!["luxe", "--headless", "-p", "hi"], vec!["luxe", "loop", "start"]]
{
assert!(parse(&engine).starts_an_engine(), "{engine:?}");
}
for printed in
[vec!["luxe", "doctor"], vec!["luxe", "loop", "status"], vec!["luxe", "auth", "list"]]
{
assert!(!parse(&printed).starts_an_engine(), "{printed:?}");
}
}
/// Environment and the real config directory are process-global; serialize what touches them.
static ENV_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
/// A project whose config starts sessions in plan mode, and an isolated global config.
fn project_that_plans() -> (tempfile::TempDir, tempfile::TempDir) {
let home = tempfile::tempdir().expect("temp home");
std::env::set_var("XDG_CONFIG_HOME", home.path());
std::env::set_var("XDG_STATE_HOME", home.path().join("state"));
for key in ["LUXE_PROVIDER", "LUXE_MODEL", "LUXE_API_KEY", "ANTHROPIC_API_KEY"] {
std::env::remove_var(key);
}
let project = tempfile::tempdir().expect("temp project");
std::fs::create_dir_all(project.path().join(".luxe")).expect("project config dir");
std::fs::write(
project.path().join(".luxe").join("config.json"),
r#"{"agent":{"default_mode":"plan"}}"#,
)
.expect("write project config");
(home, project)
}
/// `agent.default_mode` decides where a session starts; `build` is not worth sending.
#[test]
fn the_configured_default_mode_is_where_a_session_starts() {
let _guard = ENV_LOCK.lock().unwrap_or_else(|error| error.into_inner());
let (_home, project) = project_that_plans();
let settings = crate::engine_setup::AgentSettings::resolve(
project.path().to_path_buf(),
crate::engine_setup::CliOverrides {
provider: Some("lmstudio".into()),
..Default::default()
},
);
assert_eq!(settings.initial_mode.as_deref(), Some(luxe_core::mode::PLAN));
assert!(!settings.review_engine, "an ordinary session is not a reviewer");
std::fs::write(
project.path().join(".luxe").join("config.json"),
r#"{"agent":{"default_mode":"build"}}"#,
)
.unwrap();
let settings = crate::engine_setup::AgentSettings::resolve(
project.path().to_path_buf(),
crate::engine_setup::CliOverrides::default(),
);
assert_eq!(settings.initial_mode, None, "the default needs no switch");
}
#[test]
fn plan_is_a_flag_every_command_line_takes() {
let parse = |line: &[&str]| Args::try_parse_from(line).expect("a valid command line");
assert!(parse(&["luxe", "--plan"]).plan);
assert!(parse(&["luxe", "--headless", "--plan", "-p", "plan it"]).plan);
assert!(!parse(&["luxe"]).plan);
assert!(Args::try_parse_from(["luxe", "--role", "planner"]).is_err(), "--role is gone");
}
/// `--from-pr` names a pull request, and it is one way of choosing a session among three: it
/// cannot be combined with naming a session or continuing the latest.
#[test]
fn from_pr_resumes_by_pull_request_and_excludes_the_other_resumes() {
use crate::engine_setup::ResumeMode;
let parse = |line: &[&str]| Args::try_parse_from(line).expect("a valid command line");
assert!(matches!(
resume_from_args(&parse(&["luxe", "--from-pr", "146"])),
ResumeMode::PullRequest(146)
));
assert!(matches!(resume_from_args(&parse(&["luxe"])), ResumeMode::New));
assert!(Args::try_parse_from(["luxe", "--from-pr", "146", "--continue"]).is_err());
assert!(Args::try_parse_from(["luxe", "--from-pr", "146", "--resume", "abc"]).is_err());
assert!(Args::try_parse_from(["luxe", "--from-pr", "#146"]).is_err(), "a number, no hash");
}
/// `--pr` starts new work on a pull request, so it goes with nothing that picks a session, an
/// issue, or a branch of its own.
#[test]
fn pr_starts_new_work_and_excludes_every_other_start() {
let parsed = Args::try_parse_from(["luxe", "--pr", "142"]).expect("valid");
assert_eq!(parsed.pr, Some(142));
assert!(matches!(resume_from_args(&parsed), crate::engine_setup::ResumeMode::New));
for other in [
&["--from-pr", "142"][..],
&["--continue"],
&["--resume", "abc"],
&["--issue", "7"],
&["--worktree"],
] {
let mut line = vec!["luxe", "--pr", "142"];
line.extend_from_slice(other);
assert!(Args::try_parse_from(line).is_err(), "{other:?}");
}
}
/// What a flag combination is refused with, or `None` when it is allowed.
fn refusal(line: &[&str]) -> Option<String> {
let args = Args::try_parse_from(line).expect("clap accepts the line");
args.validate().err().map(|error| {
let usage = error.downcast_ref::<UsageError>().expect("a refusal is a usage error");
usage.to_string()
})
}
/// `--on-ask` settles what an `ask` becomes where nobody can answer it, so on the two surfaces
/// where somebody does it would read as a policy and do nothing.
#[test]
fn on_ask_is_refused_where_a_person_answers() {
for line in [vec!["luxe", "--on-ask", "deny"], vec!["luxe", "--rpc", "--on-ask", "deny"]] {
let said = refusal(&line).expect("refused");
assert!(said.contains("--on-ask settles what an `ask` becomes"), "{line:?}: {said}");
}
for line in [
vec!["luxe", "--headless", "-p", "hi", "--on-ask", "deny"],
vec!["luxe", "loop", "start", "--on-ask", "deny"],
] {
assert_eq!(refusal(&line), None, "{line:?} has nobody to answer");
}
}
/// `--github-writes` lets an `--rpc` client publish; anywhere else it would read as the agent being
/// allowed to.
#[test]
fn github_writes_is_refused_outside_rpc() {
let said = refusal(&["luxe", "--github-writes"]).expect("refused");
assert!(said.contains("--github-writes lets an --rpc client publish"), "{said}");
assert!(refusal(&["luxe", "--headless", "-p", "x", "--github-writes"]).is_some());
assert_eq!(refusal(&["luxe", "--rpc", "--github-writes"]), None);
}
/// A headless run with nothing to run is refused before anything else happens, a worktree made for
/// it included.
#[test]
fn a_headless_run_needs_a_prompt() {
let said = refusal(&["luxe", "--headless"]).expect("refused");
assert_eq!(said, "--headless requires --prompt <text>");
assert_eq!(refusal(&["luxe", "--headless", "-p", "hi"]), None);
// a subcommand is not a headless run, nor is a session with a person at it
assert_eq!(refusal(&["luxe", "doctor"]), None);
assert_eq!(refusal(&["luxe"]), None);
}