dex-agents-builtin-cli

dex-agents-builtin-cli provides the dex-agents-builtin command. It runs the Dex built-in agent loop as a durable Dex agent session and chats with it in your terminal. No agent framework is involved: the session's own RunModel Step makes one model call through LiteLLM, and every tool call runs in its own Dex tool Step. The shared CLI core, dex-agents-cli-core, starts or reuses dexcli dev, connects the connectors MCP server, and runs the Worker. This package only builds the built-in loop agent with the core's LiteLLM model client.

Running it

The command needs Python 3.11 or later and a key for the model's provider:

export OPENAI_API_KEY=sk-...
uvx --from dex-agents-builtin-cli dex-agents-builtin

The first run asks the init questions and writes ~/.dex/agents/builtin.yaml. Then type a message at the > prompt. Approve or reject tool calls with y or n, answer the agent's questions, and press Ctrl-D to exit. The session stays in Dex, and the command prints the --resume line that continues it. See the CLI core README for every subcommand and option, and agents/cli for the configuration file.

LiteLLM reads each provider's standard environment variables, such as OPENAI_API_KEY and OPENAI_BASE_URL for openai/ models and ANTHROPIC_API_KEY for anthropic/ models. The command never prints or stores a key.

Configuration

The model defaults to openai/gpt-5.2; set model in the file or pass --model to change it. It is a LiteLLM model name, <provider>/<model>, such as anthropic/claude-opus-5-5. A session's settings may change the model and the instructions; each model call uses the values of its turn. system_prompt replaces the default instructions. The builtin section has no options yet, and any key in it is a configuration error.

Tools

The agent's tools are the CLI core's: its local tool source and the connector tools of the connectors MCP server. Every call runs in its own Dex tool Step, with the CLI core's policy. Reads run at once, file writes and shell commands wait for approval unless the shell allow list has the command, and the file tools stay in the workspace. See the CLI core README for the local tools.

The agent also has two built-in tools that the session runs itself:

• ask_user asks you a question, and the turn waits for your answer.
• write_todos replaces the session's plan, a short task list, with no approval.

Plan mode is on. Use it through the terminal UI (dexcli agents-tui) or the session API, not the plain chat, which sends /plan and /run as ordinary messages. In the terminal UI, /plan <message> starts a planning turn: the agent drafts a plan with write_todos and uses no other tool. /run approves the draft, and the agent runs it with every tool.

The names ask_user and write_todos are reserved, so a connector or local tool with one of these names fails the turn. This is a breaking change for such a tool: rename the conflicting connector or local tool, or use another harness.

Development

Develop with uv 0.12.2. The package resolves dex-agents and the CLI core from this repository by path. uv.lock pins litellm to the version the core's lock pins, and ci.sh checks that. ci.sh installs the locked dependencies, checks lint and types, and runs the tests against a private dexcli dev:

cd agents/cli/python/builtin
DEXCLI=/path/to/dexcli ./ci.sh

The tests run the command in a pseudo-terminal with a private home and an allow-listed environment. LiteLLM sends openai/ models to the scripted Responses API of ../testing; a refused proxy stops any other request. A fake connectors MCP server serves a connector read and write. The tests cover a chat turn and --resume, read_file without approval and write_file after approval, a connector read and an approved connector write that runs once, session settings that change the model, and a key in the builtin section. They also cover a system_prompt set in the session settings, which reaches the next model request, and a rejected file write and connector write, which never run.