Modes

The Kodik agent operates in one of five modes. The mode determines what the agent is allowed to do and which tools it can call. The legacy value "act" is normalized to "code" for backwards compatibility.

Code (default)

Code is the task execution mode. It is the default for all new tasks.

Behavior: the agent uses all available tools to understand the codebase, make changes, run commands, and verify results. It operates in a visible task worktree. For browser-rendered work, it can verify the result through the Integrated Browser with preview. If the request is materially ambiguous, it may call ask_questions once before proceeding.

Available tools: shell, command_status, read_file, codebase_search, edit_file, edit_files, edit_notebook, rg, glob, ask_questions, read_lints, web_fetch, todo_write, sub_agent, memory, preview

Tip

Use Code when you need something implemented, refactored, or run.

Plan

Plan is a read-only mode. The agent explores the code, asks clarifying questions if needed, and saves a final plan via the generate_plan tool.

Behavior: the agent does not edit files, create files, or run state-modifying commands. It builds a step-by-step implementation plan, notes risks and open questions, and optionally includes a Mermaid diagram in generate_plan. Questions are only asked through ask_questions — never as plain chat text.

Available tools: read_file, glob, rg, codebase_search, read_lints, web_fetch, sub_agent, ask_questions, generate_plan, memory

Note

After the plan is saved, switch to Code mode to start implementing. See Planning.

Ask

Ask is a strict read-only mode for questions about the codebase: architecture, behavior, tradeoffs.

Behavior: the agent answers questions by reading the relevant code first. It does not run commands or edit files. If the user asks for an implementation, the agent explains that Ask mode is for analysis only and that they should switch to Code.

Available tools: read_file, glob, rg, codebase_search, read_lints, web_fetch, sub_agent, ask_questions, memory

Debug

Debug is a hypothesis-driven debugging mode that separates diagnosis from the fix.

Behavior: the agent follows a strict workflow:

1. Generates 3–5 precise hypotheses about why the issue occurs.
2. Adds targeted instrumentation to distinguish those hypotheses.
3. When necessary, asks the user to reproduce the issue with numbered steps.
4. Collects runtime evidence from logs, command output, and tests.
5. Classifies each hypothesis as CONFIRMED, REJECTED, or INCONCLUSIVE.
6. Implements only the smallest fix supported by confirmed evidence.
7. Verifies the fix with fresh evidence and removes temporary instrumentation.

The agent never declares a fix without actual runtime evidence.

Available tools: shell, command_status, read_file, codebase_search, edit_file, edit_files, edit_notebook, rg, glob, ask_questions, read_lints, web_fetch, todo_write, sub_agent, memory, preview

Caution

Debug and Code have the same tool set, but Debug requires hypotheses and evidence before any change. Do not use Debug for ordinary implementation tasks.

Educator

Educator is a read-only teaching mode built on top of Ask, adding the check_understanding tool.

Behavior: the agent explains concepts progressively, grounds explanations in actual code, and uses worked examples and simple mental models. It may call check_understanding with 1–3 concise questions to tailor the next step of the explanation. Incorrect answers are treated as diagnostic signals, not failures.

Available tools: all Ask tools plus check_understanding

Note

Educator does not modify files. Switch to Code for hands-on implementation.