GitLocal

Website: gitlocal.dev — screenshots, feature overview, and one-line install.

Community: got an idea, a question, or a rough edge? Start a discussion or open an issue. GitLocal is built in the open, and your input shapes it.

When AI agents do most of the code generation, direct hand-editing of source files becomes the exception rather than the default. A full IDE can be overkill for that. GitLocal focuses on the work humans still need to do constantly: browse the codebase, understand structure, read Markdown documents clearly, inspect changes, and make small edits when needed. Editing remains possible, but the product is optimized first for navigation, reading, review, and lightweight intervention — plus an integrated terminal for when you need to hand something back to an agent.

Everything runs locally, there are no accounts or telemetry, and any clone, fetch, pull, or push action goes through your installed git only when you choose it.

---

Requirements

Dependency	npm package	macOS app
Node.js	22+	Bundled in the app
git	2.22+	2.22+

---

Choose an Install

Choose the npm package for any OS, or the native macOS app if you'd rather skip the terminal. Both run the same GitLocal server and React viewer — the Mac app is a native wrapper around the same code, not a separate fork.

Option	Best for	What you get	Tradeoff
npm package	macOS, Windows, and Linux users who are comfortable with a terminal	One-command install, opens in your browser, mature distribution	The terminal process must stay open while GitLocal is running
macOS app beta	Mac users who want GitLocal to behave like an app	Homebrew install, opens as GitLocal.app, no terminal needed after install	Unsigned beta app — one extra command is required or macOS Gatekeeper blocks it from opening

Option 1: npm Package

npm install -g gitlocal

Open a folder or repository:

gitlocal .

GitLocal starts a local server, opens your default browser, and prints the local URL:

gitlocal listening on http://localhost:54321

Keep that terminal window open while you use GitLocal. Press Ctrl+C when you want to stop it.

You can also run GitLocal without installing it globally:

npx gitlocal

Option 2: macOS App Beta

Install with Homebrew:

brew tap ehud-am/gitlocal
brew install --cask gitlocal

Then open GitLocal.app from your Applications folder.

The macOS app starts the same local GitLocal service in the background for the app session, shows the viewer in an embedded WebKit window, and stops the service when the app quits. You do not need to keep a terminal open.

On first launch, the app asks before setting GitLocal as the default Markdown reader. If you accept, double-clicking .md and .markdown files in Finder opens GitLocal, activates the file's local folder or repository, and selects the Markdown file in the preview. If you decline, GitLocal leaves your current Markdown default unchanged. You can also choose GitLocal > Set as Default Markdown Reader later from the macOS app menu.

Unsigned beta notice: the current Mac app is not signed or notarized with an Apple Developer ID. Without the command below, macOS Gatekeeper blocks it from opening at all — this isn't just a dismissible warning. After installing, run:

xattr -dr com.apple.quarantine /Applications/GitLocal.app

Then open GitLocal.app normally. Future signed releases should remove this extra step.

Upgrade the app:

brew update
brew upgrade --cask gitlocal

Uninstall the app:

brew uninstall --cask gitlocal

Which One Should I Use?

Use the npm package if you want the most mature and portable install path, especially on Windows or Linux.

Use the macOS app beta if you are on a Mac and want a normal app experience without a running terminal. It is aligned with the npm version, but the one-time xattr step above is required until the app is signed and notarized.

---

What GitLocal Helps With

• Browse local projects with a lazy-loading, keyboard-navigable file tree (arrow keys, Enter/Space) for regular folders and git repositories.
• Keep several files open in tabs, like a code editor: opening a file adds a tab next to a folder tab, and closing the last file tab returns to the folder view. Open tabs survive a reload.
• Read Markdown clearly in the normal repository viewer with GitHub-like rendering, relative links, heading anchors, rendered find highlights, and share/copy actions.
• Preview beyond code, locally with built-in PDF, SVG, CSV, Excel (.xlsx/.xls), PowerPoint (.pptx), and HTML viewers alongside Markdown, JSON, and images — files GitHub's web UI often can't render inline and falls back to a raw download for.
• Start from useful repository context with a root dashboard for status, key documents, recent files, recently changed files, and raw directory browsing.
• Review background changes with active-file refresh/deletion notices and a changed-files panel for modified, deleted, untracked, generated, and local-only paths.
• Search intentionally with a separate repository search surface, current-folder and Markdown-focused scopes, generated/local controls, result counts, and file-level find inside the current file.
• Understand git state quickly through a plain-language repository summary with branch, remote, sync, and local-change context backed by technical badges.
• Make small edits safely by creating, updating, and deleting files directly from the viewer with dirty-navigation warnings and revision-token conflict protection.
• Manage folders by creating child folders or deleting subfolders with typed confirmation and impact counts.
• Switch branches safely with commit or discard confirmation when the working tree is dirty.
• Manage local git identity by saving repo-local user.name, user.email, and optional SSH key settings.
• Use an integrated terminal docked to the right, left, or bottom of the window (your choice is remembered), discoverable via a header button or the Ctrl+\`` shortcut (matching VS Code), with drag/keyboard-resizable size and cross-page session persistence. Every tab is a plain shell, so run claude, codex`, or anything else you like. Copy and paste with Cmd+C / Cmd+V on macOS or Ctrl+Shift+C / Ctrl+Shift+V on Windows and Linux; the terminal reconnects on its own after the computer sleeps.
• Share rendered Markdown through print, Save as PDF, local email/share flows, copy, and download fallbacks.

GitLocal supports light and dark themes. The macOS app also supports native menu and keyboard shortcuts for standard editing commands, preview-scoped Find, panel-scoped Select All, and Refresh.

---

Help Shape GitLocal

GitLocal is built in the open for people working with AI coding tools, and it gets better when those people tell us what they need. You don't have to write code to take part:

• Share an idea or a wish in Discussions → Ideas. Describe the job you're trying to get done, and we'll figure out the rest together.
• Ask a question or show how you use it in Q&A and Show and tell.
• Report a bug by opening an issue. Plain language and a screenshot are plenty.
• Build something. Browse help wanted and good first issue issues. Using an AI coding tool to write your change is welcome.

Taking part happens on GitHub and needs a free GitHub account. GitLocal itself still has no accounts and no telemetry. See CONTRIBUTING.md for the details.

---

Homebrew Troubleshooting

• If brew is not found, install Homebrew first from the official Homebrew site.
• If installation reports a checksum mismatch, run brew update and retry. Do not bypass checksum verification.
• If macOS blocks the beta app, run xattr -dr com.apple.quarantine /Applications/GitLocal.app, then launch it again.
• If your macOS version or processor architecture is unsupported, use the npm package until a compatible native artifact is available.
• If app launch fails, the npm browser workflow remains available as a fallback.

---

From Source

git clone https://github.com/ehud-am/gitlocal.git
cd gitlocal
npm ci
npm --prefix ui ci
npm run build

Run the built CLI from the repository root:

# Open the current repository
node dist/cli.js .

# Open a specific repository
node dist/cli.js ~/projects/my-app

# Open the folder picker
node dist/cli.js

---

Development

Prerequisites

• Node.js 22+

Run in dev mode

# Terminal 1: backend with auto-restart on changes
npm run dev:server

# Terminal 2: Vite dev server for the frontend
npm run dev:ui

Use both commands together during development:

• npm run dev:server starts the backend in watch mode
• npm run dev:ui starts the Vite frontend with hot reload

Run tests

npm test

Runs backend tests (Vitest + coverage) and frontend tests. All source files must maintain ≥90% branch coverage per file. Frontend component tests also include automated accessibility checks for key browsing surfaces.

Backend tests only

npm run test:server

Build

npm run build

Builds the React frontend and compiles the Node.js CLI into dist/cli.js.

Build and run the macOS native app from source

On macOS with Xcode installed, build the shared GitLocal app and the native wrapper:

packaging/macos/release/package-app.sh

This runs the normal npm build, builds GitLocal.app, bundles the server/UI assets, copies the local Node runtime into the app bundle, and creates a local unsigned artifact in packaging/macos/release/artifacts/.

List the generated artifacts:

ls packaging/macos/release/artifacts/

Or open the artifact folder in Finder:

open packaging/macos/release/artifacts/

Launch the locally built app:

open native/macos/build/Build/Products/Release/GitLocal.app

Validate the local app bundle:

packaging/macos/release/test-package.sh

Validate the local Homebrew cask against the generated artifact:

packaging/macos/cask/test-install-cask.sh \
  packaging/macos/cask/gitlocal.rb \
  packaging/macos/release/artifacts/GitLocal-$(node -p "require('./package.json').version")-macos.zip

The local app is unsigned unless you run the signing/notarization release flow. It is intended for development validation, not public distribution.

Full verification

npm run verify

Runs tests, builds, and dependency audits for both the root package and the UI package.

---

Architecture

GitLocal is a Node.js CLI that serves a React SPA:

gitlocal/
├── src/
│   ├── cli.ts           — entry point: arg parsing, server start, browser/app-mode launch
│   ├── server.ts        — Hono app, route registration, static serving + SPA fallback
│   ├── git/
│   │   ├── repo.ts      — repo metadata, branch helpers, deferred git context, README lookup, repository-local identity, and file sync state
│   │   ├── identity-settings.ts — SSH private key path expansion, discovery, and validation
│   │   └── tree.ts      — listDir (git ls-tree wrapper, sorted dirs-first)
│   ├── services/
│   │   └── repo-watch.ts — working-tree revision and sync status snapshots for the UI
│   └── handlers/
│       ├── repo.ts      — /api/info, /api/readme, /api/branches, /api/commits, /api/repo/open, and git-specific repo actions
│       ├── file.ts      — /api/tree and /api/file
│       ├── folder.ts    — /api/folder browsing, setup, create, and delete actions
│       ├── sync.ts      — /api/sync
│       └── search.ts    — /api/search
└── ui/src/
    ├── App.tsx                      — layout, repo sync polling, deferred git context, dialogs, README auto-load, picker mode
    ├── components/
    │   ├── FileTree/                — lazy expand/collapse tree
    │   ├── Breadcrumb/              — path navigation
    │   ├── ContentPanel/            — Markdown, code, image, binary rendering, and local file editing
    │   ├── ContentTabs/             — file tab strip above the content panel
    │   ├── RepoContext/             — branch switcher, sync summary, repo metadata, and identity editing
    │   └── Picker/                  — PickerPage table browser with setup actions
    └── services/api.ts              — typed fetch wrappers for all endpoints

Optional macOS native app distribution:

native/macos/           — Swift/AppKit/WebKit wrapper for GitLocal.app
packaging/macos/        — Homebrew cask, package, checksum, and release helpers

Key design decisions:

• No external runtime dependencies beyond Node.js for the product core — all git operations shell out to the local git binary via child_process.spawnSync
• Primary npm toolchain — build, test, and install the cross-platform package via npm; macOS app packaging adds scoped Swift and shell/Ruby release helpers outside the npm package
• Shared app code across distributions — npm and Homebrew use the same TypeScript server and React UI; the Mac wrapper only owns native windowing, service lifecycle, and packaging
• Hash-based routing — HashRouter means the server only needs to serve index.html for all non-asset routes
• Local-first editing and repo awareness — GitLocal can create, update, and delete files in folder roots and repository working trees while using git commands for branch, repository metadata, changed files, and conflict-safe revision checks

---

API

All endpoints are served under /api/:

Endpoint	Description
GET /api/info	Active root metadata (name, branch, isGitRepo, pickerMode)
GET /api/git/context	Deferred git identity and selected remote context for the active repository
GET /api/readme	Detects and returns the README filename for the current repo
GET /api/branches	List of branches with isCurrent flag
POST /api/branches/switch	Switch branches with dirty-tree confirmation flows
POST /api/git/commit	Compatibility route for creating a local commit; not exposed in the current repository UI
POST /api/git/sync	Compatibility route for remote sync; not exposed in the current repository UI
PUT /api/git/identity	Save repository-local user.name, user.email, and optional SSH command behavior in local git config
GET /api/git/identity/ssh-keys	List valid SSH private keys from the user's conventional SSH folder
POST /api/git/identity/ssh-key/validate	Validate an arbitrary SSH private key path before saving it
GET /api/tree?path=&branch=	Directory listing (dirs first, alphabetical)
GET /api/file?path=&branch=	File content with type and language detection
GET /api/repo/summary?branch=	Plain-language repository status, key documents, and local/generated visibility context
GET /api/repo/changes?branch=&includeGeneratedLocal=	Changed-file review items with status, availability, and local/generated labels
GET /api/repo/navigation-hints?branch=&includeRecent=&includeGeneratedLocal=	Key documents and navigation shortcuts for the root dashboard
GET /api/search?query=&branch=&mode=&caseSensitive=&rootPath=&contentKinds=&trackedMode=&limit=&cursor=	Scoped repository search across file names, contents, Markdown, current folder, and generated/local modes
POST /api/file	Create a new file in the current folder root or repository working tree

---

License

MIT — see LICENSE.

---

Contributing

Ideas, questions, bug reports, and pull requests are all welcome. See Help Shape GitLocal for where to start, and CONTRIBUTING.md for how to make a code change. Please follow the Code of Conduct, and report security problems privately per SECURITY.md. Code changes follow the GitLocal constitution, including ≥90% branch coverage per file, which CI checks for you.