Forge — A Terminal Launcher for AI Coding Assistants

Why I Built Forge

AI coding assistants (Claude Code, Codex, Cursor, etc.) have become part of my daily toolkit, but the startup ritual drives me crazy:

1. cd ~/Projects/some-project
2. Think about which assistant to use this time
3. Dig through shell history for the right command and flags
4. Hit Enter… only to realize the path was wrong

Multiply that by a dozen project switches a day and you’re bleeding real time on pure ceremony. What I actually want is: pick a project → pick a tool → Enter → go, three steps, done.

That’s why Forge exists.

What It Is

Forge is a terminal launcher purpose-built for AI coding assistants. The core flow is three steps:

Select project directory → Select startup command → Auto-execute

It scans all first-level subdirectories under a root you specify, lets you fuzzy-search to the right project, pick a command from a predefined list, then automatically switches into that directory and runs the command.

The whole thing takes under 3 seconds.

Tech Choices

Why Go

The last thing a terminal tool should require is “install a runtime first.” Python needs venv, Node needs npm — Go compiles to a single binary. brew install and you’re done.

Why the Charm Ecosystem

Traditional terminal UI libraries (like promptui or survey) get the job done but look dated. Charm provides a complete TUI stack:

• Bubble Tea: Elm-architecture TUI framework with clean state management
• Bubbles: Ready-made components (text input, list selection, fuzzy search)
• Lip Gloss: Terminal styling engine with gradients, borders, and alignment

This lets Forge deliver: gradient ASCII Art banners, rounded-border panels, real-time fuzzy filtering, a cursor indicator bar on the left… all rendered natively in the terminal, zero graphical dependencies.

Architecture

The project follows Go’s standard layout:

forge/
├── cmd/forge/main.go    # Entry point — one line of code
├── internal/
│   ├── app/             # CLI orchestration: flag parsing, flow control
│   ├── config/          # JSON config read/write (with legacy config migration)
│   ├── runner/          # Command execution (process replacement on Unix)
│   ├── scan/            # Directory scanning and filtering
│   └── ui/              # TUI components: banner, fuzzy search, style system
└── .goreleaser.yaml     # Automated release config

A few design decisions worth highlighting:

Process Replacement, Not Subprocesses

On Unix systems, Forge uses syscall.Exec to replace the current process entirely, rather than spawning a child with exec.Command. This means the AI assistant fully takes over the terminal — signal handling, stdin/stdout all pass through seamlessly, behaving identically to running the command directly. On Windows, it gracefully falls back to subprocess mode.

Smart Directory Scanning

The scanner only looks at first-level subdirectories under root, automatically filtering out noise like .git, node_modules, target, dist, and vendor. It also handles the edge case where a symlink points to a directory.

ANSI Color Adaptation

The entire style system uses ANSI color indices 0–15 instead of hard-coded hex values. This means Forge’s color scheme automatically follows your terminal theme — Catppuccin looks like Catppuccin, Dracula looks like Dracula, beautiful out of the box with zero configuration.

Configuration

Config lives at ~/.config/forge/config.json with a minimal structure:

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

• root: Default scanning directory
• commands: List of selectable startup commands — add or remove freely
• projects: Project bookmarks that skip scanning and jump straight to a path

First run will guide you through setting root; after that, just edit the config file.

Installation

# macOS (recommended)
brew install LittleBunVerse/tap/forge

# From source
go install github.com/LittleBunVerse/forge/cmd/forge@latest

Once installed, just type forge and you’re ready to go.

Final Thoughts

Forge solves a small problem — but it’s a small problem you repeat dozens of times every day. Automating these high-frequency, low-value motions frees up attention for what actually matters.

The project is fully open source (Apache 2.0). Issues and PRs are welcome.