Getting Started

This page covers installing Forge and connecting your AI coding agent. Pick the path that matches the tools your team uses.

Requirements

• VS Code 1.101 or later (for the extension)
• GitHub Copilot subscription — or Claude Code / Codex
• Node.js 18 or later — nodejs.org

Install

Option A — VS Code extension (recommended for Copilot)

1. Open VS Code → Extensions (Cmd+Shift+X / Ctrl+Shift+X).
2. Search Protrak Forge (publisher: prorigo).
3. Click Install.

The extension auto-registers the Forge MCP server for any workspace that contains Types/, Programs/, or a .csproj referencing Prorigo.Protrak.Toolkit — no manual configuration needed. If your project layout differs, run Protrak Forge: Set Protrak Project Root… (see Project root).

Option B — npm CLI (Claude Code, Codex, or any MCP client)

npm install -g @prorigo/protrak-forge

This installs the protrak-forge command globally — a single self-contained Node.js file (no Python or extra setup).

Connect your agent

The easiest way to wire up any agent is the VS Code command Protrak Forge: Configure Agent Instructions — pick the tools your team uses (Claude Code / GitHub Copilot / Codex, multi-select) and it writes the right config and guidance files for each. It never overwrites a file that already exists.

Tool	Files it writes
Claude Code	AGENTS.md (shared guide) + CLAUDE.md (thin @AGENTS.md pointer) + .mcp.json (MCP server wiring) + one Skill per customization area under .claude/skills/forge-*/SKILL.md
Codex	AGENTS.md (shared with Claude Code, with a table linking to each Skill) + .codex/config.toml (MCP server wiring)
GitHub Copilot	.github/copilot-instructions.md (lean overview + table) + one applyTo-scoped instructions file per area under .github/instructions/forge-*.instructions.md

These guidance files teach the agent to fetch schema context before writing code, so it uses Forge proactively without you asking every session.

If you'd rather configure manually, the per-agent snippets are below.

GitHub Copilot (VS Code)

The extension auto-configures Copilot. If it isn't picking up (e.g. an older VS Code), add .vscode/mcp.json to your workspace:

{
  "servers": {
    "protrak-forge": {
      "type": "stdio",
      "command": "npx",
      "args": ["--yes", "@prorigo/protrak-forge@0"],
      "env": {
        "PROTRAK_PROJECT_ROOT": "${workspaceFolder}"
      }
    }
  }
}

Then open Copilot Chat (Cmd+Alt+I / Ctrl+Alt+I) and select Agent mode.

Claude Code

Add to .claude/settings.local.json in your customization repo (or ~/.claude/settings.json globally). Requires npm install -g @prorigo/protrak-forge first so protrak-forge is on your PATH:

{
  "mcpServers": {
    "protrak-forge": {
      "command": "protrak-forge",
      "type": "stdio",
      "cwd": "/path/to/MyProject.Customization"
    }
  }
}

Codex

Codex reads MCP servers from ~/.codex/config.toml. Requires the global npm install first:

[mcp_servers.protrak-forge]
command = "protrak-forge"
args = []
env = { "PROTRAK_PROJECT_ROOT" = "/path/to/MyProject.Customization" }

Codex reads project guidance from AGENTS.md natively.

Skills (Claude Code & GitHub Copilot)

Configure Agent Instructions writes one Skill per customization area — program-authoring, notification-templates, rule-authoring, widget-authoring, and schema-workflow — in whichever shape each selected tool actually understands:

• Claude Code / Codex → .claude/skills/forge-<area>/SKILL.md, a Claude Code Skill. Claude Code loads the matching skill automatically when you touch the area it covers (e.g. editing anything under Programs/), instead of always reading the full AGENTS.md. Codex doesn't auto-load skills, but it does read AGENTS.md natively, which gets a table linking to each one.
• GitHub Copilot → .github/instructions/forge-<area>.instructions.md, Copilot's own applyTo-scoped instructions file — this is the file Copilot actually auto-attaches when you edit a matching path. copilot-instructions.md itself stays a lean overview + table pointing at these.

Both are rendered from the same skill content, so they never drift from each other.

These platform skill files are safe to re-run over: each one carries a hidden managed-content marker, and re-running Configure Agent Instructions after a Forge update rewrites the file only if you haven't hand-edited it. If you have edited a platform skill directly, Forge leaves your version untouched and instead writes a <file>.incoming sibling (auto-added to .gitignore) so you can diff and merge by hand — you're then prompted to replace, keep (freeze it for good), or decide later. To add your own notes without risking that conflict, write them below the <!-- FORGE-PROJECT-NOTES-START --> marker at the bottom of the file — that section is never touched by Forge.

To add a skill Forge doesn't ship — your own team's conventions, a customer-specific pattern — run Protrak Forge: Create Project Skill…, give it a lowercase-hyphenated name (e.g. acme-invoice-workflow), and optionally a comma-separated applyTo glob scope (e.g. Programs/**,Widgets/**). It scaffolds .claude/skills/<name>/SKILL.md, and — if you gave a scope — a matching .github/instructions/<name>.instructions.md so Copilot auto-attaches it too. Project skills are entirely yours: Forge scaffolds the file(s) once and never revisits them. Names starting with forge- are reserved for platform skills and rejected.

Project root

Forge finds your customization project by looking for a .csproj referencing Prorigo.Protrak.Toolkit, or a folder containing both Types/ and Programs/.

If auto-detection misses, or you want to target a different folder in a multi-root workspace:

• VS Code: run Protrak Forge: Set Protrak Project Root… from the Command Palette and pick any folder.
• Claude Code / Codex: set the PROTRAK_PROJECT_ROOT env var (or cwd for Claude Code) in your MCP config, as shown above.

tip

The most reliable setup is to point Forge at the customization folder itself — the one containing Types/, Programs/, etc. — not a parent directory.

Updating

The VS Code extension updates automatically through the Marketplace and pulls a matching MCP server version via npx (major version pinned for safety). To force-update the CLI manually:

npm install -g @prorigo/protrak-forge@latest