Getting Good Results

Kepler is a powerful coding agent, but like any tool, the quality of what you get out depends on what you put in. Here are patterns that produce the best results.

Be Specific

Vague requests produce vague results. Include details about:

• What you want to do
• Where (which file, which component)
• How (approach, constraints, patterns to follow)

- fix the login
+ fix the login error handling in src/app/login/page.tsx — when the API
  returns a 429, show a rate-limit message instead of a generic error

When to Use /plan

The /plan command is your most powerful tool for non-trivial changes. Use it when:

• 3+ files are involved — let Kepler think through the architecture
• You want to review before execution — /plan shows you the approach before any code is written
• The task is ambiguous — /plan clarifies what Kepler intends to do
• You’re refactoring — structure matters, and /plan gets it right

> /plan migrate the settings page from a single form to a tabbed layout

Kepler will respond with a structured plan. You can accept it, ask for revisions, or cancel and refine your request.

Use the .kepler/ Folder

The .kepler/ folder in your project root stores session history and project context. You can:

• Add project memory — edit .kepler/KEPLER.md with project-specific guidelines, commands, conventions, and architecture notes
• Check session history — Kepler remembers context across turns within the same session

To set persistent project-level instructions:

echo "We use React Server Components by default. Avoid 'use client' unless
you need browser APIs or event handlers." > .kepler/KEPLER.md

Kepler will read this file on every session and follow the instructions.

Iterate, Don’t Prompt-Engineer

Don’t try to get everything perfect in one turn. Kepler works best with an iterative workflow:

1. First turn — make the change, get it working
2. Review — read the diff or ask “show me a summary of what changed”
3. Refine — “make the button smaller”, “add error handling”
4. Test — “run the test suite” (or your project’s test command)

This is faster than trying to specify every detail upfront.

Provide Context

If you’re asking about a specific part of the codebase, help Kepler find it:

- how does auth work?
+ how does the GitHub OAuth flow work in src/lib/auth.ts?

Kepler can search the codebase, but explicit file paths and function names save time and reduce ambiguity.

Use the Right Model

Different tasks benefit from different models:

See Choosing a Model for the full breakdown.

Human-in-the-Loop (HITL)

Kepler supports several HITL affordances:

• /plan mode — review before execution
• Diff preview — Kepler shows changes before applying them
• Confirmation prompts — for destructive operations (deletes, large rewrites)
• /review — summarize what changed in the current session

Always review diffs before confirming, especially for:

• File deletions
• Large-scale renames
• Changes to configuration files
• Dependency updates

Common Patterns

Debugging a Failing Test

> /test
> fix the failing test in src/__tests__/auth.test.ts

Adding a Feature

> /plan add a "forgot password" flow to the auth module
> (review plan, accept)
> now add input validation for the email field
> /test

Understanding Code

> /explain how the WebSocket connection is managed
> /explain the data flow from API to UI in the dashboard

Refactoring

> /plan extract the shared utility functions from src/components/*.tsx
   into a src/lib/utils.ts
> (review plan, accept)
> update all imports to point to the new file
> /test

Use Skills for Reusable Patterns

Skills are portable instruction bundles that give Kepler domain expertise. Install them once and use them across projects.

# Install a skill for your team's conventions
kepler skills install ./team-react-patterns
 
# Then reference it in prompts
> using the team-react-patterns skill, create a new settings page

See Skills for the full guide.

Choose Your Approval Strategy

Different tasks benefit from different permission modes:

• --permission-mode auto (default) — best for interactive work where you want to review dangerous operations
• --permission-mode plan — use when exploring an unfamiliar codebase to prevent accidental writes
• --permission-mode acceptEdits — when you trust the agent’s edits but want to review shell commands
• --yes / --freeswim — only in disposable environments or when you’ve already reviewed the plan

Use /plan first, then --yes to execute the approved plan:

# In the REPL: review the plan
> /plan refactor the database layer to use transactions
 
# Exit and re-run with auto-approve for the execution
kepler --yes "execute the refactor plan we discussed"

Automate Repetitive Tasks

Headless mode (--headless) is ideal for CI/CD and batch processing:

# Run lint fixes in CI
kepler --headless --timeout 120 "Run lint and fix auto-fixable issues"
 
# Batch process multiple prompts
while read -r prompt; do
  kepler --headless --timeout 60 "$prompt" > "output-$(date +%s).jsonl"
done < prompts.txt

See Automation & CI/CD for details.

Resume Smartly

When resuming sessions, let Kepler manage context automatically:

• Short sessions (< 20 turns) — full transcript is sent
• Long sessions — a summary plus the last 10 messages preserves context without overflowing the model’s window
• Cross-session — use kepler history to find past sessions and --resume <sessionId> to continue

This is faster than re-explaining the entire context every time.

Customize Project Instructions

Put project-level conventions in .kepler/KEPLER.md. Kepler reads this file as durable project memory:

echo "We use React Server Components by default. Avoid 'use client' unless
you need browser APIs or event handlers.
- TypeScript strict mode enabled
- Tests use Vitest with @testing-library/react
- API routes follow the App Router convention" > .kepler/KEPLER.md

This is more effective than repeating instructions in every prompt.