Local Code Browser

A mobile-first, read-only code browser for a local source tree and its Git history, with a responsive interface that also works on desktop. The Go server embeds and serves a native ES module frontend from static/js. No npm installation is required.

Requirements

• A modern browser with native ES module support
• Git is optional; the server uses go-git by default

Usage

From the repository root:

./scripts/go.sh run ./cmd/code-browser
./scripts/go.sh run ./cmd/code-browser /path/to/project --no-open

The server browses the current directory by default, listens at http://127.0.0.1:8787/, and opens that address in the default browser. Use --no-open, --host, and --port to change this behavior.

Use the native Git executable when it is available instead of the default go-git backend:

./scripts/go.sh run ./cmd/code-browser /path/to/project --native-git

If the executable is unavailable, --native-git falls back to go-git.

To expose the browser over a trusted Tailscale network, for example:

./scripts/go.sh run ./cmd/code-browser /path/to/project --host 0.0.0.0 --no-open

There is no authentication, authorization, or TLS. A client that can reach the server can browse hidden, Git-ignored, and .git contents under the configured root, and the API reports that root's absolute path. Only bind to a non-loopback address on a trusted network, and use the host firewall or Tailscale access controls to restrict access.

Check that the root can be opened and report whether the required static assets exist without starting the server:

./scripts/go.sh run ./cmd/code-browser --check

Features

• Lazy directory exploration, including hidden and Git-ignored entries
• Seti file and folder icons for common languages and file formats
• Multiple source and diff tabs with automatic two-second refresh
• UTF-8 source viewing with Highlight.js syntax highlighting and change markers
• Project search and in-file find with match-case, whole-word, and result navigation controls
• Pan and zoom previews for PNG, JPEG, GIF, WebP, AVIF, APNG, BMP, ICO, and SVG files
• Multipage PDF rendering with pan, zoom, and viewport tile cleanup
• Git branch and working-tree status, including staged, unstaged, renamed, deleted, conflicted, and untracked files
• Unified tracked and untracked-file diffs
• Responsive Diff2Html views with context, layout, text-wrapping, and linked-scroll controls
• Root-scoped commit history, changed files, root commits, rename information, and per-file commit diffs
• Root containment checks that reject path traversal and paths resolving outside the configured root

The server is read-only. It handles API operations with GET, does not provide file-writing operations, and invokes native Git with optional locking disabled. It never stages, commits, resets, checks out, or otherwise mutates the browsed repository.

Media eligibility and response types are selected from an extension allowlist; file signatures are not inspected. Media is streamed from a separate endpoint with MIME sniffing disabled. SVG files are displayed as isolated image resources and served with a restrictive sandbox policy; their markup is never inserted into the application DOM.

Limits And Scope

• Source files and untracked-file diffs are limited to 2 MiB. Recognized images and PDFs are not subject to that byte-size limit.
• Project search accepts queries up to 256 characters and returns at most 500 results. It skips binary, non-UTF-8, and files larger than 2 MiB.
• In a Git repository, project search uses git ls-files --exclude-standard, so ignored files appear in the Explorer but are excluded from search.
• The tracked working-tree diff compares against HEAD, combining staged and unstaged changes.
• The interface loads 50 root-scoped commits from the current HEAD; the API accepts a maximum of 100.
• Git commands time out after 20 seconds.
• PDF rendering releases off-screen tile canvases, but images and complete PDF documents can still consume memory according to their decoded size.

Structure

• cmd/code-browser contains the CLI and server lifecycle.
• internal/httpserver contains the HTTP routes and embedded-asset serving.
• internal/workspace contains confined filesystem browsing and search.
• internal/gitrepo contains the default go-git and optional native Git backends.
• static/index.html and static/style.css define the application shell and presentation.
• static/js/app.js wires the API, sidebar, and viewer ES modules together.
• static/js/api.js, icons.js, highlighter.js, sidebar.js, and viewer.js contain the frontend concerns.
• static/vendor contains the bundled third-party browser assets and their license notices.
• server.py, workspace.py, and git_repository.py retain the Python reference implementation.
• Go tests cover the workspace, both Git backends, HTTP integration, and CLI parsing.

Syntax Highlighting

Highlight.js 11.11.1 and its common language set are bundled with the tool, along with the CMake grammar, so normal use works without internet access. When a recognized language is not in the local bundle, the browser attempts to load only that grammar from the version-pinned jsDelivr copy of the official Highlight.js CDN release. The request URL identifies the grammar but does not include source content. The downloaded script executes in the application page, so block jsDelivr or work offline when source confidentiality requires all code to remain local. If the request fails, source remains available as escaped plain text.

Third-Party Notices

The Explorer's base SVG shapes are adapted from Microsoft Codicons, copyright Microsoft Corporation and licensed under CC BY 4.0.

The bundled Seti icon theme font, associations, and colors are copyright Microsoft Corporation and Jesse Weed and licensed under the MIT license. Its license and attribution notices are retained in static/vendor/seti.

Highlight.js is copyright Ivan Sagalaev and contributors and licensed under the BSD 3-Clause license. Its complete license text is retained in static/vendor/highlightjs/LICENSE.

Diff2Html is copyright Rodrigo Fernandes and licensed under the MIT license. Its complete license text is retained in static/vendor/diff2html/LICENSE.md.

PDF.js 6.1.200 is copyright Mozilla Foundation and contributors and licensed under the Apache License 2.0. Only its minified display runtime and worker are bundled; the complete license text is retained in static/vendor/pdfjs/LICENSE.

Tests

./scripts/go.sh test ./...
python3 test_server.py

Pull requests build and test Linux AMD64. Pushes and merges to master, version tags matching v*.*.*, and manual runs cross-compile Windows, macOS, and Linux artifacts for AMD64 and ARM64, with a SHA-256 file for each archive. The resulting Windows AMD64, macOS ARM64, and Linux AMD64 artifacts are verified and tested on native runners, including race, backend, and live-server smoke tests. Version tags create a GitHub Release containing all six archives and checksum files after the full matrix passes.

Development

Install the pinned Go toolchain locally under the ignored .tools directory. The wrapper keeps Go caches inside the repository:

./scripts/setup-go.sh
./scripts/go.sh test ./...

The setup script currently supports macOS and Linux on amd64 and arm64. It checks for curl, tar, and either sha256sum or shasum before downloading.

License

Local Code Browser is available under the MIT License. See LICENSE.