A bounded task, with relevant context.
mce combines your task description with selected text files and optional image attachments and sends the request to your configured provider. A focused set of inputs makes it easier to assess whether the response addresses the actual problem.
- Confirm provider compatibility. Check both the endpoint and model for the intended work. Image input needs image support; structured file or shell proposals need compatible structured outputs; agents and independent reviewers need native function calls.
- State a verifiable outcome. Explain what needs to change, what must remain stable, and how you will check the result. Include the files that establish the relevant behavior.
- Choose the level of delegation. Use analysis for explanations, reviewed patches for file changes, or a shell workflow for explained command proposals and revisions. Choose an agent when the task needs several coordinated tool-assisted steps.
- Inspect before relying on the result. Compare the response with the source, examine proposed edits or commands, and run appropriate tests. A plausible explanation is not evidence that a change is correct.
Planning can prepare a proposed next-step prompt before the main request. Review or edit that plan when the task is broad or its constraints need clarification.
Separate a proposal from a write.
Patch workflows propose line-based changes across existing or new text files. Include the existing files you want changed so the proposal can be compared with their original content, and describe the intended behavior and constraints.
A unified diff shows removed and added lines alongside surrounding text. Review that comparison, request revisions when necessary, and select the accepted version before writing it.
- Copy-based output. Standalone patch mode writes separate, suffixed copies by default. This leaves the original files available for comparison.
- Reviewed source updates. Approved existing-file changes normally use the original paths in review-enabled workflows unless copy output is explicitly selected.
- Git-backed changes. A dedicated patch branch can hold accepted edits as commits, keeping them separate from your main development branch until you decide to merge.
- Saved proposals. Validated patch manifests and diffs are retained in session state, including proposals you decline. Inspect a saved patch against current files before applying it later.
Copy-based standalone patch behavior is not the default for automatic agents. Confirm the agent approval policy and output destination before assuming that original files will be preserved.
Review the command, then inspect the result.
A shell workflow turns a task into explained command proposals. Examine their intent and effects, request revisions, and use recorded execution output to guide follow-up work.
- Confirm the scope. Check the working directory, permitted writes, and any effects on services beyond the workspace. Avoid running the assistant as root.
- Bound execution separately. Per-command time limits are distinct from API request timeouts. Shell socket restrictions also have a different scope from provider requests, trusted hooks, and the outer containment service.
- Keep useful evidence. Command output and optional execution traces are retained in session state. Traces may expose credentials or file contents; inspect them before sharing.
- Resume intentionally. Previously recorded output can be reused instead of rerunning completed commands. Unattended resumption can still execute saved command proposals, so review the selected history and execution policy first.
Approval is not isolation. A command can affect host services or disclose readable data even when filesystem writes are restricted. Combine review with narrow permissions and an environment appropriate for the task.
A controller, tools, and optional independent reviews.
An agent can read files, make patches, run shell commands, delegate focused proposals to specialized workers, and track tasks across multiple turns. Both the endpoint and selected model must support native function calls.
Decide the execution policy first. Tools run without confirmation by default, and automatic patches normally update source files. Choose agent review to approve tool calls and inspect patch diffs before execution. Automatic runs require an explicit selection of suffixed copies to preserve originals; a suffix stored only in a profile is ignored. Noninteractive operation alone does not disable execution.
Self-adjusting support is opt-in
Context assist and prompt assist are disabled by default. Enable either reviewer on its own interval measured in agent turns, using the active request settings or an independent configuration profile, reasoning effort, and model. Each reviewer also needs native function-call support from its own endpoint and model.
- Context assist. Returns advisory progress guidance and can request targeted removal of stale turns or unchanged file context. Removing turns preserves loaded files; file removals affect context only, never disk. These removals retain newer turns and changed or newly loaded files. The reviewer can also refresh or clear summaries, skip the next scheduled context review, or request compaction as a last resort.
- Prompt assist. Replaces named in-memory controller, worker, tool-call, task-priority, summary, reviewer, and selected worker-profile instructions. A short history of replaced prompts helps it revisit earlier wording. Stored configuration, prompt-library files, and worker profiles remain unchanged; runtime checkpoints preserve active adjustments and prompt history for resumption.
- Independent request settings. A named reviewer configuration profile supplies its own endpoint, credentials, token limits, pricing, and API-side storage rather than inheriting controller request overrides. An API-key environment setting can still override its stored key. Reviewer reasoning and model choices can be set separately.
Reviews make additional API requests alongside controller requests, with successful results applied before a later turn. The serialized controller request may be truncated to fit the reviewer's token limit, and selected image attachments also accompany review requests. Budget for the extra usage and authorize sharing with every selected provider.
Keep longer runs recoverable
- Working context. Available text-file context refreshes from disk before later requests. Unpinned files and history expire by turn count; directly selected files are pinned on a fresh run, unlike file-list or profile inputs. Pins do not prevent token-pressure compaction or targeted context-assist removal. Automatic summaries are compressed records, not proof of execution.
- Optional snapshots. Directory backups are off by default. When enabled, snapshots run at startup and are checked before later turns, not by a continuous background timer. Keep destinations outside all source directories and grant them writes when contained. Snapshots include hidden files and are not part of expired-session cleanup.
- Specialized workers. Named worker profiles produce patch, shell, or custom-schema proposals while the controller coordinates the overall task. Worker profiles are separate from the configuration profiles used for provider settings.
- Checkpoint continuity. A resumed agent starts a new session linked to saved history. Available runtime checkpoints can recover interrupted turns as well as completed work, restoring task and context state, active prompts and recent replacement history, worker profiles, trusted hook selections, pending revisions, reviewer scheduling, and cumulative statistics.
- New-run choices. Explicit prompt overrides take precedence; explicit worker-profile or hook selections replace the saved selections. Provider settings, image attachments, approval policy, and permissions still come from the new run. Recorded context-file checksums are verified by default; retain referenced source sessions.
A checkpoint is a recovery record, not a rollback or a continuation of an in-flight API request. Inspect current files and external command effects before allowing more automatic work.
Reuse instructions without losing the record.
Compose task instructions in a file, through standard input, or in your editor, and reuse common guidance from the prompt library. Inherited configuration profiles keep shared provider settings in one place while task-specific profiles store their differences.
Control the request
- Use ordinary file context for relevant text files rather than unrelated project material. Text files above the configured size limit are skipped.
- Attach images separately only when both the endpoint and model support them. Original image bytes, including any embedded metadata, are base64-encoded without resizing, conversion, or other processing. Text-file size limits do not apply to these attachments.
- Estimate serialized text and tool-schema tokens without making a model API request, then inspect actual provider usage. Image tokens are excluded from estimates and estimated input-limit checks. Text estimates can also differ from actual usage; monetary estimates depend on current provider pricing and matching model settings.
- For repeated work across a file tree, preview include and exclude filters before running separate parallel requests. Responses are saved separately from source files, and any selected image attachments accompany every per-file request. Saved progress and combined Markdown reports help review the batch.
- Choose readable text, streamed text where supported by the workflow, JSON, or schema-constrained output. Save a response to a file when another process needs to consume it; selecting an existing output path overwrites that file.
Return to saved work
Task-based session state preserves task context, responses, patches, and shell output independently of ordinary log settings. The quick-question workflow does not create resumable state.
Resuming creates a new linked session and verifies recorded context-file checksums by default. Agents can also recover from available runtime checkpoints from interrupted turns, including saved prompt adjustments and reviewer scheduling. Confirm the new run's provider, image attachments, approvals, permissions, and any explicit prompt, worker-profile, or hook selections. Recovery does not undo file writes or command effects; inspect current state and keep referenced source sessions.
Local logging and requested API-side storage are enabled by default, but provider retention follows the provider's policy. Local logs, saved state, and provider-side storage have separate controls. Disabling local logging neither removes saved state nor controls provider retention.
Know what containment does—and does not do.
The Linux containment wrapper runs the assistant inside a transient systemd user service to restrict filesystem writes. The project directory is not writable automatically. Grant access only to the paths needed for the task; assistant state and private temporary directories remain writable under the default policy.
- Write limits are not data isolation. Host files and credentials may remain readable, and Unix sockets may provide access to host services. Do not assume a contained process is unable to disclose data.
- Tool approval is a separate boundary. Review determines which proposed actions you accept; containment limits writable locations. Avoid running the assistant as root, and inspect commands for effects beyond the project.
- Network policies have different scopes. Shell commands can create only Unix sockets by default. Allowing other socket families changes that restriction, but the shell policy does not govern provider requests or hook scripts. The outer service and separately launched shell services also have distinct network policies.
- Hooks require trust. Context hook executables run directly, without tool-call review or the shell tool's timeout and socket restrictions. When the wrapper is used, hooks still inherit its outer containment. An agent runtime checkpoint can restore hook selections on resumption, so inspect those selections as well as the executables.
- Context may be shared with more than one provider. Only send text, image attachments, and hook output you are authorized to share with the main provider and any independent reviewers. Inspect logs, saved state, backups, and traces for sensitive content before sharing them.
Containment reduces where writes are permitted; it is not complete isolation or a guarantee against data leaks. Use an appropriately isolated environment for untrusted tasks, alongside review and narrowly scoped permissions.