Built-in agent harness

Chat with a local model that can read your workspace, use tools and ask for approvals. Start in Terminal; Desktop integration is experimental and off by default.

Start a harness chat

Install Rapid-MLX with Python 3.11 or newer. Open Terminal in the folder you want to work on:

rapid-mlx chat --harness

The usual model selection and startup flow still applies. First use downloads the model; the harness displays model-loading progress. Model inference stays local. Regular rapid-mlx chat keeps the legacy chat flow unless you set RAPID_MLX_CHAT_HARNESS=1.

To use an existing server and resume a named profile:

rapid-mlx serve mlx-community/Qwen3.5-4B-MLX-4bit --port 18800
# In another terminal:
rapid-mlx chat --harness --base-url http://127.0.0.1:18800 --profile dogfood
# Later:
rapid-mlx chat --harness --base-url http://127.0.0.1:18800 --profile dogfood --resume last

The workspace is fixed from the launch directory when creating or resuming a conversation. Local history lives under ~/Library/Application Support/Rapid/chat/<profile>/. The local owner can survive CLI exits and stops after five idle minutes.

Tools and attachments

• read_file, grep and glob inspect the workspace without approval. Built-in reads refuse paths outside it, secret-like paths and symlink escapes.
• write_file and patch edit files; terminal runs commands; execute_code runs Python. /undo reverses the last file edit only if it has not since changed; it cannot reverse shell or Python effects.
• /attach PATH explicitly shares a snapshot of a selected file, including outside the workspace. Text extraction supports code, PDF text, DOCX, XLSX/CSV, PPTX, JSON/YAML and HTML. Scanned PDFs without text are unsupported. Files are limited to 20 MiB, extracted text to 1 MiB.
• Attach PNG, JPEG, WebP or GIF to a vision-capable model. Only the current message's images are sent; older images become placeholders.
• Weather, web search and web_fetch are available by default to tool-capable models. They send requests externally; fetching does not ask for per-domain approval. Providers may throttle or return no useful results.
• The built-in delegate_task tool gives a helper a fresh task context using the same local model, workspace and approval policy. Helpers cannot delegate again.

Approvals and execution boundaries

Ordinary workspace edits and commands without dangerous patterns run immediately by default. Destructive actions, privilege changes, remote execution/uploads and repeated side effects on regenerated or edited branches require approval. Network clients such as curl, wget and ssh, and recognized Python network access, trigger approval heuristics.

y allows once; a, when offered, allows the exact tool and arguments for this conversation; n denies and N adds a denial reason. Dangerous actions never offer a. Unanswered approvals expire after 120 seconds and noninteractive input denies them. Ctrl-C cancels a pending approval or kills the running command's process group.

# Ask before every action tool:
rapid-mlx chat --harness --approvals always
# Disable writes, patching, terminal and Python execution:
rapid-mlx chat --harness --no-action-tools

Equivalent owner environment settings are RAPID_MLX_CHAT_APPROVALS=always and RAPID_MLX_CHAT_ACTION_TOOLS=0. A client's settings cannot relax a stricter owner policy.

Terminal commands are not sandboxed. Terminal and Python programs run with your local account's access to files and resources. Pattern checks are heuristics, not an OS sandbox.

The terminal inherits only PATH, HOME, USER, LOGNAME, LANG, LC_*, TERM, SHELL and TMPDIR, with PWD set to the workspace. RAPID_MLX_HARNESS_TERMINAL_ENV can allow additional named non-secret variables; secret-like names and URL credentials are excluded. This restricts accidental inheritance, not what a running program can access. The default command timeout is 120 seconds (maximum 600).

For offline use, start a new profile owner with web tools disabled:

RAPID_MLX_CHAT_WEB_TOOLS=0 rapid-mlx chat --harness --profile offline

An already-running owner keeps its startup environment. Disabling web tools does not sandbox terminal networking. After interrupted actions, inspect effects before approving another attempt: unfinished dispatches are marked outcome_unknown and never automatically replayed.

Long tasks and context

Use /context to inspect limits, /compact [instructions] to summarize, /new for a fresh conversation, and /history to resume. /export [PATH] saves a transcript; /help lists commands.

The default context limit is the smallest of the model's native window, serving limit and 32,768 tokens. Read narrow file ranges, limit command output, and compact before filling the window. Small models may stop using tools in long chats; compaction and prefix caching cannot expand the context window. See the long-task context guide.

Desktop: experimental, off by default

Enable Built-in Agent Harness in Desktop Settings for new chats. The 1.0 integration is experimental and supports image inputs. Desktop allows up to eight images per message. Leave the toggle off to use the familiar chat flow.

Release sources and next steps

1.0 launch walkthrough · CLI reference · Connect a coding agent · Engine README at v1.0.0