Forge Optimizer

When to Use

• Running /forge-optimizer command (with conversation title, --latest, or --project)
• Reviewing agentic execution quality

Prerequisites

• npx tsx is available (tsx is installed globally)
• pg npm package is installed in Forge/Skills/Forge_Optimizer/scripts/node_modules/ (run npm install in that folder if missing)
• Network access to the internal Postgres instance is available
• OPENAI_API_KEY is present in the environment (read from /proc/1/environ)
• Forge/Skills/Forge_Optimizer/references/extraction_prompt.md exists

Procedure

Export Railway env vars before running the script (they are not in process.env by default):

eval $(cat /proc/1/environ | tr '\0' '\n' | grep -E '^(OPENAI_API_KEY|FORGE_DB_URL)=' | sed 's/^/export /')

Single-conversation mode

npx tsx Forge/Skills/Forge_Optimizer/scripts/optimize.ts "Conversation Title"
npx tsx Forge/Skills/Forge_Optimizer/scripts/optimize.ts --latest
npx tsx Forge/Skills/Forge_Optimizer/scripts/optimize.ts --list

Project mode

npx tsx Forge/Skills/Forge_Optimizer/scripts/optimize.ts --project Project_Automation
npx tsx Forge/Skills/Forge_Optimizer/scripts/optimize.ts --project Project_Automation --model <model>

In project mode, the script queries AgentJob for all conversations associated with the project, builds a combined transcript from all of them, and analyzes the project as a whole. This provides cross-conversation insights like repeated mistakes, knowledge gaps, and workflow inefficiencies.

The default model for each mode is determined by the use case (see Forge/Skills/Choose_AI_Model/Models/ for current models and their quirks). The user can override with --model.

When running in project mode, also check for persisted evaluation report files ({Project}_Eval_{N}.md, {Project}_Spec_Eval.md, etc.) in the project directory and include them as supporting context for the analysis.

The script saves the report to {Project}_Optimizer_Report.md in the project folder. If the file already exists, a new ## Run — {date} section is appended; otherwise the file is created with frontmatter and a header. After the script completes, spawn the Page Manager bot via spawnAgent with { botGroup: 'forge', botHandle: 'page-manager' } to add the sidebar entry (if the file is new), build, commit, push.

Generate runs summary

npx tsx Forge/Skills/Forge_Optimizer/scripts/generate-runs.ts Project_Automation
npx tsx Forge/Skills/Forge_Optimizer/scripts/generate-runs.ts Project_Automation --output /tmp

This generates a {Project}_Runs.md file with per-conversation agent, model, task, duration, tokens, and cost data.

Single-conversation mode: Output the analysis directly in the conversation — do not create a report file. Ask if the user wants to implement any of the checked findings.

Project mode: The script saves the report to {Project}_Optimizer_Report.md in the project folder. After spawning Page Manager to commit the file, present a summary of findings in the conversation and ask if the user wants to implement any of them.

What the Scripts Do

optimize.ts

1. Connects to Postgres — see Forge/Skills/Choose_AI_Model/Models/ for model-specific quirks
2. Fetches conversation(s) + all messages, builds a redacted transcript
3. Sends transcript + the extraction prompt to the selected model using references/extraction_prompt.md
4. Prints the analysis to stdout (agent presents it in conversation)
5. In project mode: saves the report to {Project}_Optimizer_Report.md in the project folder (creates or appends)

generate-runs.ts

1. Connects to Postgres (AgentJob and messages)
2. Queries all jobs for the given project
3. Computes token usage and cost per conversation
4. Generates {Project}_Runs.md from the Runs_Template

Rules

• Treat the prerequisites above as preconfigured environment requirements, not setup steps
• If any prerequisite is missing, stop and report a skill/environment contract failure
• Never analyze the current conversation — only past ones
• Consult Forge/Skills/Choose_AI_Model/Models/ for model defaults, quirks, and parameter requirements
• User can override model with --model flag in either mode
• Present findings to user before implementing any changes