Recommendations

Kavi analyzes agent activity and session state to generate actionable recommendations. These surface opportunities for handoffs, integration points, and configuration improvements.

Recommendation Types

Handoff Recommendations

Handoff recommendations appear when Kavi detects that a task might be better suited for the other agent. Common triggers:

• An agent is working on files outside its path ownership
• Keyword analysis of the task description suggests a different agent
• An agent explicitly requests help via peer messaging

Example: Codex is implementing a React component that falls within Claude's path ownership. Kavi recommends handing the component work to Claude.

Integration Recommendations

Integration recommendations surface when agent worktrees have changes that should be coordinated. Common triggers:

• Both agents have modified files in overlapping areas
• One agent's changes depend on another agent's uncommitted work
• The worktrees have diverged significantly and early integration would reduce conflict risk

Example: Codex has updated the API schema and Claude has built UI components against the old schema. Kavi recommends integrating so Claude picks up the schema changes.

Ownership-Config Recommendations

Ownership-config recommendations suggest improvements to your routing configuration based on observed patterns. Common triggers:

• Tasks are frequently routed by AI fallback for paths that could have deterministic rules
• Path ownership rules are too broad or too narrow based on actual task distribution
• Keyword lists are missing common terms that appear in task descriptions

Example: Tasks touching src/hooks/** consistently go to Claude via keyword heuristics. Kavi recommends adding src/hooks/** to claude_paths for faster, more confident routing.

Fingerprint-Based Deduplication

Each recommendation is assigned a fingerprint based on its type, context, and trigger conditions. The fingerprint prevents duplicate recommendations from appearing when the underlying conditions persist.

For example, if Kavi recommends a handoff for a specific file and you dismiss it, the same recommendation will not reappear unless the conditions change materially (e.g., a different agent starts working on the same file for a different task).

Recommendation Lifecycle

Recommendations move through a defined lifecycle:

Generated

A new recommendation has been created and is visible in the TUI's recommendation feed. It has not been acted on.

Acted On

The operator has taken action on the recommendation, such as:

• Initiating a handoff
• Triggering an integration
• Updating the config file

Dismissed

The operator has dismissed the recommendation, indicating it is not relevant or not worth acting on. Dismissed recommendations are hidden from the feed but can be restored.

Restored

A previously dismissed recommendation has been brought back into the active feed. This is useful when circumstances change and a dismissed recommendation becomes relevant again.

Actionable Follow-up Tasks

Some recommendations can generate follow-up tasks directly. When you act on a recommendation, Kavi can:

• Create a handoff task that reassigns work to the recommended agent
• Create an integration task that triggers the landing workflow for a subset of changes
• Apply config changes automatically and commit them

This reduces the friction between seeing a recommendation and acting on it.

Viewing Recommendations

Recommendations appear in the TUI's recommendation feed, ordered by relevance and recency. Each recommendation shows:

• The recommendation type (handoff, integration, ownership-config)
• A description of what was detected and why the recommendation was generated
• Suggested actions
• The ability to act on, dismiss, or inspect the recommendation

Recommendations are also logged in the session event log for audit and review.