Open your first project
Forge has two top-level modes for talking to the agent.
Open mode has no project boundary. Use it for quick questions, throwaway scripts, and exploring something on disk that isn’t yet a project. Memory writes go to ~/.forge/scratchpad/.
Project mode is pinned to a folder. The agent’s working directory is the project root, memory writes go to <project>/.forge/, the file watcher keeps the index fresh, and engine bridges (Unity, Godot) auto-detect off the project root.
Project mode is where Forge earns its keep. The rest of this guide assumes you’re using it.
Open a project
Section titled “Open a project”Click the mode dropdown in the top-left of the title bar, then Open project, then pick a folder.
The first time you open a folder, Forge creates a .forge/ directory in it with a starter set of memory files (BRIEF.md, DESIGN.md, STACK.md, DECISIONS.md, PROGRESS.md, STYLE.md, ASSETS.md) and a tasks.toml template. These are plain markdown and TOML. Version-control them, edit them by hand, or let the agent propose updates.
If a project.godot file lives in the root, Forge enters Godot mode. If Assets/ plus ProjectSettings/ProjectVersion.txt are present, it enters Unity mode. Both are described in Engine modes.
Send your first message
Section titled “Send your first message”
The chat tab is open by default in the centre pane. Try:
Skim the BRIEF.md and DECISIONS.md files in .forge/ and tell me what this project is.
The agent reads them (memory injection happens automatically on every thread start) and responds.
What’s in .forge/
Section titled “What’s in .forge/”| File | Purpose |
|---|---|
BRIEF.md | Pitch, audience, scope, success criteria. |
DESIGN.md | Game design pillars, mechanics, narrative. |
STACK.md | Engine, plugins, dependencies, versions. |
DECISIONS.md | Append-only ADR-style decision log. |
PROGRESS.md | Current state snapshot (overwrite-safe). |
STYLE.md | Art direction, palette, tone. |
ASSETS.md | Asset registry. Auto-updated when Forge generates images, audio, etc. |
plan.md | Shared checklist between you and the agent. See Plan-mode loop. |
tasks.toml | Task definitions surfaced in the command palette. |
workspace.json | Per-project layout state (tabs, splits, terminal cwd). |
.index/memory.db | SQLite index for memory search. |
Full schemas live in Memory file formats.
- Quickstart by engine for Unity, Godot, or web setup.
- Concepts for the mental model before diving in.