A visual way to manage every git repository on your computer, built to look like an instrument panel rather than a dashboard template.

Forgeline installs as an npm package, starts from your terminal, and opens a local web interface on 127.0.0.1. It is a visual layer over the real git CLI — it never reimplements git, and every action can show you the exact command it ran.

Lagoon, the default

Cathode — amber CRT warmth

Paper — light and quiet

Three groups, one interface:

• People who are afraid of git. Plain English first, with the raw git output behind a toggle when you want it.
• Developers who want a faster visual layer. Staging, diffs, branches and history without typing, and without losing the command line.
• Non-developers who only need to save and share files. A commit is one button and one sentence.

These are not aspirations; they are constraints the code is held to.

• Local first. Everything except the actions that contact a remote (fetch, pull, push, publish a release) works with no internet. No account is needed unless a remote asks for one.
• Wrap the git CLI. The real git is always run, through one wrapper module, with argument arrays. Never a git library.
• Never lose your work. Uncommitted work is never discarded without a snapshot first. Undo is offered only where recovery is proven by tests; everything else says plainly that it cannot be undone, and why.
• Explain, don't hide. Every action can show the command behind it.
• Looks hand-designed. An instrument panel, not a dashboard template: layered surfaces, hairlines, registration ticks, and a heat ramp where recent work runs hot and old work runs cold. Every glow, gradient, and texture has to encode information or help orientation, or it is deleted.

Appearance has two controls: a family (the palette) and a mode (dark or light). A family that does not support a mode says so rather than offering a broken one. Effects — motion, glow, blur, grain — have their own control, defaulting from your system's reduced-motion setting, and can be turned off entirely without losing any information.

A family that cannot do a mode disables the control and says why, rather than offering a switch that would do nothing.

Surfaces are Glass (translucent, ambient gradient, blur) or Solid (opaque and flat). Effects Off forces Solid and removes all motion.

Working end to end, not yet published. Every milestone in the build prompt is built and tested:

• Dashboard. Discovers repositories in folders you pick, with live branch, changed-file, and ahead/behind counts pushed over a local stream as files change.
• Commit flow. See what changed, stage and unstage whole files or individual hunks, read both staged and unstaged diffs, and commit behind a sanity-check card that names every staged file before anything is written.
• Safety. Every action that changes a repo is written to an action journal in your OS app-data folder and never inside a repository; an Undo timeline lists them newest first with the exact git command behind a toggle, and an Undo button appears only where recovery is proven by tests. Rescue mode snapshots, parks HEAD under a private backup ref so no local commit is lost, then resets the repo to a clean tree.
• Errors. A failing git command comes back as a plain-English card with buttons that repair it, and the raw output one click away. Forgeline also keeps a local record of which fixes actually worked.
• Remotes. Fetch, pull, push, and an ahead/behind indicator, with GitHub sign-in through the OAuth device flow and a token your OS keychain owns.
• Branches, stash, history, blame. A lane-coloured log every branch draws at once, blame per file, the full stash stack, and branch create, switch, track, rename and delete.
• Conflicts. When a merge stops, the resolver appears on its own — it is the one state in git that does not go away by itself. Each file is shown with all three versions beside it, and three answers in the same words.
• Releases. Version bump, changelog, tag, and a release commit, with the plan stated before anything is done. Nothing pushes: a release only leaves this computer when you push it. Leaving the commit out is a checkbox, not the default, because a tag has to name the release and the release has to exist first.
• Simple mode. Save and Send, with plain wording, for people who want to save files and not learn git.
• Extras. A command palette on Ctrl/Cmd-K, the gitignore doctor, SSH key help, and per-repository notes stored on this computer only.

No control is drawn for a feature that is not built, so nothing is a dead button.

The Undo timeline, with the saved snapshot and the command behind it:

The log every branch draws at once, lanes coloured so a split is visible before you read a line:

A release, with its plan stated before anything is done — this is the version now, this is what it becomes, these are the commits it contains:

The gitignore doctor, which reads the project type off the real files rather than from a list:

The package has not been published to npm, and the name forgeline has not been checked for availability. Do not treat it as installable yet.

See docs/status.md for the milestone table, what is verified, and the exact next step.

Forgeline is vibecoded: written by AI agents working from a detailed build prompt, with a human directing the work and reviewing the output. It is not maintained by a team, and it has not been audited by anyone who did not write it.

That is worth knowing before you trust it with your repositories. The tests are real and they run against real git repositories in throwaway temp directories, but they were also written by the same agents that wrote the code, so they share its blind spots. Treat this as a project to read and learn from, not as infrastructure to depend on yet.

The build process is documented rather than hidden:

• docs/spec.md — the original build prompt the agents worked from. Source of truth for what gets built.
• docs/decisions.md — every deviation from the spec, and why. The spec is never edited; changes are recorded here.
• docs/architecture.md — module map, request flow, and the git execution rules.
• docs/status.md — milestone table, verified flows, known limitations, and the next step.
• docs/progress.md — an append-only log of every slice, including the bugs found and the fixes.

If you want to see how an AI-built project handles the parts that usually go wrong, docs/progress.md is the honest record: it keeps the mistakes.

• Node.js 22 or newer (24 recommended). Check: node --version.
• git 2.31 or newer. Forgeline checks on startup and refuses to start on older git. Check: git --version.
• Linux, macOS, or Windows. The code makes no assumptions about one operating system — paths, line endings, shells, and keychain access are all platform-aware — but only Linux has actually been run. macOS and Windows are untested, and docs/status.md says so. There is a CI workflow that runs npm run verify on all three; until it has passed, treat the other two as claims rather than facts.

Once it is published:

npm install -g forgeline
forgeline            # start on an OS-assigned port and open the browser
forgeline 4700       # start on a specific port
forgeline --no-open  # start without opening a browser

It has not been published yet, and the name forgeline has not been checked for availability — so the commands above are what it will be, not what it is. Do not treat it as installable yet.

From a checkout, after npm ci:

npm run build          # build the frontend and the server
node dist/cli.js       # start on an OS-assigned port and open the browser
node dist/cli.js 4700  # start on a specific port
node dist/cli.js --no-open

Forgeline prints a URL containing a one-time token and opens it in your browser. That token is exchanged for an HttpOnly, SameSite=Strict session cookie and removed from the address bar. It is single-use and expires after five minutes; if it expires, press Enter in the terminal for a fresh one.

• No port given: bind port 0 and use whatever the OS assigns.
• A free port: use it.
• A port already in use: print Port <n> is in use. Try <n+1>, or run forgeline with no port. and exit non-zero. It never silently moves.
• An invalid port: print the error and the usage line, and exit non-zero.

The server binds 127.0.0.1 only. It is never reachable from your network.

Forgeline never scans your whole disk. You pick folders — it suggests ~/code, ~/projects, and ~/Documents — and it searches those only, to a bounded depth. It skips node_modules and hidden folders, does not descend into a repository it has already found, and follows no symlinked directories.

Results refresh on their own. Forgeline watches each repository's .git/HEAD, .git/index, and .git/refs and pushes changes to the open page. On filesystems where native watching does not work, such as some network drives, it falls back to polling every three seconds and says so in the sidebar rather than going quietly stale.

Settings, notes, and caches live in your operating system's standard app-data folder, never inside a repository.

Because this is a local app driving real git, the surface is worth stating plainly.

• Bind: 127.0.0.1 only.
• Auth: every /api/* route requires the session cookie. There is no password and no account.
• Host and Origin: a request with a foreign Host header is rejected with 403, which blocks DNS rebinding. Writes also require an allowed Origin and Content-Type: application/json.
• Opaque IDs: the browser never sends a filesystem path. It sends an ID the server issued, and a forged ID resolves to nothing.
• Path handling: repo-relative paths are checked lexically, then re-resolved and re-checked, so a symlink swapped in after registration cannot escape the repository.
• Secrets: tokens are never written to a URL that persists, a config file, or a log. Sign-in, when it lands, stores credentials in your OS keychain.

This is a guard against other websites and other local processes reaching your repositories through the browser. It is not a sandbox: anyone who can already write to the built files or to your repositories can already do what this app does.

npm run dev:web     # Vite dev server for the frontend only
npm run build       # build frontend (dist/web) and server (dist/)
npm run verify      # typecheck + lint + lint:copy + unit tests + e2e tests
npm test            # unit tests only (vitest)
npm run test:e2e    # end-to-end tests (Playwright, 1440px and 800px)

npm run verify is the gate. Nothing is committed to main unless it is green.

There is a GitHub Actions workflow, .github/workflows/verify.yml, that runs verify on Linux, macOS, and Windows on Node 22 and 24. It has never been run against a real push, because this repository's CI is not enabled — so the three operating systems remain untested claims rather than verified ones.

End-to-end tests need a browser once:

npx playwright install chromium

To refresh the screenshots above, with npm run build already done:

node scripts/capture-screenshots-design.mjs   # the themes shown above
node scripts/capture-screenshots-m2.mjs       # the earlier milestone-2 set

src/cli.ts                    commander CLI: port rules, startup, clean shutdown
src/server/index.ts           Hono app: auth, routes, static serving, SSE
src/server/git/git.ts         the only module that runs git
src/server/git/diff.ts        changed-file records and unified-diff parsing
src/server/journal.ts         the action journal, written to app-data
src/server/errorHistory.ts    which errors happened and which fix worked
src/server/git/errors.ts      the error translator and its rule catalogue
src/server/git/branches.ts    list, create, switch, track, rename, delete
src/server/git/stash.ts       save, apply, pop, drop, and the stack as one view
src/server/git/history.ts     the log, per-file history, and blame
src/server/git/conflicts.ts   read, resolve, finish, or abandon a stopped merge
src/server/git/release.ts     version bump, changelog, release commit, tag
src/server/git/doctor.ts      project type, .gitignore suggestions, untracked findings
src/server/git/ssh.ts         list SSH keys and their public halves
src/server/notes.ts           per-repository notes, stored in app-data only
src/server/snapshots.ts       private refs for pre-action recovery points
src/server/appdata.ts         resolves the OS app-data folder, never inside a repo
src/server/scan/              bounded repository discovery
src/server/live/              file watching with a polling fallback
src/server/queue.ts           per-repository single-writer queue
src/shared/types.ts           types shared by server and browser
src/web/src/theme/families.ts every colour, verified by scripts/check-contrast.mjs
src/web/src/theme/            ThemeProvider, tokens.css (structure only)
src/web/src/components/       RepoRail, StatusBar, CommandPalette, AppearancePanel,
                              BranchPanel, StashPanel, HistoryPanel, ConflictResolver,
                              ReleasePanel, DoctorPanel, SshPanel, NotePanel, SimpleBar
src/web/src/app/             App shell, API client, SSE-driven repo list
docs/                         spec, decisions, design, architecture, status, progress

The docs/ folder is the working record of the build, listed above under How this was built.

Two more, if you want them:

• AGENTS.md — the rules every session works under: reading order, commands, and the commit gate.
• docs/setup.md — what to install to run and test this on a new machine.

MIT. See LICENSE.

Copyright (c) 2026 porkfrnd.