Context & Conversations

When you chat with Kiwi Code, the AI maintains a conversation history that grows with each message. Understanding how context works helps you get better results.

How Context Works

Every message you send, every tool call, and every AI response becomes part of the conversation context. The AI sees this full history when generating its next response.

Message 1: "Explain this repo"
  → AI reads files, responds with architecture overview

Message 2: "Now add rate limiting"
  → AI remembers the architecture from message 1
  → Knows which files to edit without re-reading everything

This is why conversations get smarter over time — the AI accumulates understanding of your codebase as you work.

Conversation Window

To prevent context from growing too large, Kiwi Code uses a sliding window over your conversation history:

The AI always sees:

1. The system prompt and initial context (pinned)
2. The most recent 20 turns of conversation

Older turns are still saved but aren't sent to the AI, keeping the request size manageable.

Starting Fresh

If the AI seems confused or you're switching to a different task, start a new conversation:

/new

This clears all context and gives you a clean slate. Use this when:

• You're done with one task and starting another
• The conversation has become too long and unfocused
• The AI is referencing outdated information from earlier in the chat

Continuing Conversations

Resume a previous conversation with its full history:

/continue <run_id>

Or from the CLI:

kiwi --terminal --run-id <run_id> "Continue where we left off"

The AI picks up with the same context it had before.

What Counts as Context

Each item in the conversation uses context space:

Tips for Managing Context

• Be specific — "Fix the bug in src/auth.py line 42" uses less context than "Find and fix all bugs"
• Use worktrees for large tasks — start fresh context in an isolated branch
• Start new conversations when switching tasks — don't reuse a conversation about auth to work on the UI
• Attach only relevant files — don't upload your entire project

Roles & Modes Affect Context

When you switch roles or modes, Kiwi Code injects additional instructions into the context:

• /role senior-software-engineer — adds coding-focused system instructions
• /mode plan — adds instructions to analyze and plan, not write code
• /mode validate — adds instructions to review and test, not modify

These are added silently to your message — you don't see them, but the AI does. This is how roles and modes change the AI's behavior without you having to write detailed instructions.

Multi-Agent Context

In multi-agent workflows, each agent gets its own independent context. Agents don't share conversation history — they each see only their assigned task and inputs.

Agent 1: context = task description + file batch 1
Agent 2: context = task description + file batch 2
Agent 3: context = task description + file batch 3

This isolation means each agent works independently without interference.