Planning Mode

Planning mode lets Kavi decompose broad goals into dependency-aware task graphs before execution. Instead of sending a complex prompt directly to one agent, Kavi first asks the planner to structure the work.

When Planning Helps

• Multi-step features that span backend and frontend
• Tasks that have natural dependency ordering
• Goals where parallel execution would speed things up
• Work that needs coordination between Codex and Claude

Planning Modes

In the TUI composer, press Ctrl+P to cycle:

From the CLI:

# Force planning
kavi task "Build the auth system" --plan

# Skip planning
kavi task "Fix the typo in README" --direct

How Planning Works

1. Planner task: Kavi sends your prompt to Codex as a planning task
2. Graph materialization: Codex produces a structured execution graph with:
   • Task keys and titles
   • Owner assignments (codex/claude)
   • Dependencies between tasks
   • Execution modes (blocking, parallel, follow_up)
   • Claimed paths for each task
3. Dependency scheduling: The daemon schedules tasks, only executing when dependencies are met
4. Cross-agent execution: Tasks flow between agents based on the graph

Inspecting Plans

# View the current execution graph
kavi plan

In the TUI, the Results view (2) shows the materialized plan with task status.

Plan Lifecycle

Draft → Active → Completed
                → Blocked (if a dependency fails)

• Draft: Plan is being materialized
• Active: Tasks are being scheduled and executed
• Completed: All tasks in the graph finished
• Blocked: A task failed or was blocked, halting dependent tasks

Tips

• Use auto mode by default — Kavi's heuristics are good at detecting when planning helps
• Use plan mode for ambitious goals: "Build X from scratch"
• Use direct mode for quick fixes: "Fix the bug in auth.ts"
• Review the plan in Results (2) before execution starts
• Follow-up tasks from reviews are always direct (no re-planning)