denree — an autonomous AI agent that accomplishes a goal by running the terminal's commands, reasoned by a local LLM (WebGPU, 100% in-browser)
SYNOPSIS
denree "<goal in natural language>" denree (asks for the goal interactively) denree --commands denree --model <id> "<goal>" denree [--steps n] [--candidates n] [--rounds n] [--fast] "<goal>" denree --unload
DESCRIPTION
denree (a nod to "la Denrée", the alien from the film La Soupe aux Choux) is a reasoning agent: you give it a goal and a language model running entirely in your browser (WebGPU, no server) works it out through a small reasoning graph, shown live as a tree:
- plan: a first split of the goal into sub-questions — a hint, not a fixed script;
- decide → act → reflect, in a loop: the model picks the next command seeing every fact gathered so far (so one result can feed the next command, e.g. checkip finds your city, then weather <city>), the command runs, and the model extracts its facts — or, with the command's manual in view, explains what went wrong so the next decision can fix it. A lookup (help -k <keyword>, man <command>) skips that check: its output is kept as-is for the next decision, so the agent can find a command it did not think of, then use it (its manual then joins the context);
- synthesize: an answer is drafted from the facts;
- critique: only when the investigation did not settle the goal (or with --candidates > 1), the draft is scored against the facts; if something is missing, one more command is run and the answer re-synthesized;
- answer: the best-scored draft wins.
A small local model is slow, so the agent spends calls only where they help: a short, single-part goal skips the plan, and a settled investigation goes straight to one answer — about 4 to 5 model calls for a simple question. Every prompt is kept within the model's context window (manuals, then lookups, then the oldest facts are trimmed first) and every generation has a length cap.
denree adapts to the model loaded in the browser: every budget is derived from that model's context window (4k tokens for most builds, 1k or 2k for some — shown at the top of the tree), and the characters-per-token estimate is measured on each call from the token counts the engine reports. In a small window the command list shrinks to names only, and outputs, manuals and facts are cut shorter. Should a prompt still overflow, it is rebuilt from the exact token count and retried once.
Every decision is constrained to JSON by the engine (grammar-guided generation). Every call starts with the same system prompt: the model is told it runs in the visitor's browser, inside LudOS — a simulated Linux environment whose shell commands it is free to use to answer — and that help -k <keyword> finds the commands whose manual mentions a keyword (plain help would only repeat the list it already has). It also receives the whole catalog of usable commands (denree --commands) and the manuals of the most relevant ones. Commands with side effects, endless or heavy ones (rm, su, msg, open, dl, top, hashcat, httperf, todo, say, the LLM commands…) are blocked for safety, and interactive commands get no keyboard input.
The model comes from the central LLM module (see llm and the widget in the top-right corner). By default no model is loaded: denree proposes a reasoning model and asks you to confirm its download — unless a model is already warm, which it reuses instantly. Ctrl+C interrupts it.
OPTIONS
--commands, --list list the commands the agent may use --model <id> pick the reasoning model (default: Qwen2.5-1.5B) --steps <n> max decide → act → reflect steps (1–30, default 12) --candidates <n> answers drafted, then ranked by a critique (1–5, default 1) --rounds <n> critique/refinement rounds when the goal is not settled (0–4, default 2) --fast 6 steps, one candidate, no critique round (quicker) --unload, --stop free the loaded model from GPU memory
EXAMPLES
denree "what is my public IP address and its country?" denree "summarize the file about.md in one sentence" denree --steps 20 "search for the word 'drone' in my documents" denree --fast "what time is it?" denree --model Qwen2.5-3B-Instruct "what's the weather in Rennes?" denree --unload