Session Management

How Grok One-Shot handles conversation sessions, storage, and recovery.

Overview

Sessions are the foundation of Grok One-Shot's conversational interface. Each session maintains context, tracks usage, and can be saved, restored, or analyzed.

Session Lifecycle

Starting a Session

Interactive mode:

grok

# Session starts
# Loads: GROK.md + docs-index.md (~3,500 tokens)
# Ready for conversation

With initial message:

grok "analyze authentication flow"

# Session starts with your message already queued
# AI processes and responds immediately

Headless mode (no session persistence):

grok -p "quick query"

# Executes query
# No session file created
# Exits immediately

During a Session

Conversation flow:

User types message
AI receives message + full context
AI uses tools as needed
AI generates response
Conversation continues
Session auto-saves periodically

Context accumulation:

Initial: ~3,500 tokens (startup context)
Message 1: +1,500 tokens
Message 2: +2,000 tokens
Message 3: +3,500 tokens
...
After 20 messages: ~40,000 tokens

Ending a Session

Graceful exit:

# In session, type:
/exit
# or
/quit

# Session saved to ~/.grok/sessions/
# Clean shutdown

Keyboard shortcuts:

Ctrl+D → Exit gracefully
Ctrl+C → Interrupt (may not save)
Ctrl+C (twice) → Force exit (no save)

Automatic save:

Sessions save periodically during conversation
Final save on graceful exit
Emergency save on unexpected termination (best effort)

Session Storage

Storage Location

Default directory:

~/.grok/sessions/

Session files:

ls ~/.grok/sessions/

session-2025-11-05-14-30-12.json
session-2025-11-05-16-45-03.json
session-2025-11-06-09-15-22.json

Session File Format

Structure:

{
"sessionId": "session-2025-11-05-14-30-12",
"startTime": "2025-11-05T14:30:12.345Z",
"endTime": "2025-11-05T15:15:42.789Z",
"model": "grok-2-1212",
"messages": [
{
"role": "system",
"content": "[GROK.md + docs-index.md content]"
},
{
"role": "user",
"content": "analyze authentication flow",
"timestamp": "2025-11-05T14:30:15.000Z"
},
{
"role": "assistant",
"content": "I'll analyze the authentication flow...",
"timestamp": "2025-11-05T14:30:18.500Z",
"toolCalls": [
{
"tool": "Glob",
"parameters": { "pattern": "**/*auth*" },
"result": ["src/auth/middleware.ts", "..."]
}
]
}
],
"tokenUsage": {
"input": 23450,
"output": 8920,
"total": 32370
},
"metadata": {
"workingDirectory": "/home/user/myproject",
"nodeVersion": "20.10.0",
"grokVersion": "1.1.101"
}
}

Session File Benefits

Review conversations:

# View recent session
cat ~/.grok/sessions/session-2025-11-05-14-30-12.json | jq '.messages[] | {role, content}'

Track token usage:

# Total tokens across all sessions
find ~/.grok/sessions/ -name "*.json" -exec jq -r '.tokenUsage.total' {} + | awk '{sum+=$1} END {print sum " total tokens"}'

Audit tool usage:

# What tools were used?
cat ~/.grok/sessions/*.json | jq -r '.messages[].toolCalls[]?.tool' | sort | uniq -c

Debug issues:

# What happened in that session?
cat ~/.grok/sessions/problem-session.json | jq '.messages'

Session Features

Implemented

Auto-save:

Periodic saves during conversation
Save on graceful exit
Emergency save on crash (best effort)

Session files:

JSON format for easy parsing
Complete conversation history
Tool call tracking
Token usage accounting
Metadata (directory, versions, timestamps)

Session isolation:

Each session independent
No cross-session context leakage
Clean state per session

Token tracking:

Input token count
Output token count
Total usage per session
Real-time monitoring (Ctrl+I)

Partially Implemented

Session management:

No built-in session listing UI
No session restore command
No session search/filter
Manual review via file system

Session cleanup:

No automatic cleanup
No retention policies
Manual deletion supported

Session naming:

Automatic timestamp-based names
No custom session names
No session tagging

Planned Features

Session management UI:

# Future commands
grok sessions list
grok sessions show <session-id>
grok sessions delete <session-id>
grok sessions resume <session-id>

Session restoration:

Resume previous session with context
Continue where you left off
Session branching (fork from point)

Intelligent cleanup:

Auto-delete sessions older than N days
Configurable retention policy
Archive important sessions

Session analytics:

Cost tracking per session
Performance metrics
Tool usage statistics
Success rate analysis