FORGE Documentation

What is FORGE?

FORGE is a cross-platform desktop application built for developers who want more control over AI-assisted coding. Unlike a general-purpose chatbot, FORGE is structured around engineering tasks: persistent project context, multi-model prompting, file-aware agents, integrated terminal and browser panels, Git workflows, and configurable automations.

AI requests are routed through a managed backend that proxies to providers (OpenAI, Anthropic, Google, DeepSeek, xAI). Beta users install the desktop app without supplying their own API keys.

Getting started

1. Download and install the desktop app from the FORGE website. Windows installers (.msi / .exe) are supported.
2. Sign in via GitHub or Google from the account menu in the activity bar (bottom-left). Authentication enables account features, XP progression, and GitHub integration for repository operations.
3. Create a project from the Projects sidebar or Ctrl+N for a new agent. Link a local folder to give agents file context.
4. Configure your Model Cart in the Agent Cart sidebar — select which AI models participate in your Round Table.
5. Start chatting in the main workspace. Use @ to target specific models and attach files or folders for context.

Interface layout

FORGE uses an IDE-style layout similar to VS Code, optimized for AI engineering workflows.

Title bar

Custom window chrome with the FORGE wordmark, application menu bar (File, Edit, View, Go), and native minimize/maximize/close controls on Windows. The title bar is draggable to move the window.

Activity bar (left rail)

Icon strip for switching primary sidebar views:

• Model Cart — browse and select AI models for your Round Table.
• Projects — project list, chat history, and file tree.
• Source Control — Git status, staging, commits, and sync. Shows a badge with pending change count.
• Settings — opens the full settings page.
• Account menu — sign in, XP bar, and logout.

Left sidebar

Context panel that changes based on the active activity bar icon. Shows the project tree, chat/project list, Git panel, or Model Cart. Collapsible via Ctrl+B or View → Toggle Left Sidebar.

Main workspace

The central area holds agent tabs, chat messages, the composer, and optional split panes. A toolbar provides quick access to Terminal, Browser, and layout controls. The bottom or side panel hosts integrated terminal and browser tabs.

Status bar

Footer strip showing composer hints (/ for commands, @ for context), GitHub auth status, and system health indicator.

Projects & workspaces

A project (also called a workspace) is a container for one or more agents, linked folders, and chat history. Projects persist locally and appear in the Projects sidebar.

Creating and managing projects

• New Project — File → New Project, or use the + button in the Projects panel.
• Rename — right-click a project or use inline rename when creating.
• Pin — pin important projects so they stay at the top of the list.
• Delete — remove projects you no longer need via the context menu.
• Folder linking — add local directories to a project so agents can read and write files within permitted paths.

Project tree

When a folder is linked, the Projects panel shows a file tree. Each node has an access checkbox that grants the AI full context, read, and write access to that path and its children. Hover a folder or file to reveal the checkbox. Disabled paths are excluded from agent context.

Project settings

Per-project configuration (in Agent/Chat Settings):

• Project name — display name shown in sidebars and navigation.
• Project description — free-text context injected into agent prompts so models understand the project's purpose.
• Project tools — tag external tools or services the project uses (e.g. Vercel, Supabase). Enter names and press Enter to add.
• File context folders — explicitly add folders beyond the project tree for AI context.

Chat history panel

Lists all saved projects/workspaces. Selecting one opens it in the main workspace. Shows linked context folder labels beneath each entry. Supports search, rename, pin, and delete.

Agents & chat

Each project can have multiple agents — independent chat threads with their own name, system prompt, and permission set. Agents appear as tabs in the workspace and can be split into side-by-side panes.

Creating agents

• New Agent — File → New Agent (Ctrl+N) or the + tab button.
• Split layout — drag agent tabs to create horizontal or vertical splits, each running an independent agent.
• Close agents — click × on a tab. If the agent is still generating, you'll be prompted to confirm stopping the response.

Agent settings

Open via the gear icon on the chat utility bar or File → Agent Settings:

• Agent name — custom display name (defaults to "Agent 1", "Agent 2", etc.).
• System prompt — instructions that define the agent's role and behavior for every conversation turn.
• Permissions — granular toggles for Terminal, File read, File write, Browser, In-app settings, and Git commands. Use "Allow all" for full capability.

Chat composer

The message input at the bottom of each agent pane supports:

• Multi-line input with Enter to send (Shift+Enter for newline).
• Attachments — attach files via picker or drag-and-drop from the OS or project tree.
• Prompt optimization — AI-powered rewrite that improves clarity while preserving meaning (uses GPT-4o). Includes undo.
• Stop generation — cancel an in-progress response.
• Drag project files into the composer to reference them in your message.

Message behavior

Configure per-project in Agent Settings:

• Auto-scroll — automatically scroll to new messages as they arrive.
• Queued message behavior — choose what happens when you send while the agent is busy:
  • Wait to send — queue until the current reply finishes.
  • Stop and send — cancel the current reply and send immediately.
  • Prevent early sending — disable the send button while the agent is working.

Messages & activity

• Messages render with syntax-highlighted code blocks and model attribution.
• Round Table discussion — when multiple models are active, a live indicator shows which model is "speaking" and when answers are being synthesized.
• Forge activity — file read/write actions performed by agents appear as structured activity chips in messages.
• Undo/redo — revert composer and workspace changes with Edit → Undo/Redo or Ctrl+Z / Ctrl+Shift+Z.
• Find in chat — search within the current conversation (Ctrl+F).
• Navigate messages — jump to previous/next message with Ctrl+↑ / Ctrl+↓.

Global agent management

Settings → Agents lists all active agents across projects with search. Click any agent to open its full settings dialog without navigating to the project first.

Model Cart & Round Table

FORGE's multi-model system lets you curate a personal lineup of AI models and choose how they participate in each conversation.

Model Cart

Open the Agent Cart sidebar to browse models grouped by provider (ChatGPT, Claude, Gemini, DeepSeek, Grok). Search filters by name, provider, or role. Toggle models on/off to add or remove them from your Round Table. Click a provider row to expand its model list.

Round Table

When multiple models are active, FORGE runs a Round Table: each model contributes in turn, then a synthesis step combines their outputs into one unified response. The discussion indicator shows progress through participating models.

• Model dock — vertical strip beside the chat showing active models. Click to toggle a model on/off for the current message.
• Reorder — drag models in the dock to change Round Table speaking order.
• Weights — each model has a weight that influences synthesis priority. Weights persist across sessions.

Auto vs. manual mode

• Auto mode — FORGE analyzes your prompt and automatically selects the best model(s) from your cart based on task type (code, reasoning, research, creative, fast, etc.). Click any model in the dock to switch to manual mode.
• Manual mode — you choose exactly which models respond. Toggle individual models or use keyboard shortcuts.

Model keyboard shortcuts

Default cart on first launch: GPT-4o, Claude 3.5 Sonnet, and Gemini 2.5 Flash.

Prompting tools

@ Mentions

Type @ in the composer to mention a model from your cart. Mentions route the message to specific models regardless of auto/manual mode. Autocomplete appears as you type, matching by model ID or display name. Completed mentions are highlighted in the composer.

/ Slash commands

Type / to open slash command autocomplete. Available commands include agent slot shortcuts (/a1, /agent1, etc.), model shortcuts (/GPT-4o), and edit commands (/undo, /redo).

Prompt optimization

Click the optimize button in the composer to have GPT-4o rewrite your draft prompt for clarity and structure without changing intent. An undo button restores your original text.

Attachments

Attach files via the attachment button or by dragging files into the composer. Supports native OS file picker, drag-and-drop from the desktop, and drag from the project tree. Duplicate filenames are deduplicated automatically.

File context & permissions

FORGE gives agents awareness of your codebase through folder linking, per-node permissions, and explicit file context configuration.

How context works

• Link a local folder to a project — the file tree appears in the Projects sidebar.
• Enable access on folders/files — agents can read (and optionally write) within enabled paths.
• Add explicit context folders in Agent Settings for paths outside the main project tree.
• Drag files from the tree into the composer to reference them in a message.

Agent permissions

Each agent has six independent permission toggles:

Project memory

FORGE maintains an internal project memory system that tracks agent decisions, file changes, tool results, and task notes. When queries reference history or prior context, relevant memory records are retrieved and ranked by relevance, recency, and importance.

Terminal & browser

Integrated tool panels live in the workspace bottom or side area, toggled from the toolbar or View menu.

Terminal

• Full xterm.js terminal with fit-to-pane sizing.
• Opens in the project directory (CWD follows the active project's linked folder).
• Multiple terminal tabs supported — create via File → New Terminal or Ctrl+`.
• Tabs can be split horizontally or vertically alongside browser tabs.
• Drag tabs to rearrange or split the panel layout.

Embedded browser

• Native embedded webview for browsing documentation, testing web apps, or viewing URLs agents reference.
• Multiple browser tabs with independent sessions.
• Toggle via View → Browser or the globe icon in the workspace toolbar.
• Supports split layouts with terminal tabs in the same panel group.

Panel management

• Show/hide the entire bottom panel from the toolbar.
• Split panes support 2- or 3-way layouts with draggable dividers.
• Panel sizes persist across sessions.

Source control (Git)

The Source Control sidebar provides Git integration for linked project folders.

Repository setup

• Existing repo — link a folder that already contains a .git directory.
• Initialize — create a new Git repository in the project folder.
• Clone — clone a remote repository into the project directory (supports GitHub auth).

Working with changes

• View staged and unstaged changes grouped in collapsible sections.
• File status indicators: Modified (M), Added (A), Deleted (D), Renamed (R), Untracked (U), Conflicted (!).
• Stage files individually or stage all when committing.
• Write a commit message and commit with Ctrl+Enter.
• AI commit message — generate a commit message from staged changes using AI, or get a quick heuristic suggestion.

Sync & branches

• Branch selector to view and switch branches.
• Pull, push, fetch, and sync (push when ahead with no local changes).
• Ahead/behind indicators show sync status relative to remote.
• Refresh button to re-scan repository state.

GitHub authentication

Sign in with GitHub from the account menu to enable authenticated clone, push, and pull operations. Auth status appears in the status bar.

Layouts & appearance

Layout presets

• Vertical Default — chat panes stacked vertically with the tool panel below.
• Horizontal Default — chat panes arranged side-by-side with the tool panel beside them.

Switch layouts via the layout grid button in the workspace toolbar, View → Appearance, or Settings → Appearance. Thumbnail previews show each layout arrangement.

Saved layouts

Save up to two custom layout snapshots that capture your current panel sizes, split arrangement, and visibility state. Click an empty saved slot to capture; click a filled slot to restore. Delete saved layouts with the × button.

Theme

Settings → Appearance → Theme: choose System, Dark, or Light. The app defaults to dark mode.

Resizable panels

Drag dividers between the sidebar, chat area, tool panel, and split panes. Sizes persist in local storage. Collapse the left sidebar with Ctrl+B.

Navigation & menus

Application menu

Go to panels

Go → Go to Agent (Ctrl+Shift+O) or Go to Project opens a searchable quick-switcher with recent items. Type to filter, arrow keys to navigate, Enter to select.

Settings search

The settings page includes a search bar that indexes all settings sections and individual options. Results jump directly to the relevant panel.

Settings

Open via the gear icon in the activity bar. Settings are organized into sections:

General

• Forge Account — link to manage account and billing on the web.
• System Notifications — OS notifications when an agent completes or needs attention (shown when app is backgrounded).
• Warning Notifications — in-app toast alerts for warnings.
• System Tray Icon — keep FORGE accessible from the Windows system tray.
• Completion Sound — audio cue when an agent finishes responding.
• Data Sharing — opt in or out of sharing prompts, edits, and usage data to improve FORGE.
• Log Out — end the current session.

Appearance

• Theme selector (System / Dark / Light).
• Layout picker with presets and saved layout slots.

Plan & Usage

• Free plan token usage bar with limit tracking.
• Tokens sent (input), tokens received (output), and estimated cost across all models.
• Per-model usage breakdown sorted by input tokens.
• Reset usage statistics.
• Link to pricing plans.

Usage is tracked locally from chat sessions. Cost estimates use public API pricing and are approximate.

Models

• Default Model — the model FORGE prefers when auto mode selects a single model.

Agents

Global view of all active agents grouped by project. Search, inspect summaries, and open individual agent settings.

Automation

See the Automations section below.

Workflows, Plugins, Rules

Coming soon These settings sections are reserved for future features: visual workflow tools, plugin extensions, and persistent AI rules/guidelines.

Automations

Automations let you schedule agent tasks or trigger them reactively based on project events. Configure in Settings → Automation.

Creating an automation

1. Click New to open the builder.
2. Give it a name (e.g. "Nightly dependency review").
3. Choose a trigger type and configure its parameters.
4. Write the agent task — instructions the agent receives when the automation fires.
5. Save. Toggle the switch on the list to enable or disable.

Trigger types

Time based (schedule)

• Every hour — runs at the top of each hour.
• Daily — runs once per day at a specified time (local timezone).
• Weekdays — runs Monday–Friday at a specified time.
• Weekly — runs on a chosen day of the week at a specified time.
• Custom interval — runs every N minutes (minimum 15).

Agent completion

Runs after an agent finishes its current task. Scope options:

• Any agent — triggers when any agent in any project completes.
• Specific agents — pick individual agents to watch.
• Specific projects — triggers when any agent in selected projects completes.

Event based

• Git commit — after a new commit is detected. Optional branch filter (e.g. main, release/*).
• File changed — when a file matching a glob pattern changes (e.g. src/**/*.ts).
• Branch pushed — when a branch is pushed to remote. Optional branch filter.
• Pull request opened — when a new PR is created. Optional target branch filter.

Agent task

The task field contains the prompt/instructions sent to an agent when the automation triggers. Be specific about what to review, summarize, or act on. The agent runs in the context of its configured project.

Notifications

• System notifications — when enabled, FORGE sends native OS notifications if an agent completes or needs attention while the app is minimized or unfocused. Includes workspace and agent name in the notification.
• Completion sound — optional audio feedback when an agent finishes responding, even when the app is focused.
• Warning toasts — in-app toast messages for warnings (configurable).
• System tray — optional tray icon for background presence on Windows.

Account & authentication

Sign in

Authenticate via GitHub or Google from the account menu (bottom of the activity bar). Sign-in enables XP progression, GitHub Git operations, and account-linked features.

XP & levels

Creating new agents awards XP. Progress is tracked per account with a level bar shown in the account menu. Levels cap at a maximum tier with color-coded progress indicators.

GitHub integration

GitHub auth (separate from sign-in) enables authenticated remote Git operations — clone private repos, push, and pull. Status shown in the status bar and account menu.

Google sign-in

Google OAuth is supported as an alternative sign-in provider. The OAuth callback is handled by a dedicated route in the app.

Keyboard shortcuts

Supported AI models

Models available in the Model Cart, grouped by provider:

ChatGPT (OpenAI)

• GPT-4o — Code generation, general purpose
• GPT-4 Turbo — General purpose
• o1 — Deep reasoning

Claude (Anthropic)

• Claude 3.5 Sonnet — Reasoning & analysis
• Claude 3 Opus — Complex analysis

Gemini (Google)

• Gemini 2.5 Pro — Research & context
• Gemini 2.5 Flash — Fast responses
• Gemini 2.0 Flash — Fast responses
• Gemini 2.5 Pro (Direct) — Deep reasoning
• Gemini 3.5 Flash — Cutting edge
• Gemini 3.1 Flash Lite — Ultra-fast responses
• Gemini 3.0 Flash / Pro (Preview) — Next-gen models
• Gemini 3.1 Pro (Preview) — Cutting edge pro

DeepSeek

• DeepSeek Coder — Specialized coding tasks

Grok (xAI)

• Grok 4.3 — General
• Grok 4.20 Fast — Low latency
• Grok 4.20 Reasoning — Deep reasoning
• Grok 4.20 Multi-Agent — Multi-agent orchestration
• Grok Code — Coding

Model availability depends on which providers are configured on the managed backend. Not all models may be available in every deployment.

Coming soon

Features referenced in the codebase or roadmap but not yet fully implemented:

• Workflows — visual workflow tools for multi-agent collaboration.
• Plugins — extension system for third-party integrations.
• Rules — persistent AI rules and guidelines (similar to Cursor rules).
• Better file indexing — codebase-wide search and indexing.
• Advanced agent orchestration — deeper multi-agent coordination beyond Round Table.