A toy coding agent for joy only.
Oven reads and edits your files, runs shell commands, delegates to subagents and remembers your project between sessions.
Install · Usage · Configuration · Interactive mode · Build from source · License
Warning
Status: not production-ready.
macOS / Linux:
curl -fsSL https://oven.paulden.site/install | bashWindows (PowerShell):
irm https://oven.paulden.site/install | iexNote
/install serves the script matching the caller (PowerShell/ in the
User-Agent selects install.ps1); /install.sh and /install.ps1 still work.
Restart your terminal, then verify with oven --help.
# One-shot query
oven "what does this project do?"
oven -Q "what is love?"
# Interactive TUI
oven
# Pick model / API key
OVEN_MODEL=deepseek-v4-flash OVEN_API_KEY=sk-xxx oven
# Resume a session
oven --session my-session
oven -c # resume the most recent session in this directory
# Work in a different directory
oven -C /path/to/project
# Run without durable memory: no memory tools, nothing recalled into the prompt
oven --amnesia
# List, add and remove provider models without starting the TUI
oven model
oven model add # asks for what the flags leave out
oven model rm xaiRun oven --help for the full CLI.
Oven runs inside your project directory and speaks the OpenAI chat completions
format, so any compatible provider works. The model can read and write files,
run shell commands, and delegate jobs to subagents
(docs/subagents.md).
- Durable memory under
.oven/memory/~/.oven/memory, injected into the system prompt and managed withmemory_read,memory_write,memory_forgetor/memory(docs/memory.md) - MCP servers mounted as
<server>_<tool>(docs/oven-app.md) - Sessions as JSONL files under
~/.oven/sessions/, resumed with-c - The architecture is described in
docs/architectures.md
Config lives in .oven.toml at the project root, or globally at
~/.oven/config.toml (created as a template on first run). Env vars
OVEN_MODEL, OVEN_API_KEY, and OVEN_BASE_URL override it.
oven model manages that file without starting the TUI:
oven model # every configured and shipped model
oven model ls myproxy # just one provider
oven model add # interactive: provider, endpoint, key, model, limits
oven model rm myproxy/my-model # drop one model; `oven model rm myproxy` drops the restoven model add writes to ~/.oven/config.toml and, unless --activate is
passed, leaves the current model selected. Every question is also a flag, so a
script needs no answers at all — a missing required one fails naming it:
oven model add myproxy --base-url https://proxy.example/v1 --api-key sk-xxx \
--model my-model --context-window 200k --max-output-tokens 8k --no-vision| Flag | Meaning |
|---|---|
--base-url |
endpoint; required for a vendor oven does not ship |
--protocol |
completions (default) or responses; unknown vendors only |
--api-key / --api-key-env |
save a key, or read OVEN_API_KEY instead |
--model |
wire id to add |
--context-window, --max-output-tokens |
limits, as 200k or 1m |
--no-tools, --no-vision |
capabilities the model lacks |
--reasoning-effort |
none, low, medium or high |
--activate |
also make this provider and model current |
--no-verify |
skip the one-token check that the key and endpoint work |
--yes |
write without showing the preview |
# Provider in use; every vendor is declared under [providers.<slug>].
active = "deepseek"
tools = ["file_read", "file_write", "bash"]
# Fraction of the model's context window that triggers automatic history
# compaction after a turn completes. 0 disables auto-compaction; /compact
# still works. Ignored when the active model's window size is unknown.
compact_threshold = 0.8
# Provider round trips one turn may take before the loop asks to continue.
max_iters = 200
# How many traces of a workspace are kept: the newest ones, the older ones go.
# 0 keeps them all.
trace_keep = 2
[subagents]
enabled = true
max_concurrent = 4
max_iters = 60
[providers.deepseek]
model = "deepseek-v4-flash"
base_url = "https://api.deepseek.com"
api_key = "sk-xxx"
reasoning_effort = "high"
[providers.xai]
api_key = "xai-xxx"
reasoning_effort = "low"
# Only for a model oven does not ship: the wire id is the table key, and the
# limits are what turn on ctx% display and auto-compaction. Any of those keys
# can instead sit in the provider table itself, as a default for every model
# below it that leaves the field unset.
# [providers.myproxy]
# base_url = "https://example.com/v1"
# api_key = "sk-xxx"
# model = "my-model"
# context_window = 200000
# [providers.myproxy.models."my-model"]
# max_output_tokens = 8192tools— capabilities the agent can invoke (file_read,file_write,bash,glob,grep,web_fetch); an empty list means the defaults.web_fetchreturns a page to the model as markdown.max_iters— provider round trips one turn may take before the loop asks whether to continue;[subagents]tunes delegation (enabled,max_concurrent, and the subagents' ownmax_iters).trace_keep— how many traces a workspace keeps; the newest ones stay and the older ones go, and0keeps them all.active— the canonical vendor slug in use; aliases are accepted on read (grok→xai,kimi→moonshot,glm→zhipu). A known vendor needs onlyapi_key: its endpoint, wire protocol and model catalog come fromoven-llm. A custom vendor also needsbase_url, and may setprotocol(completionsorresponses) to override the default.- a provider table may also carry
context_window,max_output_tokens,supports_system_prompt,supports_tools,supports_streamingorsupports_visiondirectly: they are the defaults every entry under[providers.<slug>.models]inherits wherever it leaves a field unset, so a vendor whose models share one window declares it once. A model that sets a field keeps its own value, and the stored entries stay as written. [mcps]— MCP servers: stdio (command/args/env) or remote streamable HTTP (url/headers); their tools are mounted as<server>_<tool>.AGENTS.md/CLAUDE.mdfrom~/.oven/and the project root are injected into the system prompt.- Skills live in
SKILL.mddirectories under~/.oven/skills/and.oven/skills/(project wins). - Sessions are JSONL files under
~/.oven/sessions/.
Type a prompt and press Enter to send. Esc cancels a running turn, or
rewinds the last exchange when idle. Shift+Tab toggles plan or ask mode and
Ctrl-C quits.
| Command | What it does |
|---|---|
/clear |
New chat (new session, old file kept) |
/exit |
Quit |
/model |
Switch model: /model <id> [none|low|medium|high] |
/setup |
Configure provider: /setup name=... api_key=... |
/plan |
Toggle plan mode: /plan [on|off] |
/agents |
List subagents; /agents <name> opens one, /agents stop <name|all> stops them |
/compact |
Compact conversation history into a summary; auto-compaction triggers at compact_threshold. |
/memory |
List, show or remove memories: /memory [show <ref> | rm <ref>], where <ref> is workspace/<id>, user/<id> or a bare id |
Oven writes a rotating log to ~/.oven/logs/oven.log (10 MiB per file, one backup). The TUI never prints logs to the terminal. Increase verbosity with OVEN_LOG=debug (or RUST_LOG).
cargo build -r
./target/release/ovenMIT.