Forge

English | 简体中文

---

English

Forge is a terminal-based launcher designed for AI programming assistants (e.g., Claude Code, Codex). It enables rapid project switching within a "Root" directory and automates the execution of startup commands.

🌟 Key Features

• Effortless Navigation: No more constant cd or path hunting.
• Unified Startup: Consolidate commands and arguments for various AI tools.
• Persistent Context: Remember your default Root directory while allowing overrides.
• Smart Scanning: Automatically ignores .git, node_modules, and other noise for a snappy UI.

🚀 Installation

via Homebrew (Recommended for macOS)

brew install LittleBunVerse/tap/forge

From Source

go install github.com/LittleBunVerse/forge/cmd/forge@latest

⌨️ Quick Start

Run it directly:

forge

The first run will guide you through setting up your default scanning directory (Root).

Specify a temporary Root:

forge --root "~/Projects"
# or simply
forge "~/Projects"

🛠 Common Commands

• forge config: Display current configuration.
• forge config set-root <path>: Update the default scanning directory.
• forge root: Shorthand for updating the root.

⚙️ Configuration

The configuration is stored in ~/.config/forge/config.json.

{
  "root": "/Users/you/Projects",
  "commands": [
    { "name": "Claude Code", "command": "claude", "args": [] },
    { "name": "Codex", "command": "codex", "args": [] }
  ],
  "projects": [
    { "name": "my-app", "path": "~/Projects/my-app" }
  ]
}

🌍 Environment Variables

• FORGE_ROOT: Override the default root directory.
• FORGE_CONFIG_DIR: Specify a custom configuration directory.
• XDG_CONFIG_HOME: Follows XDG base directory specification.

🔍 Scanning Rules

• Depth: Scans only the first level of the root directory.
• Exclusions: Automatically ignores directories starting with . (e.g., .git) and common noise such as node_modules, target, dist, and vendor.

🛠 Development

# Run tests
go test ./...

# Local build
go build -o forge ./cmd/forge