Dext

Dext is a single-binary Rust coding agent that runs from your terminal, keeps project-scoped session state, and gives the model a small set of native tools for filesystem, search, shell/data, HTTP, Git, and task tracking.

Dext is source-first: prompts, runtime state, tool policies, provider wiring, and the TUI live in this repository with no external service required beyond whichever model provider you authenticate.

Highlights

• Interactive terminal agent with an inline ratatui TUI; no alternate-screen takeover.
• One-shot mode for scripted tasks and JSON/stream-JSON output for automation.
• Provider catalog with built-in GLM, ChatGPT/Codex, OpenAI, Anthropic, DeepSeek, and local OpenAI-compatible profiles plus env/catalog overrides.
• OAuth/API-key auth flows stored outside the repo under Dext state directories.
• Lean default tool schemas and smaller default toolset, with optional full schemas/full toolset and frugal context mode.
• Project-scoped latest sessions, named session export/analyze/grep/failure/verification helpers.
• Permission and sandbox profiles for read-only, workspace-write, and explicit danger modes.
• Eval harness, release tests, and a PTY-backed TUI smoke test.
• Git-native safety helpers: pre-mutation checkpoints, /undo/dext undo, mutation previews, and explicit memory-file merge-driver registration.

Install

Requires Rust stable with edition 2024 support.

git clone https://github.com/SiliconState/Dext.git
cd Dext
cargo install --path . --force

Then run:

dext --help
dext

For local development without installing:

cargo run -- --help

Quick start

Authenticate a provider:

dext auth providers
dext auth login chatgpt          # ChatGPT/Codex OAuth
dext auth login glm <api-key>    # ZAI GLM key
dext auth login openai <api-key> # OpenAI Platform key
dext auth login anthropic <api-key>
dext auth login deepseek <api-key>
dext auth provider local        # local llama.cpp/Qwen on 127.0.0.1:8080, no key
# Dext probes llama.cpp runtime context on startup; fallback local budget is 32K tokens.
# local model choices: qwen2.5-coder-7b or qwen3.5-9b

Start an interactive session:

dext

Run a one-shot task:

dext "summarize this repository"

Read a prompt from stdin:

printf 'explain Cargo.toml\n' | dext -p

Use low-token mode:

dext --frugal --effort off
# even smaller local mode:
dext --context-mode tiny --effort off
# or inside Dext:
/context tiny
/effort off

The default provider-visible toolset hides specialized tools (jq, fzf, awk, git_log, csvkit). Use dext --toolset full, DEXT_TOOLSET=full, or /tools full only when you need the complete catalog.

Common commands

CLI:

dext --resume
dext --fork
dext sessions
dext session export latest html dext-session.html
dext session analyze latest
dext undo --list
dext memory check
dext pack list
dext pack inspect autoresearch
# or inspect SkillOpt-style pack/skill optimization
dext pack inspect packopt
dext pack run autoresearch "optimize the benchmark in this repo"
dext --eval

Interactive slash commands:

/help
/providers
/provider chatgpt
/models all
/login chatgpt
/model local/qwen2.5-coder-7b
# or: /model local/qwen3.5-9b
/approval ask|auto-read|auto-write|never|always
/sandbox-profile read-only|workspace-write|danger-full-access
/context standard|frugal|tiny
/tools default|full
/tool-profile lean|full     # default is lean
/preview off|simple|git
/undo --list
/undo
/compact status
/pack list
/pack inspect autoresearch
/pack inspect packopt
/pack run autoresearch optimize the benchmark in this repo
/save name
/export html path
/sessions analyze|grep|failures|verify-log|decisions

Persistent local services

Dext treats each bash call as atomic: commands run in a dedicated process group and that group is cleaned up after the shell exits, times out, or is interrupted. Do not expect cmd &, nohup, or disown to keep servers alive across tool calls. setsid-style detaches are unsupported because they escape Dext cleanup.

Prefer static files or one-shot commands when possible. If the user explicitly needs a long-lived local service, use the host OS supervisor and clean it up when finished. On Linux with systemd:

systemd-run --user --unit=dext-preview --same-dir python3 -m http.server 8000
systemctl --user status dext-preview
journalctl --user-unit dext-preview -n 100 --no-pager
systemctl --user stop dext-preview

Use dext- prefixes for agent-started units so they are easy to inspect and stop (systemctl --user list-units 'dext-*'). On macOS/Windows or Linux without systemd, use the platform's native supervisor if needed; otherwise avoid persistent background processes.

Git safety and memory merging

Dext creates lightweight Git checkpoints before approved write-risk tool calls when the sandbox root is inside a Git repository, with direct file mutations receiving path-specific restore hints. Checkpoints live under hidden refs (refs/dext/checkpoints/) with local manifests in .dext/checkpoints/. They are best-effort safety snapshots for Dext edits; they do not replace normal commits, and they do not cover arbitrary external side effects.

Use undo commands to inspect or restore checkpointed paths:

dext undo --list
dext undo --preview <checkpoint-id>
dext undo --apply <checkpoint-id>
dext undo --prune

In an interactive session:

/undo --list
/undo                 # preview latest checkpoint
/undo --apply         # restore latest checkpointed worktree paths
/undo <id>
/undo <id> --apply
/undo --prune

Normal undo restores worktree paths and never silently moves HEAD. The CLI's explicit --reset-head mode is only for cases where you intentionally want a checkpoint to move the current branch state.

Mutation previews show capped diffs for direct file-writing tools before an approval prompt:

dext --preview off|simple|git
DEXT_MUTATION_PREVIEW=simple

Inside Dext:

/preview              # status
/preview simple
/preview off

git preview mode is accepted for forward compatibility and currently falls back to simple in-memory previews.

Dext can also register section-aware Git merge drivers for its memory files:

dext memory check
dext memory register
dext memory unregister
# used by Git after registration:
dext memory merge [--recall] <base> <ours> <theirs> [marker-size] [path]

Registration is local-only by default: it writes repository-local Git config and local attributes. Use dext memory register --versioned-attributes only when you want .gitattributes entries committed for the project. dext memory merge is the Git merge-driver entry point and is not normally run by hand. The merge driver covers MEMORY.md and recall.md and is explicit; Dext does not silently edit Git config or attributes during normal agent runs.

Packs

See docs/PACKS.md for the full packs and shelves reference, including structure, discovery, building, and distributing packs.

Packs are source-first workflow bundles with a PACK.md. Dext discovers packs from DEXT_PACK_<NAME>_DIR, project .dext/shelves/<shelf>/packs, .dext/packs, packs, DEXT_SHELVES_DIR, DEXT_PACKS_DIR, user ~/.dext/shelves/<shelf>/packs, ~/.dext/packs, and bundled repository packs. Shelf packs take precedence over same-named legacy project/user pack directories within the same scope. Typed shelf manifests named shelf.json are loaded from the same shelf roots into the runtime ShelfRegistry and exposed in prompt context plus /shelves / dext shelves as provider-neutral ability metadata.

The default installation target for reusable packs is user-global Dext scope: ~/.dext/packs/<name>/ for legacy packs or ~/.dext/shelves/<shelf>/packs/<name>/ for shelf packs. Use project-local packs/<name>/, .dext/packs/<name>/, or .dext/shelves/<shelf>/packs/<name>/ only when the user explicitly asks for repo-scoped behavior.

The stable extension contract is intentionally provider-neutral: a pack is files plus instructions that any LLM/provider can read, with optional shell helpers and phooks.json steering. Scaffold reusable packs in user-global Dext scope by default (~/.dext/packs/<name>/PACK.md or ~/.dext/shelves/<shelf>/packs/<name>/PACK.md), keep helper scripts inside that directory, and validate with dext pack inspect <name> plus a real dext pack run <name> ... on a disposable task. Use project-local packs/<name>/PACK.md or .dext/... variants only when the user explicitly wants the pack tied to one repository. Use packopt for SkillOpt-style improvement of pack/skill documents with bounded edits, strict held-out validation, and rejected-edit memory. Shared shelves live at <shelf>/packs/<pack> and can be distributed through project, user, or DEXT_SHELVES_DIR paths without adding provider-visible tools. shelf.json manifests add typed ability metadata for internal registry resolution; the runtime lists and prompt-injects those records without expanding the provider-visible tool list.

Invoke a pack conversationally:

run autoresearch on improving this project benchmark
run packopt on improving ~/.dext/packs/autoresearch/PACK.md against held-out tasks

Or invoke it explicitly:

/pack run autoresearch improve this benchmark
/pack run packopt improve ~/.dext/packs/autoresearch/PACK.md against held-out tasks

CLI equivalents:

dext pack list
dext pack inspect autoresearch
dext pack inspect packopt
dext pack run autoresearch "improve this benchmark"
dext pack run packopt "improve ~/.dext/packs/autoresearch/PACK.md against held-out tasks"
dext --pack autoresearch "improve this benchmark"
dext --pack packopt "improve ~/.dext/packs/autoresearch/PACK.md against held-out tasks"

If a pack has phooks.json, Dext activates those hook templates for that invocation and passes DEXT_PACK_DIR plus DEXT_PACK_<NAME>_DIR to hook processes. Shelf packs use the same invocation path and remain regular source directories.

Configuration and state

Dext reads .env for local development if present, but .env is ignored and must never be committed. Prefer dext auth login ... for credentials.

Useful environment variables:

DEXT_PROVIDER=local
DEXT_MODEL=qwen2.5-coder-7b
DEXT_BASE_URL=http://127.0.0.1:8080
DEXT_THINKING_EFFORT=off
# Experimental: force well-formed tool calls on local llama.cpp (opt-in).
# Constrains generation with a GBNF grammar so small models cannot emit a
# tool call with empty/dropped arguments. Off by default; validate against
# your llama.cpp build before relying on it, as it forces a tool call.
DEXT_LLAMA_TOOL_GRAMMAR=1
# or cloud:
DEXT_PROVIDER=chatgpt
DEXT_MODEL=gpt-5.3-codex
DEXT_BASE_URL=https://example.test/v1
DEXT_API_KEY=...
ZAI_API_KEY=...
ANTHROPIC_API_KEY=...
OPENAI_API_KEY=...
DEEPSEEK_API_KEY=...
CHATGPT_ACCESS_TOKEN=...
DEXT_HOME=~/.dext
DEXT_SESSIONS_DIR=~/.dext/sessions
DEXT_LOGS_DIR=~/.dext/logs
DEXT_APPROVAL=ask
DEXT_TRUST=0  # opt out of default startup trust mode
DEXT_SANDBOX_PROFILE=workspace-write
DEXT_CONTEXT_MODE=standard
DEXT_TOOLSET=default
DEXT_TOOL_PROFILE=lean
DEXT_MUTATION_PREVIEW=simple
DEXT_BUDGET_CAP=$5
# Optional pricing overrides in USD per million tokens:
DEXT_INPUT_USD_PER_MTOK=1
DEXT_OUTPUT_USD_PER_MTOK=5
DEXT_CACHE_READ_USD_PER_MTOK=0.1
DEXT_CACHE_CREATE_USD_PER_MTOK=1.25

Runtime state and credentials live outside version control. Project-local runtime directories such as .dext/, target/, .env, DEXT.todo.json, autoresearch.*, packopt.*, and dext-session-* exports are ignored.

Usage metrics are recorded in session headers and /usage after provider turns. Cloud providers use returned usage objects when available; OpenAI-compatible streaming requests ask for usage chunks, while local llama.cpp derives exact prompt/cache/output counts from streamed timings and records zero dollar cost unless pricing env overrides are set.

Development

cargo fmt
cargo build --release
cargo test --release
cargo test --release --test tui_smoke -- --nocapture
cargo install --path . --force

Use the TUI smoke test after changing src/tui.rs.

Repository map

• src/main.rs — agent loop, tool execution, CLI, slash commands, evals, orchestration.
• src/git_checkpoints.rs — Git-native pre-mutation checkpoints, hidden recovery refs, undo preview/apply support.
• src/mutation_preview.rs — capped in-memory diffs for direct file-tool approval prompts.
• src/memory_merge.rs — explicit Git merge-driver helpers for MEMORY.md and recall.md.
• src/provider.rs — provider catalog, auth, OAuth/API-key handling, request shaping.
• src/session.rs — session persistence, project state paths, logs, lock cleanup, terminal restore.
• src/tools.rs — tool catalog and provider-facing tool schemas.
• src/tool_policy.rs — validation and command/external-source guardrails.
• src/orchestrator.rs — turn telemetry, dedupe, circuit-breaker, and workflow guards.
• src/tui.rs — inline terminal UI.
• src/packs.rs — pack discovery, loading, and invocation.
• src/shelves.rs — shelf registry with typed manifests and abilities.
• tests/ — integration tests and replay fixtures.
• benches/ — criterion benchmarks.
• DEXT.md / recall.md — prompt-facing project guidance and recall for Dext working on itself.
• MEMORY.md — durable project memory.
• docs/PACKS.md — packs and shelves reference.

More detail: docs/ARCHITECTURE.md, docs/USAGE.md, SECURITY.md, and CONTRIBUTING.md.