Skip to main content

​
Your First Session

Let’s start your first Forge session. Make sure you’ve completed the installation first.
1

Start Forge

Open your terminal and run:
forge
If this is your first time, Forge will guide you through provider setup:
forge provider login
2

Ask a question

Once in interactive mode, try asking about your project:
> What files are in this directory?
Forge will analyze your current directory and provide detailed information.
3

Make a change

Ask Forge to help with a task:
> Create a simple Python script that prints 'Hello, Forge!'
Forge will create the file and explain what it did.
4

Exit the session

Type exit, quit, or press Ctrl+D to end the session.

​
Core Commands

Forge offers powerful CLI commands for various workflows: 
# Start interactive session
forge

# Start with specific agent
forge --agent sage

# Continue previous conversation
forge --conversation-id abc-123

# Start in specific directory
forge -C /path/to/project

​
Common Workflows

​
Code Exploration

Understand your codebase quickly: 
forge -p "explain how authentication works in this codebase"
Forge will:
  1. Analyze your project structure
  2. Identify authentication-related files
  3. Explain the authentication flow
  4. Show relationships between components

​
Feature Development

Implement new features with AI guidance:
1

Start interactive session

forge
2

Describe your feature

> I need to add a dark mode toggle to our React application
3

Review the plan

Forge will suggest an approach based on your codebase.
4

Implement

> Let's implement the dark mode using context API
Forge will create the necessary components and styles.
5

Test and refine

> Add tests for the dark mode toggle

​
Debugging

Get help diagnosing and fixing issues: 
forge
> I'm getting "TypeError: Cannot read property 'map' of undefined"

​
Code Review

Get instant feedback on code quality: 
forge -p "review the code in src/components/UserProfile.js and suggest improvements"
Forge analyzes:
  • Readability: Clear naming, structure, comments
  • Performance: Optimization opportunities
  • Security: Potential vulnerabilities
  • Maintainability: Code smells, refactoring suggestions

​
Working with Agents

Forge includes specialized agents for different tasks:
The general-purpose coding agent. Best for:
  • Code understanding and explanation
  • Feature implementation
  • Debugging and problem-solving
  • Refactoring
forge --agent forge
Use forge list agent to see all available agents and their descriptions.

​
Configuration Basics

​
Set Your Preferred Model

# View available models
forge list model

# Set default model
forge config set model claude-3.7-sonnet

# Override for single session
forge --model o3-mini-high

​
Manage Providers

# List configured providers
forge list provider

# Add new provider
forge provider login

# Switch provider
forge config set provider OpenAI

# Remove provider credentials
forge provider logout

​
View Configuration

# Show all configuration
forge info

# Get specific value
forge config get model

# List all config options
forge config list

​
Conversation Management

Forge maintains conversation context across sessions:

​
Continuing Conversations

# List recent conversations
forge conversation list

# Resume specific conversation
forge conversation resume abc-123

# Continue with new prompt
forge --conversation-id abc-123 -p "continue implementing the feature"

​
Exporting Conversations

# Export as JSON
forge conversation dump abc-123

# Save to file
forge conversation dump abc-123 > conversation.json

​
Conversation Operations

# Show last assistant message
forge conversation show abc-123

# View conversation statistics
forge conversation stats abc-123

# Clone conversation with new ID
forge conversation clone abc-123

# Delete conversation
forge conversation delete abc-123

​
Slash Commands

While in interactive mode, use slash commands for quick actions:

/model

Switch models mid-conversation
/model claude-3.7-sonnet

/agent

Switch to different agent
/agent sage

/help

Show available commands
/help

/clear

Clear conversation history
/clear
Type / and press Tab to see all available slash commands with descriptions.

​
Tips for Better Results

Provide context and details for better responses:Good: “Refactor the user authentication in auth.js to use async/await instead of promises”Too vague: “Fix the auth code”
Forge understands your project structure. Reference files and directories:
> Explain how the components in src/components/ interact with the API in src/api/
Don’t expect perfection on the first try. Iterate:
> Create a user registration form
> Add email validation
> Add password strength indicator
> Style it to match our design system
Different agents have different strengths:
  • forge: Implementation and coding
  • sage: Architecture and design
  • muse: Brainstorming and exploration
Resume conversations to maintain context:
forge conversation resume abc-123
This preserves all previous context and decisions.

​
Advanced Features

Once you’re comfortable with the basics, explore these advanced features:

Semantic Search

Index your codebase for intelligent semantic search

Model Context Protocol

Integrate external tools and services via MCP

Custom Agents

Create specialized agents for your workflow

Custom Commands

Define reusable command shortcuts

Shell Integration

Transform natural language to shell commands

Configuration File

Deep customization with forge.yaml

​
Next Steps

1

Explore Your Project

Try different questions about your codebase:
forge -p "what's the overall architecture of this project?"
2

Set Up Shell Integration

Enhance your terminal experience:
forge setup
3

Index Your Workspace

Enable semantic search:
forge workspace sync
4

Create Custom Configuration

Create a forge.yaml file in your project:
model: claude-3.7-sonnet
temperature: 0.7
custom_rules: |
  - Always add error handling
  - Include unit tests
  - Follow our team's naming conventions
5

Join the Community

Connect with other Forge users on Discord and share your experience!

​
Getting Help

Discord

Join our community

GitHub

Report issues and contribute

Documentation

Explore full documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us