g3/docs/CONTROL_COMMANDS.md

g3 Control Commands

Last updated: January 2025
Source of truth: crates/g3-cli/src/lib.rs

Purpose

Control commands are special commands you can use during an interactive g3 session to manage context, refresh documentation, and view statistics. They start with / and are processed by the CLI, not sent to the LLM.

Available Commands

Command	Description
/compact	Manually trigger conversation compaction
/thinnify	Replace large tool results with file references (first third)
/skinnify	Full context thinning (entire context window)
/clear	Clear session and start fresh
/resume	List and switch to a previous session
/readme	Reload README.md and AGENTS.md from disk
/stats	Show detailed context and performance statistics
/help	Display all available control commands

---

/compact

Manually trigger conversation compaction to reduce context size.

When to use:

• Context usage is getting high (70%+)
• You want to start a new phase of work
• Conversation has accumulated irrelevant history

What it does:

1. Sends conversation history to LLM for compaction
2. Replaces detailed history with concise summary
3. Preserves key decisions and context
4. Significantly reduces token usage

Example:

g3> /compact
📝 Compacting conversation history...
✅ Reduced context from 45,000 to 8,000 tokens (82% reduction)

Notes:

• Summarization uses tokens, so there's a small cost
• Some detail is lost; use before major context shifts
• Auto-triggered at 80% context usage if auto_compact = true

---

/thinnify

Replace large tool results with file references to save context space.

When to use:

• Large file contents are consuming context
• Tool outputs are taking up space
• You want to preserve conversation structure but reduce size

What it does:

1. Scans the first third of context for large tool results
2. Saves content to .g3/sessions/<session>/thinned/
3. Replaces inline content with file reference
4. Preserves the ability to re-read if needed

Example:

g3> /thinnify
🔧 Thinning context window...
✅ Thinned 3 large tool results, saved 12,000 characters

Notes:

• Only processes the first third of context (older content)
• Recent tool results are preserved inline
• Auto-triggered at 50%, 60%, 70%, 80% thresholds

---

/skinnify

Full context thinning - processes the entire context window.

When to use:

• Context is critically full
• /thinnify wasn't enough
• You need maximum space recovery

What it does:

• Same as /thinnify but processes entire context
• More aggressive space recovery
• May thin recent tool results too

Example:

g3> /skinnify
🔧 Full context thinning...
✅ Thinned 8 tool results, saved 35,000 characters

Notes:

• Use sparingly; may thin content you still need inline
• Consider /compact first for better context preservation

---

/clear

Clear the current session and start fresh.

When to use:

• You want to start a completely new task
• The current context is cluttered or confused
• You want to discard all conversation history

What it does:

1. Clears all conversation history (keeps system prompt)
2. Removes the session continuation symlink
3. Resets context to initial state

Example:

g3> /clear
🧹 Clearing session...
✅ Session cleared. Starting fresh.

Notes:

• This is irreversible for the current session
• Previous session data remains in .g3/sessions/ and can be resumed with /resume
• Use when you want a clean slate

---

/resume

List available sessions and switch to a previous one.

When to use:

• You want to continue work from a previous session
• You accidentally cleared or lost context
• You want to switch between different tasks/sessions

What it does:

1. Scans .g3/sessions/ for sessions in the current directory
2. Displays a numbered list with timestamps and context usage
3. Prompts for selection
4. Saves current session before switching
5. Restores the selected session's context

Example:

g3> /resume
📋 Scanning for available sessions...

Available sessions:
  1. [2025-01-11 14:30] implement_auth_feature_abc123 (45%) 📝
  2. [2025-01-11 10:15] fix_bug_in_parser_def456 (23%)
  3. [2025-01-10 16:45] refactor_database_layer_ghi789 (67%)

Enter session number to resume (or press Enter to cancel):
> 1
🔄 Switching to session: implement_auth_feature_abc123
✅ Full context restored from session.

Notes:

• Sessions marked with 📝 have incomplete TODO items
• Current session is marked with "(current)"
• Only sessions from the current working directory are shown
• Full context is restored if usage was <80%, otherwise summary is used

---

/readme

Reload README.md and AGENTS.md from disk without restarting.

When to use:

• You've updated project documentation
• AGENTS.md has new instructions
• README.md has changed

What it does:

1. Re-reads README.md from workspace root
2. Re-reads AGENTS.md from workspace root
3. Updates the agent's system context
4. New instructions take effect immediately

Example:

g3> /readme
📖 Reloading documentation...
✅ Loaded README.md (5,234 chars)
✅ Loaded AGENTS.md (2,100 chars)

Notes:

• Useful during iterative documentation updates
• Changes apply to subsequent messages
• Previous context retains old documentation

---

/stats

Show detailed context and performance statistics.

What it shows:

• Current context usage (tokens and percentage)
• Session duration
• Token usage breakdown
• Tool call metrics
• Thinning and compaction events
• First-token latency statistics

Example:

g3> /stats
📊 Session Statistics
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Context Usage:     45,230 / 200,000 tokens (22.6%)
Session Duration:  1h 23m 45s
Total Tokens Used: 125,430
Tool Calls:        47 (45 successful, 2 failed)
Thinning Events:   3 (saved 28,000 chars)
Summarizations:    1 (saved 35,000 chars)
Avg First Token:   1.2s

---

/help

Display all available control commands with brief descriptions.

Example:

g3> /help
📚 Available Commands:
  /compact   - Summarize conversation to reduce context
  /thinnify  - Replace large tool results with file refs
  /skinnify  - Full context thinning (entire window)
  /clear     - Clear session and start fresh
  /resume    - List and switch to a previous session
  /readme    - Reload README.md and AGENTS.md
  /stats     - Show context and performance statistics
  /help      - Show this help message

---

Context Management Strategy

g3 automatically manages context, but manual intervention can help:

Proactive Management

1. Check stats regularly: Use /stats to monitor usage
2. Thin early: Use /thinnify before hitting thresholds
3. Compact at transitions: Use /compact when switching tasks

Reactive Management

When context gets high:

1. 50-70%: Consider /thinnify
2. 70-80%: Use /compact
3. 80-90%: Use /skinnify then /compact
4. 90%+: Auto-compaction triggers

Best Practices

• Long sessions: Compact periodically to maintain quality
• Large files: Thin after reading large codebases
• Documentation updates: Use /readme instead of restarting
• Before complex tasks: Ensure adequate context space

---

Automatic Context Management

g3 performs automatic context management:

Threshold	Action
50%	Thin oldest third of context
60%	Thin oldest third of context
70%	Thin oldest third of context
80%	Auto-compaction (if auto_compact = true)
90%	Aggressive thinning before tool calls

Manual commands give you finer control over when and how this happens.