Forge

Standalone AI CLI for repositories that contain a .ai/ directory.

Forge turns a repo-local .ai workspace into a usable terminal workflow for planning, execution, fixing, review, and prompt inspection. It discovers the target repository automatically, assembles prompts in a fixed context order, and invokes Codex through a dedicated runner.

Why Forge

Most AI-assisted repo workflows start as shell scripts glued to prompt files. That works at first, then breaks down when you need:

• a stable command interface
• reusable behavior across multiple repositories
• deterministic prompt assembly
• backward compatibility for existing task files
• prompt debugging without invoking the model

Forge is the standalone layer that sits on top of .ai/ and handles that orchestration.

Features

• Standalone CLI for any repository that contains .ai/
• Automatic repository root detection by walking upward to .ai/
• Deterministic prompt assembly for task-based workflows
• Centralized prompt builder shared by plan, run, fix, review, and prompt
• Per-invocation caching for heavy context files
• Backward compatibility with existing markdown task files
• Interactive and non-interactive Codex execution modes for task commands
• Prompt debugging via --print-prompt, --save-prompt, and forge prompt
• Self-hosted .ai workspace in this repository for developing Forge with Forge

Install

Build from source

git clone <your-repo-url>
cd forge-cli
go build -o forge ./cmd/ai

Optional global install

go build -o forge ./cmd/ai
sudo mv ./forge /usr/local/bin/forge

Requirements

• Go 1.24.3+
• Codex CLI available on PATH
• A target repository containing .ai/

Quick Start

1. Build Forge

go build -o forge ./cmd/ai

2. Move into a target repository

Forge does not require you to run commands from the repo root. It walks upward from the current directory until it finds .ai/.

cd /path/to/your/repo

If .ai/ is not found, Forge returns:

AI context directory (.ai) not found

3. Plan a task

forge plan feature_example

4. Run a task

forge run feature_example
forge run feature_example --mode exec

5. Fix a task-scoped issue

forge fix feature_example --error "undefined: builder"
forge fix feature_example --error "test is failing" --mode exec

6. Review current changes

forge review
forge review --staged
forge review internal/context/builder.go

7. Inspect the final assembled prompt

forge prompt feature_example
forge --print-prompt run feature_example
forge --save-prompt /tmp/feature_example.prompt run feature_example

Command Reference

forge plan <task>

Loads the task and repository context, assembles the planning prompt, and invokes Codex.

forge plan feature_transaction_history

forge run <task> [--mode interactive|exec]

Builds the execution prompt for a task and invokes Codex in the selected mode.

forge run feature_transaction_history
forge run feature_transaction_history --mode exec

forge fix <task> --error "<message>" [--mode interactive|exec]

Builds a fix prompt using the task context plus an explicit error message.

forge fix feature_transaction_history --error "panic: nil pointer dereference"

forge review [<path>] [--staged|--worktree]

Builds a review prompt using either:

• the current worktree diff
• the staged diff
• an explicit path target

forge review
forge review --staged
forge review internal/task/task.go

forge prompt <task>

Prints the fully assembled prompt without invoking Codex.

forge prompt feature_transaction_history

How Forge Works

Repository detection

Starting from the current working directory, Forge walks upward until it finds:

.ai/

That directory becomes the target repository root.

Task loading

Forge reads task files from:

.ai/tasks/<task>.md

It supports:

• explicit front matter metadata
• legacy markdown task files
• fallback filename-prefix routing when metadata is missing

Supported fallback prefixes:

• feature_*
• fix_*
• refactor_*
• test_*

Prompt assembly

All prompt construction goes through one builder pipeline. For task-based flows, Forge assembles prompts in this exact order:

1. task context
2. feature-map.md
3. symbol-map.md
4. repomap.md
5. file-index.md
6. architecture.md
7. framework-go-core.md
8. engineering-rules.md
9. ownership.md
10. prompt template

This ordering is deterministic.

Context caching

Forge caches these files for the lifetime of a single CLI invocation:

• feature-map.md
• repomap.md
• symbol-map.md

There is no persistent on-disk cache in the current version.

Codex execution

All Codex CLI execution goes through a runner abstraction that handles:

• command argument construction
• interactive vs exec mode
• prompt delivery via direct argument, stdin, or temp file
• structured execution results

.ai Workspace Layout

Forge expects a target repository to contain a structure like:

.ai/
  context/
    architecture.md
    engineering-rules.md
    feature-map.md
    file-index.md
    framework-go-core.md
    ownership.md
    repomap.md
    symbol-map.md
  prompts/
    breakdown.md
    execute.md
    fix.md
    review.md
    test.md
  tasks/
    template.md
    feature_example.md

This repository includes its own .ai workspace so Forge can run against forge-cli itself.

Developing Forge

Run tests

go test ./...

If your environment has a read-only default Go build cache, use:

GOCACHE=/tmp/forge-go-build go test ./...

Build the binary

go build -o forge ./cmd/ai

Use Forge against Forge

./forge prompt feature_self_host_workspace
./forge plan feature_self_host_workspace

Project Structure

forge-cli/
  cmd/ai
  internal/
    app/
    cli/
    codex/
    context/
    repo/
    task/
  pkg/forge/
  .ai/

Package responsibilities:

• cmd/ai: binary entrypoint
• internal/cli: command and flag parsing
• internal/app: application orchestration
• internal/repo: repository root detection
• internal/task: task parsing and compatibility
• internal/context: context loading and prompt building
• internal/codex: Codex runner abstraction
• pkg/forge: shared public types

Current Scope

Forge currently focuses on:

• local terminal workflows
• task-based prompt assembly
• Codex CLI orchestration

It is designed to grow into:

• CI integration
• multi-service awareness
• PR automation
• richer agent workflows

Notes

• forge review currently runs in the interactive review flow.
• forge prompt is the safest way to inspect prompt output while developing .ai content.
• The current README documents the implemented command surface, not planned future subcommands.