Plan & Act

Plan and Act are two agent modes in Kodik, described on the Modes page. They structure work: first understand and plan, then implement.

Plan Mode

In Plan mode Kodik is read-only. It will not edit files, run mutating commands, or create files — even if you ask it to. Only read and analysis tools are available: read_file, glob, rg, codebase_search, read_lints, web_fetch, plus sub_agent and ask_questions.

The output of Plan mode is a structured plan artifact created via the generate_plan tool. If a Mermaid architecture diagram would materially help, the agent includes it.

Workflow inside Plan mode

1. Kodik reads and analyzes the relevant code.
2. If the request is materially ambiguous, it calls ask_questions exactly once.
3. It breaks the work into small actionable steps ordered by implementation sequence.
4. It calls out risks, assumptions, and open questions.
5. It calls generate_plan exactly once to save the final plan artifact.

Plan mode does not allow ordinary chat text: questions only via ask_questions, the final plan only via generate_plan. No intermediate status messages.

Plan panel

After generate_plan is called, Kodik automatically opens a dedicated plan-review tab. Chat keeps a short confirmation while the tab renders the Markdown, task list, and (if present) Mermaid diagram; it is not an unsaved .md file in the editor.

Act Mode (Code / Act)

Once the plan is ready, switch to Act mode. All agent tools are available — file editing, terminal commands, file creation. Context from the planning session is preserved.

Typical workflow

1. Start the task in Plan mode.
2. Describe the goal; Kodik explores the codebase.
3. Answer any clarifying questions if prompted.
4. Review the generated plan in the plan panel.
5. Switch to Act mode — Kodik executes the plan.
6. If unexpected complexity arises, switch back to Plan to refine the strategy.

Best Practices

Planning phase

• Provide context up front: requirements, constraints, key files.
• Use @Mentions to point Kodik at important files explicitly.
• Let Kodik finish reading code before it forms the plan.

Implementation phase

• Follow the plan; switch back to Plan mode if the approach needs adjustment.
• Use Checkpoints to snapshot state before large changes.
• Track progress via the Task list.

When to use each mode

Plan mode works best when:

• the approach to a task is not obvious
• you need to understand a complex bug before fixing it
• you are making architectural decisions that affect multiple parts of the codebase

Act mode is ideal when:

• a plan is already in place
• you are making routine changes with a clear approach
• you are running tests or minor adjustments