copilot-cli-modes

# Copilot CLI Running Modes ## Overview Copilot CLI provides 7 distinct running modes, each optimized for different tasks. Understanding when to use each mode is the key to effective AI-assisted development. Modes can be combined — for example, Plan → Autopilot + Fleet is a common power workflow. --- ## Mode Quick Reference | Mode | Trigger | Autonomy | Modifies Code? | Best For | |------|---------|----------|----------------|----------| | **Interactive** | Default | Low — asks at every step | Yes (with permission) | Day-to-day coding, Q&A, small changes | | **Plan** | `Shift+Tab` or `/plan` | Low — creates plan, waits for approval | No (planning only) | Complex features, multi-file refactors | | **Autopilot** | `Shift+Tab` (cycle) or `--autopilot` | High — works until done | Yes (needs `--allow-all`) | Well-defined tasks, CI, batch ops | | **Fleet** | `/fleet` prefix | High — parallel subagents | Yes | Large parallelizable tasks | | **Research** | `/research` | High — autonomous research | No (report only) | Deep technical investigation | | **Chronicle** | `/chronicle` | N/A — reads history | No | Standups, tips, self-improvement | | **Delegate** | `/delegate` | Full — runs in cloud | Yes (creates PR) | Async work, other repos | --- ## 1. Interactive Mode (Default) ### What It Is The standard back-and-forth mode. You prompt, Copilot responds, you guide the next step. Copilot asks for permission before making changes and checks in with you at decision points. ### When To Use - Day-to-day coding tasks - Quick bug fixes - Single-file changes - Exploratory questions about the codebase - Tasks where you want control at every step ### Usage Scenarios **Codebase onboarding:** ``` How is logging configured in this project? What's the pattern for adding a new API endpoint? Explain the authentication flow ``` **Quick fix:** ``` The login form doesn't validate email format. Fix the validation in src/components/LoginForm.tsx ``` **Git operations:** ``` Create a PR for this branch with a detailed description Rebase this branch against main ``` ### Key Commands - Type your prompt and press Enter - `Shift+Tab` to cycle to other modes - `/model` to switch AI models mid-session - `/clear` or `/new` to start fresh between unrelated tasks ### Tips - Keep sessions focused — use `/clear` between unrelated tasks - Use `/context` to see how much context window you've used - Copilot reads `copilot-instructions.md` automatically --- ## 2. Plan Mode ### What It Is A structured planning mode where Copilot analyzes your request, asks clarifying questions, and produces a detailed implementation plan with tasks and checkboxes — **before writing any code**. Plans are saved to `plan.md` in your session folder. ### When To Use - Complex multi-file features - Refactoring with many touch points - New feature implementation - Any task where you want to review the approach before execution ### When NOT To Use - Quick bug fixes - Single-file changes - Simple questions ### How To Activate - Press `Shift+Tab` to toggle into plan mode (prompts show "plan" indicator) - Or use `/plan` command from normal mode ### Usage Scenarios **Feature planning:** ``` /plan Add OAuth2 authentication with Google and GitHub providers ``` **Refactoring:** ``` /plan Migrate all class components to functional components with hooks ``` **Architecture change:** ``` /plan Extract the payment processing logic into a separate microservice ``` ### What Happens 1. Copilot analyzes your request and codebase 2. Asks clarifying questions to align on requirements 3. Creates a structured plan with checkboxes 4. Saves plan to `plan.md` 5. Waits for your approval before implementing 6. After approval, you can: - **Implement manually** — `Proceed with the plan` - **Implement on autopilot** — "Accept plan and build on autopilot" - **Implement on autopilot + fleet** — "Accept plan and build on autopilot + /fleet" ### Viewing & Editing Plans - `Ctrl+Y` — open plan in your default Markdown editor - `/session plan` — view current plan in CLI ### The Power Workflow: Explore → Plan → Code → Commit ``` 1. Explore: "Read the authentication files but don't write code yet" 2. Plan: /plan Implement password reset flow 3. Review: Check the plan, suggest modifications 4. Build: "Proceed with the plan" (or autopilot) 5. Verify: "Run the tests and fix any failures" 6. Commit: "Commit these changes with a descriptive message" ``` --- ## 3. Autopilot Mode ### What It Is Hands-off autonomous mode. Copilot works through a task without waiting for your input after each step, continuing until the task is complete, a problem occurs, or you press `Ctrl+C`. ### When To Use - Well-defined tasks with clear goals - Implementing a plan you've already reviewed - Batch operations (writing tests, fixing lints) - CI/CD workflows and scripting - Large tasks that require many steps ### When NOT To Use - Open-ended exploration - Tasks requiring nuanced judgment calls - Vague or ambiguous instructions - Tasks where you want to guide each step ### How To Activate - Press `Shift+Tab` to cycle to autopilot mode - Or use `--autopilot` flag from command line - Or accept a plan with "Accept plan and build on autopilot" ### Usage Scenarios **Implement a reviewed plan:** ``` # After creating a plan in plan mode: "Accept plan and build on autopilot" ``` **Programmatic usage (CI/scripts):** ```bash copilot --autopilot --yolo --max-autopilot-continues 10 -p "Write unit tests for all functions in src/utils/" ``` **Batch linting:** ```bash copilot --autopilot --allow-all -p "Run the linter, fix all errors, and commit the changes" ``` ### Permissions When entering autopilot, you're prompted: 1. **Enable all permissions** (recommended) — equivalent to `--allow-all` / `--yolo` 2. **Continue with limited permissions** — auto-denies tool requests needing approval 3. **Cancel** Use `/allow-all` or `/yolo` mid-session to grant full permissions later. ### Safety Controls - `--max-autopilot-continues N` — cap the number of autonomous steps (prevents runaway loops) - `Ctrl+C` — stop the agent at any time - Each continuation shows premium request usage: `Continuing autonomously (3 premium requests)` ### Comparison Table | Flag | What It Does | Autonomy Level | |------|-------------|----------------| | `--allow-all` / `--yolo` | Auto-approves all tool permissions | Still interactive (asks at decision points) | | `--no-ask-user` | Suppresses clarifying questions | Semi-autonomous (no extra premium requests) | | `--autopilot` | Full autonomous execution | Fully autonomous (continues until done) | --- ## 4. Fleet Mode (`/fleet`) ### What It Is Parallel task execution. The main agent acts as orchestrator, breaking a large task into independent subtasks and assigning them to subagents that run simultaneously. Each subagent has its own context window. ### When To Use - Large tasks with multiple independent steps - Writing tests for many modules at once - Refactoring several unrelated files - Updating dependencies across packages - Any parallelizable work where speed matters ### When NOT To Use - Sequential tasks where each step depends on the previous one - Small, focused single-step tasks - Tasks where you need fine-grained control over order ### How To Activate Prefix your prompt with `/fleet`: ``` /fleet Write comprehensive unit tests for all controllers in src/controllers/ ``` ### Usage Scenarios **Parallel test writing:** ``` /fleet Write unit tests for UserService, OrderService, and PaymentService. Each test file should cover happy paths, error cases, and edge cases. ``` **Multi-file refactoring:** ``` /fleet Rename all instances of "userId" to "accountId" across the following directories: src/models/, src/services/, src/controllers/ ``` **Documentation generation:** ``` /fleet Generate JSDoc comments for all exported functions in src/utils/, src/helpers/, and src/lib/ ``` **Using specific agents per subtask:** ``` /fleet Use @tester to create tests for src/auth/. Use @technical-writer to update the API docs in docs/. Use @security-auditor to review src/payments/. ``` **Using specific models per subtask:** ``` /fleet Use Claude Opus 4.5 to refactor the database layer. Use GPT-5.3-Codex to generate the migration scripts. ``` ### Combining with Autopilot The most powerful workflow: Plan → Autopilot + Fleet 1. `Shift+Tab` into plan mode 2. Create a detailed implementation plan 3. Select "Accept plan and build on autopilot + /fleet" 4. Copilot decomposes the plan, runs subtasks in parallel, and works to completion ### Cost Consideration Fleet spawns multiple subagents, each consuming premium requests independently. A `/fleet` task may use more total premium requests than the same task done sequentially. Use `/model` to check your current model's multiplier. --- ## 5. Research Mode (`/research`) ### What It Is A specialized deep-research agent that produces comprehensive Markdown reports with citations. Unlike normal chat (optimized for quick answers), `/research` is optimized for thoroughness — reports can be hundreds of lines with architecture diagrams, code snippets, and citations. ### When To Use - Deep technical investigation - Understanding codebase architecture - Comparing technologies or approaches - Understanding how a library/framework works internally - Cross-repository research ### When NOT To Use - Quick questions ("what does this function do?") - When you need code changes (research produces reports, not edits) - Time-sensitive interactions (research takes longer) ### How To Activate ``` /research TOPIC ``` ### Usage Scenarios **Codebase architecture:** ``` /research What is the architecture of this codebase? ``` → Produces architecture diagrams, component breakdowns, data flow descriptions **Technology comparison:** ``` /research What's the difference between JWT and session-based authentication? Include pros, cons, and when to use each. ``` → Narrative explanation with trade-off tables **Internal patterns:** ``` /research How are feature flags implemented at our organization? ``` → Searches org repos first, maps internal patterns **Deep-dive into a component:** ``` /research How is the session management system implemented in this repo? Trace the full flow from login to token refresh. ``` → Walks through actual code, follows imports, traces call chains **How a technology works:** ``` /research How does React implement concurrent rendering? Show the actual source code and internal architecture. ``` → Fetches real source from GitHub, prioritizes code over docs ### Viewing & Sharing Reports - `Ctrl+Y` — open the latest report in your editor - `/share gist research` — save as a GitHub gist - `/share file research [PATH]` — save to a local file - Reports stored at: `~/.copilot/session-state/SESSION-ID/research/` ### Report Types The agent adapts its output format based on query type: | Query Type | Format | Example | |-----------|--------|---------| | Process/how-to | Step-by-step guide | "How do I add an endpoint?" | | Conceptual | Narrative + trade-offs | "What's the difference between X and Y?" | | Technical deep-dive | Architecture diagrams + code | "How is X implemented?" | **Tip**: Be explicit about the report type you want. "Give me a technical deep-dive into X with architecture diagrams" produces better results than "What is X?" --- ## 6. Chronicle Mode (`/chronicle`) ### What It Is A session history analysis tool. Copilot records every session locally (prompts, responses, tools used, files modified) in a SQLite database. Chronicle reads this history to generate standups, tips, and self-improving custom instructions. ### When To Use - Start of day: generate standup report - Periodically: discover productivity tips - When Copilot keeps making the same mistake: generate corrective instructions - To recall past work: search your coding history ### How To Activate > **Note**: Chronicle is experimental. Enable with `/experimental on` or `--experimental`. ### Subcommands **Standup report:** ``` /chronicle standup /chronicle standup last 3 days ``` → Summarizes recent work: branch names, PR links, status checks **Personalized tips:** ``` /chronicle tips ``` → Analyzes your usage patterns and suggests features/workflows you're underusing **Self-improving instructions:** ``` /chronicle improve ``` → Analyzes sessions where Copilot misunderstood you or there was lots of back-and-forth, then generates custom instructions to fix the patterns **Rebuild session index:** ``` /chronicle reindex ``` → Rebuilds the session store from disk (after deletion, migration, or corruption) ### Usage Scenarios **Monday morning standup:** ``` /chronicle standup last 3 days ``` → "Last Friday you worked on the auth refactor (branch: feat/oauth2), created PR #42, and fixed 3 test failures. Thursday you debugged the payment timeout issue..." **Discovering unused features:** ``` /chronicle tips ``` → "You rarely use plan mode before complex tasks. Try /plan for multi-file changes — models achieve higher success rates with a concrete plan." **Fixing recurring miscommunication:** ``` /chronicle improve ``` → Generates a custom instruction like: "When I say 'fix the tests', I mean fix failing tests only — do not refactor passing tests or add new ones." ### Data Location ``` ~/.copilot/session-state/{session-id}/ ├── events.jsonl # Full session history ├── workspace.yaml # Metadata ├── plan.md # Plans (if created) └── research/ # Research reports ~/.copilot/session-store.db # SQLite index for chronicle ``` ### Session Management - `/session` — view current session info - `/session checkpoints` — view compaction checkpoints - `/session plan` — view current plan - `copilot --continue` — resume last session - `copilot --resume` — pick a session to resume --- ## 7. Delegate Mode (`/delegate`) ### What It Is Offloads a task to Copilot cloud agent, which runs asynchronously and creates a pull request with the results. You can continue working locally while the cloud agent works in the background. ### When To Use - Tangential tasks you don't want to block on - Documentation updates - Refactoring separate modules - Changes to other repositories - Long-running tasks you can review later ### When NOT To Use - Core feature work requiring tight control - Active debugging - Interactive exploration ### How To Activate ``` /delegate PROMPT ``` ### Usage Scenarios **Tangential task:** ``` /delegate Add dark mode support to the settings page ``` → Cloud agent creates a PR while you keep coding locally **Documentation:** ``` /delegate Update the API documentation to reflect the new authentication endpoints ``` **Cross-repo work:** ``` /delegate In the frontend repo, update the API client to use the new /v2/users endpoint ``` ---