f6b84d864a
Standardize project name to lowercase 'g3' throughout documentation, comments, and configuration files. Environment variables (G3_*) are unchanged as they follow the uppercase convention.
297 lines
7.7 KiB
Markdown
297 lines
7.7 KiB
Markdown
# 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.
|