Forge

Local, Finder-tagged kanban project management for macOS.
Kanban board · Finder tags · ordinary folders · no Forge-hosted servers.

---

Forge is a kanban board for project tracking built on ordinary folders and Finder tags. It is local-first: your projects live in your own directories, and Forge does not require any hosted service.

Who is Forge for?

Forge is for people who think in files and folders first, and who want a transparent system built on ordinary directories, Finder tags, and markdown files.

Forge works well if you:

• Prefer plain-text, markdown-based systems you can search, diff, and version-control with git.
• Want project state driven by Finder tags (including assignees as #Person tags).
• Want a kanban view for projects without a hosted backend.
• Care about local-first privacy: Forge uses no hosted servers.

For a longer tour of concepts and workflows, see the user manual in docs/forge-manual.md.

Components

Component	Description
forge CLI	Command-line interface for board views and project moves/tags
Forge.app	Menu bar companion and board window
Neovim plugin	Keymaps, commands, and dashboard integration via forge-nvim.lua

Project website

The public site is simonab.github.io/forge (fork: https://<user>.github.io/<repo>/). Landing page: docs/index.html with docs/assets/site.css and docs/favicon.svg.

The full documentation is also published as static HTML next to the landing page, generated from the same markdown as the repo (README.md, CHANGELOG.md, PRIVACY.md, docs/cli.md, docs/app.md, docs/neovim.md, docs/forge-manual.md):

Page	Source
docs/cli.html	docs/cli.md
docs/app.html	docs/app.md
docs/neovim.html	docs/neovim.md
docs/manual.html	docs/forge-manual.md
docs/privacy.html	PRIVACY.md
docs/readme.html	README.md
docs/changelog.html	CHANGELOG.md

Regenerate the *.html files after editing documentation:

pip install -r docs/requirements.txt   # once per environment
python3 docs/build_site.py

Commit the updated HTML so GitHub Pages serves the latest content.

To publish with GitHub Pages, open Settings → Pages, set Build and deployment to Deploy from a branch, branch main, folder /docs.

Quick start

Pre-built binaries (macOS 14+, Apple Silicon arm64):

• CLI: forge-macos-arm64.zip (includes LICENSE and install notes).
• Menu bar app: Forge-macos-arm64.app.zip — unzip and drag Forge.app into Applications. Updates use Sparkle (docs/appcast.xml): Check for Updates… and periodic automatic checks.

See all releases. Intel Macs: build from source with build.sh. Developers syncing source via iCloud typically still use build.sh below so the CLI and app stay in sync with local changes.

# On a fresh Mac where Forge source has synced via iCloud Drive:
zsh ~/Documents/Forge/build.sh

This builds the Swift project, creates /Applications/Forge.app, and registers a Launch Agent so the menu bar app starts at login. To put forge on your terminal $PATH, use Forge → Preferences… → Install CLI…. The script only touches the Forge source directory, ~/.forge-build, and your local application folders; it never sends any data off your Mac. See setup details.

Requirements

• macOS 14 or later.
• Xcode or Xcode Command Line Tools (for the Swift toolchain).
• Python 3 with Pillow (pip3 install Pillow) if you want the generated app icon (Forge will still work without this; a default icon is used).

Run build.sh once per Mac after your Forge directory has synchronised (for example via iCloud Drive or git). Your tasks and configuration remain plain-text files in the Forge directory, shared across machines however you choose to sync.

Privacy and data model

• All projects are ordinary directories under your configured workspace roots. Kanban state is stored as Finder tags on those directories.
• Forge keeps small local caches for performance. It does not require any Forge-hosted backend.
• You are free to keep the Forge directory under git, on an encrypted volume, or in a local-only folder if you prefer not to sync via any cloud service.

See PRIVACY.md for a fuller description of what Forge stores, how sync works, and how to run in markdown-only or local-only modes.

If you use an AI assistant with Forge output (for example pasting forge brief into a chat), you can choose what fits: Ollama with the Pi coding agent for privacy-first local inference on your Mac, or a cloud assistant when you need more capability — Forge stays agnostic. See AI assistants and local language models in PRIVACY.md for setup and trade-offs.

Directory layout

~/Documents/Forge/              Forge home (synced via iCloud Drive)
├── config.yaml                 Configuration (board columns, workspace roots, tags)
├── build.sh                  Per-Mac build & install script
├── generate_icon.py            App icon generator (requires Pillow)
├── Sources/                    Swift source code
├── Package.swift               Swift package manifest
└── docs/                       Documentation
    ├── cli.md
    ├── app.md
    └── neovim.md

~/Documents/Work/Projects/      Workspace (project directories)
├── ProjectA/
├── ProjectB/
└── ...

Projects are ordinary directories. Their kanban column is stored as a Finder tag (visible in Finder and readable by Spotlight).

Configuration

Start from config.sample.yaml and copy it to config.yaml, then adjust paths and names to match your setup. Key sections:

• workspace — path to the directory containing project folders.
• board.columns — ordered kanban columns, each mapped to a Finder tag.
• board.meta_tags — supplementary tags (e.g. Collab, Student, URGENT), used for per-project flags and for the board's Radar view.
• terminal — preferred terminal app (auto, iTerm, Terminal.app).

Multi-Mac sync

Source code and markdown files sync automatically via iCloud Drive. The compiled .build directory is kept outside iCloud at ~/.forge-build (symlinked into the source tree). Run build.sh on each new Mac to build locally.

Licence

Forge is distributed under the Apache License, Version 2.0. See the LICENSE file in this repository for the full text.