Custom Prompts

Kavi supports custom system prompts for each agent, giving you fine-grained control over how Codex and Claude approach tasks in your project.

Prompt Files

Custom prompts are Markdown files stored in .kavi/prompts/:

These files are created with placeholder content by kavi init. When these files exist, their contents are prepended to the agent's system prompt before each task, letting you inject project-specific context, coding conventions, and behavioral guidelines.

How Prompts Are Used

When Kavi sends a task to an agent, the custom prompt is included as part of the system context:

1. Kavi reads the corresponding prompt file (e.g., .kavi/prompts/codex.md for Codex)
2. The prompt content is prepended to the task instructions
3. The agent receives the combined prompt as its system context

This means agents see your custom instructions on every task, ensuring consistent behavior throughout the session. You can use prompts to:

• Set coding standards and conventions
• Provide project-specific context
• Define output format expectations
• Restrict or guide agent behavior

Example: Codex Prompt

<!-- .kavi/prompts/codex.md -->

# Project Context

This is a Node.js monorepo using pnpm workspaces. The backend is Express + Prisma + PostgreSQL.

## Conventions

- Use `zod` for all input validation
- Prefer named exports over default exports
- Database queries go through the repository pattern in `src/backend/repos/`
- All API routes must have corresponding integration tests in `__tests__/`
- Use `async/await` instead of callbacks
- Prefer `const` over `let`

## Architecture Rules

- Never import from `src/components/` (frontend code)
- Use the shared types in `src/shared/types.ts` for API contracts
- Migrations must be backward-compatible (no column drops without a deprecation period)
- All database queries go through the `src/db/` module

## Output Format

When completing a task, provide:
1. A summary of changes made
2. Any concerns or open questions
3. Files that need review attention

Example: Claude Prompt

<!-- .kavi/prompts/claude.md -->

# Project Context

This is a Next.js frontend using React 19 with Server Components. Styling uses Tailwind CSS.

## Conventions

- Use `cn()` utility from `src/lib/utils.ts` for conditional class names
- Components go in `src/components/` with one component per file
- Use Server Components by default; add `"use client"` only when interactivity is needed
- Prefer `useActionState` over manual form state management
- Components should be accessible (ARIA labels, keyboard navigation)

## Design System

- Follow the design tokens in `tailwind.config.ts`
- Use the `Button`, `Input`, `Card` primitives from `src/components/ui/`
- Spacing: use Tailwind spacing scale (4px base)
- Typography: use the project's font variables, never hardcode font families
- Use Tailwind CSS utility classes, never inline styles

What to Include

Effective custom prompts typically cover:

Project Context

• Tech stack and major dependencies
• Repository structure overview
• Build system and tooling

Coding Conventions

• Naming conventions
• Import/export patterns
• File organization rules
• Error handling patterns

Architecture Rules

• Boundary constraints (what should not be imported from where)
• Pattern requirements (repository pattern, service layer, etc.)
• API contract conventions

Domain Knowledge

• Business logic rules that agents should know
• Data model relationships
• External service integration patterns

What to Avoid

Custom prompts work best when they are concise and actionable.

• Verbose documentation -- agents work better with terse rules than lengthy explanations
• Redundant information -- don't repeat what's obvious from the codebase
• Contradictory rules -- ensure Codex and Claude prompts don't give conflicting guidance on shared concerns
• Overly restrictive rules -- too many constraints reduce agent effectiveness

Prompt File Size

Keep prompt files focused. A good target is 200-500 words per prompt. Extremely long prompts consume context window space and can dilute the most important instructions.

Version Control

Custom prompt files live in .kavi/prompts/ which is inside your project's .kavi/ directory. Whether to commit these files depends on your team:

• Commit them if the prompts encode team-wide conventions that everyone should use
• Gitignore them if prompts contain personal preferences or experimental instructions

If you commit them, add them explicitly since .kavi/ may be in your .gitignore:

git add -f .kavi/prompts/codex.md .kavi/prompts/claude.md

Tips

• Test the effect of prompt changes by running a task and reviewing the output
• Start with a minimal prompt and iterate based on agent behavior
• Review the agent's output for signs that it is or isn't following your guidelines