Sessions & History

How Sessions Work

Every time you use YeePilot, your conversation is automatically saved as a session. Sessions capture your prompts, AI responses, command plans, approval decisions, and execution output. You never need to manually save -- it happens in the background.

When you launch YeePilot, it resumes your most recent session. If you prefer to start fresh, use the /new command.

Managing Sessions

Create a New Session

> /new

This creates a fresh session with a clean conversation history. Your previous session is preserved and can be resumed later.

List All Sessions

> /sessions

This displays a list of your saved sessions with their names, creation dates, and message counts. Select a session from the list to switch to it.

Sessions:
  1. nginx-troubleshooting     (12 messages, 2h ago)
  2. database-migration        (8 messages, yesterday)
  3. firewall-setup            (23 messages, 3 days ago)
 
Switch to: _

Rename a Session

By default, sessions are named automatically. Give them meaningful names to find them later:

> /rename nginx-troubleshooting

You can also rename without arguments to be prompted for a name:

> /rename
Enter new name: prod-server-audit

Export a Session

Export the current session as a plain text transcript:

> /export

This saves the full conversation -- your prompts, AI responses, proposed commands, and execution output -- as a readable text file. Exports are useful for documentation, incident reports, or sharing with colleagues.

Context Window Management

AI models have a limited context window -- the amount of text they can consider at once. As your conversation grows, it approaches this limit. YeePilot handles this automatically through context compaction.

How Compaction Works

When the context window reaches approximately 80% capacity, YeePilot triggers automatic compaction:

1. The oldest 80% of messages in the conversation are selected
2. These messages are summarized into a concise recap
3. The summary replaces the original messages
4. The most recent 20% of messages remain intact

This process is seamless. You do not need to take any action, and the conversation continues normally. The AI retains the essential context from earlier in the conversation while freeing up space for new interactions.

What Compaction Preserves

The summary retains:

• Key decisions and outcomes
• Important file paths and configuration values
• Error messages and their resolutions
• The overall goal of the session

What it naturally loses:

• Exact command output from early in the session
• Verbose intermediate steps
• Exploratory commands that did not lead anywhere

If you need to reference exact output from earlier in a long session, consider exporting the session before compaction occurs, or start a new session for the next task.

Token Tracking

YeePilot tracks token usage for every session, giving you visibility into API consumption and costs.

Viewing Token Usage

Press Ctrl+S during a session to see the stats panel, which includes:

• Prompt tokens -- tokens sent to the AI (your messages plus context)
• Completion tokens -- tokens generated by the AI
• Total tokens -- combined usage for the session
• Estimated cost -- calculated from your model's per-token pricing

Understanding Token Costs

Token usage varies significantly based on:

• Conversation length -- longer sessions use more tokens per message because the full history is sent as context
• Agent mode -- multi-step tasks consume more tokens due to repeated context and tool calls
• Thinking mode -- higher thinking levels use more completion tokens
• File context -- files loaded with /file add to the prompt token count

Keeping Costs Down

• Use free OpenRouter models for routine tasks
• Start new sessions with /new instead of continuing very long conversations
• Remove files from context with /unfile when they are no longer needed
• Use lower thinking modes (/think low) for straightforward tasks
• Monitor usage with Ctrl+S periodically

Session Storage

Sessions are stored locally in ~/.yeepilot/sessions/. Each session is a JSON file containing the full conversation history and metadata. These files are only accessible to your user account.

Sessions are never sent to YeePilot's servers. They remain entirely on your machine. The only data that leaves your system is what you send to your chosen AI provider as part of the normal prompt/response flow.

Practical Workflows

Task-Based Sessions

Create a new session for each distinct task:

> /new
> /rename firewall-audit-2026-02
> Check all iptables rules and identify any overly permissive entries

This keeps your sessions organized and makes them easy to find later.

Incident Response

During an incident, the session becomes a real-time log of your investigation:

1. Start a new session: /new
2. Name it: /rename incident-2026-02-27-api-outage
3. Work through the diagnosis with YeePilot
4. Export when resolved: /export

The exported transcript serves as an incident report showing exactly what was checked, what was found, and what actions were taken.

Resuming Work

Coming back to a task the next day:

> /sessions

Select the relevant session. The AI has the full conversation context and can pick up where you left off.