Skip to main content

​
Overview

Forge provides powerful conversation management features that allow you to track, resume, analyze, and optimize your AI interactions. Each conversation maintains its own context, history, and state.

​
Conversation Basics

​
Automatic Conversation Creation

By default, Forge creates a new conversation for each session: 
forge "Implement user authentication"
# Creates new conversation automatically

​
Explicit Conversation ID

You can specify a conversation ID to continue an existing conversation: 
# Using --conversation-id flag
forge --conversation-id abc123def456 "Continue implementation"

# Short form
forge -c abc123def456 "Add error handling"

​
Conversation Commands

​
List Conversations

View all conversations in the current workspace: 
# Interactive list (allows selection)
forge conversation list

# Machine-readable format
forge conversation list --porcelain
Output shows:
  • Conversation ID
  • Title (generated from content)
  • Last updated time
  • Message count
  • Token usage

​
Create New Conversation

Explicitly start a fresh conversation: 
forge conversation new
Use this when you want to ensure a clean context without any prior history.

​
Resume Conversation

Continue an existing conversation in interactive mode: 
forge conversation resume <conversation-id>
This:
  • Loads the full conversation history
  • Switches to interactive mode
  • Allows you to continue the conversation naturally

​
Show Conversation

Display the last assistant message from a conversation: 
# Rendered output
forge conversation show <conversation-id>

# Raw markdown
forge conversation show <conversation-id> --md
Useful for:
  • Reviewing what was last discussed
  • Getting quick reminders
  • Extracting information from past conversations

​
Conversation Info

Get detailed information about a conversation: 
forge conversation info <conversation-id>
Shows:
  • Conversation metadata
  • Creation and update timestamps
  • Model used
  • Configuration settings
  • Related conversations

​
Conversation Statistics

View usage statistics for a conversation: 
# Human-readable format
forge conversation stats <conversation-id>

# Machine-readable format
forge conversation stats <conversation-id> --porcelain
Displays:
  • Total messages (user and assistant)
  • Input tokens used
  • Output tokens generated
  • Total cost
  • Cache performance (hits/misses)

​
Advanced Features

​
Dump Conversation

Export conversation data for archival or analysis: 
# Export as JSON
forge conversation dump <conversation-id> > conversation.json

# Export as HTML
forge conversation dump <conversation-id> --html > conversation.html
JSON format includes:
  • All messages with full content
  • Tool calls and results
  • Metadata and timestamps
  • Token usage per message
HTML format provides:
  • Human-readable conversation view
  • Syntax highlighting for code
  • Formatted markdown rendering

​
Compact Conversation

Reduce token usage by compacting conversation history: 
forge conversation compact <conversation-id>
This:
  • Summarizes older messages
  • Preserves recent context
  • Reduces token count
  • Maintains conversation coherence
Compaction is IrreversibleCompacted messages cannot be restored to their original form. Consider dumping the conversation first if you want to preserve the full history.

​
Clone Conversation

Create a copy of a conversation with a new ID: 
# Clone conversation
forge conversation clone <conversation-id>

# Machine-readable output
forge conversation clone <conversation-id> --porcelain
Useful for:
  • Branching from a specific point
  • Creating templates
  • Experimenting with different approaches
  • A/B testing prompts

​
Retry Last Message

Retry the last assistant turn without modifying context: 
forge conversation retry <conversation-id>
This:
  • Keeps the same conversation context
  • Generates a new response
  • Useful when the previous response was incomplete or unsatisfactory

​
Delete Conversation

Permanently remove a conversation: 
forge conversation delete <conversation-id>
Deletion is PermanentDeleted conversations cannot be recovered. Consider exporting important conversations before deletion.

​
Programmatic Usage

​
Generate Conversation ID

Generate a new conversation ID without creating a conversation: 
forge conversation new --generate-id
Use this to:
  • Pre-allocate IDs for workflows
  • Create ID references before starting
  • Integrate with external systems

​
Run with Conversation ID

Start Forge with a specific conversation: 
# Non-interactive mode
forge run --conversation-id <id> "Continue the implementation"

# Interactive mode
forge --conversation-id <id>

​
Conversation Workflows

​
Long-Running Project Workflow

1
Initialize Project Conversation
2
forge "Analyze this codebase and create a refactoring plan"
# Note the conversation ID from output
3
Work in Sessions
4
# Day 1
forge --conversation-id <id> "Implement phase 1 of the plan"

# Day 2
forge --conversation-id <id> "Continue with phase 2"

# Day 3
forge conversation show <id>  # Review progress
forge --conversation-id <id> "Complete final phase"
5
Review and Archive
6
forge conversation stats <id>
forge conversation dump <id> --html > project-summary.html

​
Experimentation Workflow

1
Create Base Conversation
2
forge "Design a new API endpoint for user management"
# Save conversation ID: abc123
3
Try Different Approaches
4
# Clone for approach A
forge conversation clone abc123
# Returns: def456
forge --conversation-id def456 "Use REST architecture"

# Clone for approach B  
forge conversation clone abc123
# Returns: ghi789
forge --conversation-id ghi789 "Use GraphQL architecture"
5
Compare Results
6
forge conversation show def456 > approach-a.md
forge conversation show ghi789 > approach-b.md
diff approach-a.md approach-b.md

​
Cost Optimization Workflow

1
Monitor Usage
2
# Check conversation stats regularly
forge conversation stats <id> --porcelain
3
Compact When Needed
4
# If token count is high, compact
forge conversation dump <id> > backup.json
forge conversation compact <id>
5
Review Impact
6
# Compare stats before and after
forge conversation stats <id>

​
Context Management

​
Understanding Context Windows

Forge automatically manages context:
  • Recent messages are always included
  • Older messages are summarized when necessary
  • Tool results are managed for relevance
  • Context window adapts to model limits

​
Manual Context Control

Control context size through compaction: 
# Compact to reduce tokens
forge conversation compact <id>

# Or start fresh when context is no longer relevant
forge conversation new

​
Context Preservation

Important context is preserved through:
  • Automatic summarization
  • Smart message selection
  • Tool result caching
  • Conversation metadata

​
Integration with Other Features

​
With Sandboxes

# Start conversation in sandbox
forge --sandbox experiment "Try new approach"
# Note conversation ID

# Resume in same sandbox
forge --sandbox experiment --conversation-id <id>

​
With Custom Agents

# Use agent with specific conversation
forge --conversation-id <id> agent test-generator "Add more tests"

​
With Data Processing

# Continue data processing in existing conversation
forge data process --conversation-id <id> input.jsonl schema.json

​
Configuration

​
Maximum Conversations

Control how many conversations are shown in lists: 
# .env
FORGE_MAX_CONVERSATIONS=100  # Default is 100

​
Conversation Storage

Conversations are stored in:
  • Local workspace: .forge/conversations/
  • User directory: ~/.config/forge/conversations/
Storage format:
  • SQLite database for metadata
  • JSON files for message history

​
Best Practices

​
Naming and Organization

While conversation IDs are auto-generated, you can organize through:
  • Consistent commit messages
  • Clear initial prompts (used for title generation)
  • Regular cleanup of unused conversations

​
When to Start New Conversations

Create a new conversation when:
  • Starting a completely different task
  • Context from previous conversation isn’t relevant
  • Token usage is too high
  • You want to try a different approach

​
When to Continue Conversations

Resume an existing conversation when:
  • Building on previous work
  • Context is still relevant
  • Following a multi-step plan
  • Iterating on a solution

​
Regular Maintenance

# Monthly cleanup script
#!/bin/bash

# List all conversations
forge conversation list --porcelain > conversations.txt

# Review and delete old ones
while read -r conv_id; do
    echo "Review: $conv_id"
    forge conversation info "$conv_id"
    read -p "Delete? (y/n) " -n 1 -r
    if [[ $REPLY =~ ^[Yy]$ ]]; then
        forge conversation delete "$conv_id"
    fi
done < conversations.txt

​
Troubleshooting

​
”Conversation not found”

Check that:
  • Conversation ID is correct
  • You’re in the right workspace
  • Conversation wasn’t deleted
forge conversation list --porcelain | grep <id>

​
High Token Usage

Reduce token consumption: 
# Compact the conversation
forge conversation compact <id>

# Or start fresh
forge conversation new

​
Lost Conversation

Find conversations: 
# List all conversations
forge conversation list

# Search by recent activity
forge conversation list --porcelain | head -10

​
Performance Optimization

​
Cache Usage

Forge uses caching to reduce costs:
  • Conversation metadata is cached
  • Tool results are cached when applicable
  • Model responses use prompt caching when available
Monitor cache performance: 
forge conversation stats <id> --porcelain | grep cache

​
Token Reduction Strategies

  1. Regular compaction: Compact long conversations
  2. Focused prompts: Be specific to reduce back-and-forth
  3. Tool usage: Let tools provide context instead of long explanations
  4. New conversations: Start fresh when context shifts
Conversation LimitsWhile conversations have unlimited context through automatic summarization:
  • Very long conversations may become slower
  • Token costs increase with conversation length
  • Regular compaction is recommended for active conversations

Build docs developers (and LLMs) love

Get started for freeTalk to us