Full-Stack Workflow

End-to-end guide for building a feature with Kavi — from scaffold to landed code

This guide walks through a complete full-stack feature build using Kavi, demonstrating how Codex and Claude collaborate on backend and frontend work.

Scenario

You're building a user authentication system with JWT tokens and a login UI.

Set Up Ownership Rules

Before starting, configure path-based routing in .kavi/config.toml:

[routing]
codex_paths = ["src/api/**", "src/db/**", "src/lib/**"]
claude_paths = ["src/components/**", "src/pages/**", "src/styles/**"]
backend_keywords = ["api", "auth", "jwt", "database", "schema", "migration"]
frontend_keywords = ["ui", "component", "page", "form", "css", "layout"]

Open a Session

kavi open --goal "Build JWT authentication with login/register UI"

Kavi creates worktrees for both agents and opens the TUI.

Compose the Task

Press c to open the composer:

Build a complete JWT authentication system with:
- Database schema for users
- Login and register API endpoints with token rotation
- React login and register forms with validation

With planning mode on auto, Kavi detects this is a multi-step task and routes it to the planner.

Review the Plan

Switch to the Results view (2) to see the materialized execution graph:

[1] setup-db        (codex)  → Add user schema and migrations
[2] api-routes      (codex)  → Implement auth endpoints [depends: 1]
[3] frontend-forms  (claude) → Build login/register UI [depends: 2]
[4] integration     (codex)  → Wire frontend to API [depends: 3]

Monitor Execution

Switch to Activity (1) to watch progress. Tasks execute respecting dependencies:

Codex creates the database schema
Codex builds the API routes
Claude builds the frontend forms
Codex integrates everything

Review Diffs

Switch to Tasks (3) and navigate to a completed task. Use ,/. to cycle changed files and {/} to cycle patch hunks.

Add review notes:

Press A to approve good changes
Press C to raise concerns (e.g., "use bcrypt instead of sha256")
Press F to queue a fix task from a concern

Land

When all tasks are complete and reviews are resolved, press L to land:

Landing...
  Snapshot: codex worktree → commit
  Snapshot: claude worktree → commit
  Integration: merge in temp worktree
  Validation: npm test → passed
  Fast-forward: main ← integration
  Report: .kavi/state/reports/land-001.json

Verify

kavi result    # See the merged outcome
kavi summary   # Session-level summary

Full-Stack Workflow

On this page