Sessions

Ripperdoc maintains session history to enable context-aware conversations and session resumption.

Session Storage

Sessions are stored in ~/.ripperdoc/sessions/ as JSON files containing:

• Full conversation transcript
• Tool execution history
• Token usage and costs
• Session metadata

Resuming Sessions

Continue Most Recent Session

Continue the most recent session in the current directory:

ripperdoc --continue
# or
ripperdoc -c

This automatically resumes the last session without prompting.

Interactive Session Selection

Use the /resume command during an interactive session to select from recent sessions:

> /resume

This opens an interactive picker to browse and select from your session history.

Session Commands

View Status

> /status

Shows current session information including:

• Message count
• Token usage
• Duration
• Tool calls

View Statistics

> /stats

Shows detailed session statistics:

• Input/output tokens
• Cache read/write tokens (if supported)
• Cost breakdown
• Tool usage breakdown

View Costs

> /cost

Shows token usage and estimated costs. Includes cache read/write tokens when available (e.g., Anthropic cache).

Context Management

Clearing History

Clear the current conversation:

> /clear

This starts a fresh conversation while keeping the session.

Compacting History

When the context window fills up, Ripperdoc automatically compacts the conversation by summarizing older messages.

Manually trigger compaction:

> /compact

You can also provide custom instructions:

> /compact Focus on the API implementation details

Session Configuration

Configure session behavior via environment variables:

Or in ~/.ripperdoc.json:

{
  "auto_compact_enabled": true,
  "context_token_limit": 100000
}

Context Length Handling

When the context window is exceeded:

1. Ripperdoc detects the context length error
2. Automatically compacts older messages
3. Retries the request with the compacted context
4. Notifies you if compaction was performed

Exporting Sessions

Session files are stored as JSON and can be:

• Backed up manually
• Analyzed for usage patterns
• Shared for debugging

Session file location: ~/.ripperdoc/sessions/<project-hash>/<session-id>.json

Best Practices

1. Use /clear for new tasks: Start fresh when switching to unrelated work
2. Monitor /cost for long sessions: Keep track of token usage
3. Resume when interrupted: Use -c or --continue to continue interrupted work
4. Compact proactively: Use /compact if responses slow down
5. Use /resume to browse history: Find specific past sessions interactively