Common Workflows

This page shows practical ways to use Kiwi Code — prompt patterns, command sequences, and workflows for common development tasks.

Explore a New Codebase

When you open a project for the first time:

Explain the architecture of this repository.
What are the main components and how do they connect?

Follow up with specifics:

How does authentication work in this project?

Where are the API routes defined? Walk me through the request flow.

Plan Before Building

Use modes to separate thinking from doing:

/mode plan

I need to add WebSocket support to the chat feature.
What's the best approach? What files need to change?

Review the plan, then switch to build:

/mode build

Implement the WebSocket approach we discussed.

Fix a Bug

Describe the symptom and let the AI investigate:

The login endpoint returns 500 when the email contains a + sign.
Find the bug and fix it.

Or point to a specific error:

Running `pytest tests/test_auth.py` fails with:
AssertionError: expected 200 but got 403

Fix the failing test.

Refactor Code

Ask for specific refactoring patterns:

Refactor the UserService class to use dependency injection
instead of hardcoded database calls.

Convert all callback-based functions in src/utils/ to async/await.

Write Tests

Write unit tests for src/services/payment.py.
Cover the happy path and edge cases (invalid amount, expired card, network timeout).

The coverage report shows src/auth/middleware.py at 30%.
Add tests to bring it above 80%.

Use Worktree Mode for Safe Experiments

Isolate AI work in a git worktree so your main branch stays clean:

kiwi -w add-rate-limiting

The AI works in an isolated copy. When you're happy with the result:

cd .kiwi/worktrees/add-rate-limiting
git diff main
git checkout main
git merge add-rate-limiting

Checkpoint and Rewind

Every message you send creates a checkpoint of modified files. If the AI makes a change you don't like:

/rewind

Select the checkpoint to restore to. Your files revert to that state. Then try a different approach:

Try again, but use Redis instead of an in-memory cache.

Attach Files for Context

Use @ to attach files the AI should reference:

@ src/models/user.py

Then type your message:

Add email validation to the User model based on the existing pattern.

Or upload files with a command:

/upload docs/api-spec.yaml

Implement the endpoints defined in the API spec I just uploaded.

Terminal Mode for Scripting

Run one-off queries without the full TUI:

# Quick question
kiwi --terminal "What does the main() function in src/app.py do?"

# Continue a previous conversation
kiwi --terminal --run-id run_abc123 "Now add error handling"

# JSON output for scripting
kiwi --terminal --json "List all TODO comments in the codebase"

Web Dashboard + CLI Runtime

For browser-based access with local execution:

# Terminal 1: Start the runtime
kiwi-runtime connect --scope full

Then open kiwicode.ai/autocode/new and prompt:

Connect to my CLI runtime.
Run the test suite and fix any failures.

Role Switching

Switch roles based on your task:

/role browser-wizard

Scrape the pricing page at example.com and extract the plan details into a JSON file.

Switch back for regular coding:

/role senior-software-engineer

Validate Before Shipping

Switch to validate mode for a final review:

/mode validate

Review all changes in this branch.
Check for security issues, missing error handling, and test coverage gaps.

Quick Reference

Workflow	Commands
Plan → Build → Validate	`/mode plan` → `/mode build` → `/mode validate`
Safe experiment	`kiwi -w experiment-name`
Undo AI changes	`/rewind`
Attach files	`@` or `/upload path`
Switch AI persona	`/role <name>`
One-off query	`kiwi --terminal "question"`
Browser + local exec	`kiwi-runtime connect` + web dashboard

Common Workflows

On this page