lamport run
This commit is contained in:
Dhanji R. Prasanna
224
docs/CONTROL_COMMANDS.md
Normal file
224
docs/CONTROL_COMMANDS.md
Normal file
@@ -0,0 +1,224 @@
|
||||
# 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 summarization |
|
||||
| `/thinnify` | Replace large tool results with file references (first third) |
|
||||
| `/skinnify` | Full context thinning (entire context window) |
|
||||
| `/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 summarization 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 summarization
|
||||
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
|
||||
|
||||
---
|
||||
|
||||
## /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 summarization 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)
|
||||
/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-summarization 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-summarization (if `auto_compact = true`) |
|
||||
| 90% | Aggressive thinning before tool calls |
|
||||
|
||||
Manual commands give you finer control over when and how this happens.
|
||||
Reference in New Issue
Block a user