Frontmatter:
title: Agent Sessions
description: Learn how to configure, direct, and review agent sessions in Kepler — including how to read diffs, stage changes, and commit agent output.
taxonomy:
category: kepler
Purpose: Cover everything that happens inside an agent session: configuration options, reading and interacting with agent output in the console, reviewing the diff, staging, and committing.
Sections to include:
Configuring an agent session
Four settings available at session start: Agent, Mode, Model, Effort Level.
Agent: which agent runtime runs this session (Claude Code, Codex CLI, Copilot CLI, Cursor, OpenCode). Set at session start; cannot be changed mid-session. (Link to agent-integrations.md.)
Mode: how the agent handles decisions — from pausing at every decision point to running without interruption. Document the available modes.
Model: the model powering the agent. "Default (recommended)" is pre-selected. Faster models for simple tasks; more capable for complex ones.
Effort Level: how thoroughly the agent reasons. More effort = more thorough, slower. Document the available levels.
Per-message overrides: Mode, Model, and Effort can be changed on any individual message from the console input bar without restarting the session. Agent cannot be changed mid-session.
Using the console to direct agents
Session tabs: each session has a tab showing its name (truncated). Click × to close; click + to open a new session tab. Multiple sessions per worktree can be open simultaneously.
Agent output format:
User messages appear as chat bubbles.
Agent responses render as formatted markdown (bold, inline code, lists, tables).
Tool calls (file reads, searches, shell commands) appear as collapsible rows (e.g., find /path...) with a Completed badge or error state. Click ► to expand the full tool output.
Input bar controls:
Mic (🎤): voice input.
Attachment (paperclip): attach a file for the agent to reference.
Mode dropdown: change mode for this message.
Model dropdown: change model for this message.
Effort dropdown: change effort for this message.
"20%" indicator: flag for engineering — likely token budget remaining or cost usage.
Send (↑): submit the instruction.
How to course-correct: send a follow-up instruction when you see unexpected output, a tool call error, or a Needs Attention/Disconnected status.
Reviewing changes: diffs, staging, and commits
Opening the diff: click a worktree in the List view sidebar. The diff opens in the center panel.
Reading the diff:
File path and +/- line stats at the top.
Stacked vs. Split toggle: Stacked = top-to-bottom; Split = side-by-side.
Unmodified sections are collapsed with a line count. Click to expand.
Red = removed, green = added.
Working changes panel (right): shows uncommitted changes alongside the worktree's recent commit history.
Commit history: click any commit to see full title, description, author name and email, timestamp, full hash, branch tags, and per-file +/- stats with change type (M/A/D).
Staged files panel:
Header: "STAGED (N)" with file count.
Each file: path and change type badge (M, A, D).
Discard All: discards all changes (destructive — document any confirmation prompt).
Unstage All: moves all staged files back to unstaged.
Individual file: click to view its diff; per-file controls to unstage or discard (confirm exact interaction with engineering).
Commit message: pre-populated by Kepler/agent; fully editable. Click Commit to commit staged files.
Push / Pull / Fetch: available from the diff view toolbar (top right) without leaving Kepler.
"Back to session": closes the diff and returns to the agent session console.
Optional agent features: AI Sync and Compose
Two experimental features (Settings → Features) that extend what agents can do. Both are opt-in, off by default.
AI Sync: gives agents tools to rebase or merge with automatic conflict resolution. Operations are safe and can be rolled back.
Compose: gives agents tools to reorganize messy changes into clean, atomic commits. Operations are undoable.
How to enable: Settings → Features → toggle on.
What changes in agent behavior after enabling: describe the additional tools the agent can invoke.
Link to: settings.md (Features section).
Frontmatter:
title: Agent Sessions
description: Learn how to configure, direct, and review agent sessions in Kepler — including how to read diffs, stage changes, and commit agent output.
taxonomy:
category: kepler
Purpose: Cover everything that happens inside an agent session: configuration options, reading and interacting with agent output in the console, reviewing the diff, staging, and committing.
Sections to include:
Configuring an agent session
Four settings available at session start: Agent, Mode, Model, Effort Level.
Agent: which agent runtime runs this session (Claude Code, Codex CLI, Copilot CLI, Cursor, OpenCode). Set at session start; cannot be changed mid-session. (Link to agent-integrations.md.)
Mode: how the agent handles decisions — from pausing at every decision point to running without interruption. Document the available modes.
Model: the model powering the agent. "Default (recommended)" is pre-selected. Faster models for simple tasks; more capable for complex ones.
Effort Level: how thoroughly the agent reasons. More effort = more thorough, slower. Document the available levels.
Per-message overrides: Mode, Model, and Effort can be changed on any individual message from the console input bar without restarting the session. Agent cannot be changed mid-session.
Using the console to direct agents
Session tabs: each session has a tab showing its name (truncated). Click × to close; click + to open a new session tab. Multiple sessions per worktree can be open simultaneously.
Agent output format:
User messages appear as chat bubbles.
Agent responses render as formatted markdown (bold, inline code, lists, tables).
Tool calls (file reads, searches, shell commands) appear as collapsible rows (e.g., find /path...) with a Completed badge or error state. Click ► to expand the full tool output.
Input bar controls:
Mic (🎤): voice input.
Attachment (paperclip): attach a file for the agent to reference.
Mode dropdown: change mode for this message.
Model dropdown: change model for this message.
Effort dropdown: change effort for this message.
"20%" indicator: flag for engineering — likely token budget remaining or cost usage.
Send (↑): submit the instruction.
How to course-correct: send a follow-up instruction when you see unexpected output, a tool call error, or a Needs Attention/Disconnected status.
Reviewing changes: diffs, staging, and commits
Opening the diff: click a worktree in the List view sidebar. The diff opens in the center panel.
Reading the diff:
File path and +/- line stats at the top.
Stacked vs. Split toggle: Stacked = top-to-bottom; Split = side-by-side.
Unmodified sections are collapsed with a line count. Click to expand.
Red = removed, green = added.
Working changes panel (right): shows uncommitted changes alongside the worktree's recent commit history.
Commit history: click any commit to see full title, description, author name and email, timestamp, full hash, branch tags, and per-file +/- stats with change type (M/A/D).
Staged files panel:
Header: "STAGED (N)" with file count.
Each file: path and change type badge (M, A, D).
Discard All: discards all changes (destructive — document any confirmation prompt).
Unstage All: moves all staged files back to unstaged.
Individual file: click to view its diff; per-file controls to unstage or discard (confirm exact interaction with engineering).
Commit message: pre-populated by Kepler/agent; fully editable. Click Commit to commit staged files.
Push / Pull / Fetch: available from the diff view toolbar (top right) without leaving Kepler.
"Back to session": closes the diff and returns to the agent session console.
Optional agent features: AI Sync and Compose
Two experimental features (Settings → Features) that extend what agents can do. Both are opt-in, off by default.
AI Sync: gives agents tools to rebase or merge with automatic conflict resolution. Operations are safe and can be rolled back.
Compose: gives agents tools to reorganize messy changes into clean, atomic commits. Operations are undoable.
How to enable: Settings → Features → toggle on.
What changes in agent behavior after enabling: describe the additional tools the agent can invoke.
Link to: settings.md (Features section).