Misar IO Docs

Multi-File Compose

Plan-then-execute workflow for AI-driven edits spanning 5 to 20 files — ideal for refactors, feature additions, and cross-cutting changes.

Overview

Multi-File Compose is a structured mode for changes that span many files. Instead of making edits immediately, the agent first produces a numbered plan for your review. Once you approve the plan, it executes the edits file by file — each with a full diff review — keeping you informed at every step.

Activating Compose

Type /compose in the chat input followed by a description of the change:

/compose Extract all authentication logic from pages/ into a new lib/auth/ module

/compose Add OpenTelemetry tracing to every API route handler

/compose Rename UserProfile component to AccountProfile across the entire codebase

Compose is optimized for changes touching 5–20 files. For smaller single-file changes, the standard chat agent is faster. For changes exceeding 20 files, break the work into multiple Compose sessions.

The Plan-Then-Execute Workflow

Survey — The agent uses repo_map, glob, and grep to understand the structure of the relevant codebase sections. No files are modified in this step.

Plan creation — The agent writes a numbered plan listing every file it intends to modify, what change will be made in each, and the order of operations. The plan is presented in the chat for your review.

Example plan output:

1. Create lib/auth/index.ts — new auth module entry point
2. Create lib/auth/session.ts — move session helpers from pages/api/auth.ts
3. Create lib/auth/middleware.ts — move withAuth HOC from utils/auth.ts
4. Update pages/api/auth.ts — replace moved code with imports from lib/auth
5. Update utils/auth.ts — remove withAuth, add re-export for compatibility
6. Update 8 page files — replace direct session imports with lib/auth imports

Approval — Reply with approve, yes, or looks good to proceed. If you want changes to the plan, describe them and the agent will revise before executing.

Execution — The agent processes each plan item in order. For every file change, a diff view opens so you can review and accept or reject before the agent moves to the next file.

Summary — After all items are complete, the agent posts a summary of what was changed, any items that were skipped (e.g., because you rejected a diff), and suggested follow-up actions (e.g., running tests).

Plan Mode Internals

Compose uses the enter_plan_mode and exit_plan_mode tools internally. In plan mode, the agent is restricted to read-only tools and write_plan — it cannot modify files until plan mode is exited. This guarantees that the full plan is visible before any changes are made.

You can use plan mode directly in regular chat without /compose by asking the agent to "plan first, then ask before executing." The agent will invoke enter_plan_mode automatically for complex requests.

Rejecting Individual Steps

You are not locked into accepting every diff. If you reject a file's diff during execution:

  • The agent notes the rejection
  • It continues with the remaining plan items
  • If the rejected file was a dependency of a later step, the agent adapts (e.g., adjusting imports in subsequent files)
  • The final summary lists all rejections so you know exactly what was and was not applied

Ideal Use Cases

Module Extraction

Move a group of related functions or classes from scattered locations into a dedicated module.

Rename / Rebrand

Rename a component, class, or symbol consistently across all usages, imports, and tests.

Pattern Migration

Replace a deprecated pattern (e.g., class components → hooks, callbacks → async/await) across the codebase.

Feature Addition

Add a cross-cutting feature (logging, tracing, feature flags) to many existing files.

Dependency Upgrade

Update call sites after a breaking API change in a library you depend on.

Configuration Reference

| Setting | Type | Default | Description | |---------|------|---------|-------------| | misar.composeMaxFiles | number | 20 | Maximum number of files a single Compose session will edit | | misar.composePauseForApproval | boolean | true | Require explicit approval of the plan before execution begins | | misar.autoAcceptChanges | boolean | false | Skip per-file diff review during Compose execution (use with caution) |