Loom

Weave your branches. A local-first web dashboard for Git & GitHub: stage, commit, branch and push from one screen, see any repo as a tree or a commit graph, compare it against another folder, and read its files in a built-in viewer.

Loom is a single Python file plus a single HTML page. It runs on your own machine, listens only on 127.0.0.1, and shells out to the git you already have installed. No accounts, no cloud, no build step.

What is Loom for?

Loom is for anyone who wants the power of Git without juggling terminal commands:

• Beginners who want to see what staging, committing and branching actually do.
• Everyday developers who want a fast, one-screen workflow for stage → commit → push.
• Code readers who want to explore a GitHub repo (tree, history, files) without cloning it.
• Anyone reconciling two copies of a project, using the Compare tab to merge differences between folders safely.

Because everything runs locally and calls your real git, what you see in Loom is exactly what Git is doing.

Using the VS Code extension

Loom also runs inside VS Code, so you never have to leave the editor. There is no command to type and no folder path to paste: Loom picks up the folder you have open.

Using the extension? You can skip the Installation section below. That part is for running Loom on its own, without VS Code.

Quick start

1. Install the extension. Open the Extensions view, click the … menu, choose Install from VSIX… and pick the .vsix file. (Or run code --install-extension <file>.vsix in a terminal.) Reload the window when VS Code asks.
2. Open a repo folder. Use File → Open Folder… as you normally would.
3. Start Loom. Any one of these works:
   • Click the Loom icon in the Activity Bar, then press Open Loom.
   • Click Loom in the status bar at the bottom left.
   • Open the Command Palette (Ctrl/Cmd + Shift + P) and run Loom: Open for This Workspace.
4. First run only: Loom checks that Python 3.9+ and Git are installed, then creates its own private Python environment and installs fastapi and uvicorn into it. A progress notice appears while it works. This needs internet access to pypi.org once. Later starts take a couple of seconds.
5. Use it. Loom opens in a tab inside VS Code with your folder already filled in and the Tree tab showing. From there it works as described under Usage: stage files, commit, push, view the graph, compare folders.
6. Stop it when you are done. Press Stop Server in the sidebar. Closing VS Code stops Loom as well.

While Loom is running, the status bar item shows a dot (Loom ●) and the sidebar says "Loom is running." The Stop Server button only appears while it is running, so if you don't see it, Loom is off.

The Loom sidebar

Which folder does Loom open?

• If a file is open in the editor, Loom uses the workspace folder that file belongs to.
• Otherwise, if you have one folder open, it uses that folder.
• If you have several folders open, it asks which one.
• If no folder is open, it shows a folder picker.

Opening Loom for a different folder restarts it for that folder.

Map a GitHub repo without cloning

Paste a link such as https://github.com/owner/repo into the Map a GitHub repo box in the sidebar, or run Loom: Open GitHub Repo Link... from the Command Palette. Loom starts if it isn't running and shows the repo's tree, commit graph and files. Private repos need a GitHub token, which you paste into Loom's token box.

Commands

All commands are in the Command Palette (Ctrl/Cmd + Shift + P):

Settings

If something goes wrong

• Run Loom: Check Requirements to see exactly what is missing, and Loom: Show Server Log for details.
• "cannot reach pypi.org": the first run needs internet to install fastapi and uvicorn. If you are offline or behind a firewall, install them yourself with pip install fastapi uvicorn in a Python 3.9+ environment, then set loom.pythonPath to that interpreter.
• Remote windows (WSL, SSH, Dev Containers): Loom runs on the remote machine, so Python, Git and internet access must be available there.
• "Loom did not start within 20 seconds": open the server log. The most common cause is that fastapi or uvicorn is not installed in the Python Loom is using.

Features

Everyday Git, one screen

• Stage and unstage files with a click, or drag a file onto the staging area
• Write a message and commit, then push
• One-click Init, Add all, Fetch, Pull, Push, Stash, Pop
• Switch branches or create a new one from the sidebar
• Command bar for any git command, e.g. git log --oneline -10
• Command feed that records every command with its output and timing. Each card can be copied, re-run, pinned or deleted, and a Clear button wipes the unpinned ones. The feed scrolls on its own.

See your repo

• Diff: colour-coded diffs for working-tree and staged changes
• Graph: an animated commit graph with branch and tag labels
• Tree: your files as a collapsible tree, with sizes
• Reflog: browse recent history and click an entry to create a recovery branch there (nothing is overwritten)

Compare

• Compare your repo against another folder or a single file
• See which files are changed, only in your repo, only in the other folder, or identical
• Review differences line by line, then merge hunks, join, replace or copy into your repo
• Line-ending differences (CRLF vs LF) can be ignored
• Files your repo git-ignores (build junk, secrets) are skipped
• The other side is never modified, and every file that gets overwritten or deleted is backed up first to ~/.loom-backups

Read-only file viewer

• Click any file in the Tree tab to open it in a mini viewer
• Code and text get line numbers and basic syntax colouring (JS/TS, Python, shell, YAML, JSON, CSS, HTML and similar)
• Images (PNG, JPG, GIF, WebP, SVG, ICO, BMP, AVIF) are shown with their pixel size
• Binary and very large files get a short "no preview" message
• Works for both local folders and GitHub repos. Close with the button, a click outside, or Esc

GitHub without cloning

• Paste or drag a GitHub link (https://github.com/owner/repo, including /tree/branch links) to map the repo as a tree, a commit graph, and browse its files. Everything is read through the GitHub API.
• Private repos and higher rate limits work with a token

Push over HTTPS safely

• Set origin from the page and push with a personal access token
• The token is sent to git for that single push only. It is never written to .git/config or to disk

Polish

• Themes (Noir, Dracula, Tokyo Night, White, Black & White) plus a light/dark switch
• Command palette (Ctrl/Cmd + K), keyboard shortcuts, and an in-app help guide (?)
• Zen mode

Requirements

Installation

git clone https://github.com/Echo4-4/loom.git
cd loom
pip install fastapi uvicorn

loom.py and index.html must stay in the same folder.

Optional: run loom from anywhere

To start Loom from any folder by typing loom instead of python loom.py:

1. Create the launcher (run this from inside the cloned loom folder):

mkdir -p ~/.local/bin
cat << EOF > ~/.local/bin/loom
#!/usr/bin/env bash
python3 "$(pwd)/loom.py" "\$@"
EOF
chmod +x ~/.local/bin/loom

2. Make sure ~/.local/bin is on your PATH. If loom isn't found, add it:

• Zsh:

  echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
  

• Bash:

  echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
  

Now loom, loom /path/to/repo and loom --port 9000 all work from any directory.

Running Loom

python loom.py                    # start, then paste a repo path in the page
python loom.py /path/to/repo      # open a local repo straight away
python loom.py --port 9000        # use another port (default 8765)
python loom.py --no-browser       # don't auto-open the browser
python loom.py help               # print the usage guide

Loom prints a URL such as http://127.0.0.1:8765/?token=... and opens it in your browser. The token changes on every run, so always use the URL from the latest start.

Usage

Daily flow

1. Open a repo: paste a folder path in the top box and press Open.
2. Click + next to files to stage them (or Add all).
3. Type a commit message and press Commit.
4. Press Push.

Start a new repo

Open an empty folder and press Init. Loom runs git init -b main for you.

Map a GitHub repo

Paste a GitHub link into the top box, or drag the link onto the page. Then use the Tree tab to browse, click a file to read it, or open the Graph tab to see its recent commits.

The remote graph shows the history of one branch (the one in the link, or the default branch), up to 100 commits, with branch and tag labels. The local graph shows all branches.

Compare two folders

1. Open your repo in Loom.
2. Go to the Compare tab and enter the path of the other folder (or a single file).
3. Review the lists: changed, only in your repo, only in the other folder.
4. Open a changed file to review it hunk by hunk, then choose to merge, join, replace, or copy.
5. Apply. Loom writes only to your repo and saves a backup of anything it overwrites or deletes in ~/.loom-backups.

Push over HTTPS

1. On GitHub go to Settings → Developer settings → Personal access tokens and create a fine-grained token with Contents: Read and write for your repo.
2. In Loom's Remote box paste https://github.com/you/repo.git and press Set.
3. Paste the token in the token box and press Push.

To skip pasting the token each time, run this once in a terminal and push once from there. Loom's normal Push button then works:

git config --global credential.helper store

Keyboard shortcuts

The palette lists every available action.

Security

Loom is meant for use on your own machine.

• It binds to 127.0.0.1 only.
• Requests with any other Host header are rejected, which blocks DNS-rebinding attacks.
• Every API call needs a random per-run token, sent in the X-Loom-Token header.
• The local file viewer only reads files inside the repo folder you opened. Paths that escape it are refused.
• Compare only ever writes inside your repo folder, never to the other side, and never into .git.
• Tokens you paste are used for one request and are not stored or logged. They are redacted from command output.

Warning: the command bar runs git commands as you, with the same power as your terminal. Do not expose Loom to a network or put it behind a public proxy.

Limits

• GitHub allows 60 unauthenticated API requests per hour. Each repo mapping uses 2 requests, each remote graph about 3, and each remote file view 1. Add a token if you hit the limit.
• GitHub may truncate the file list of very large repos. Loom tells you when that happens.
• The file viewer previews text up to about 1.5 MB and images up to 8 MB.
• Compare handles up to 20,000 files, and merges text files up to about 600 KB. Larger or binary files can be copied or replaced but not merged line by line.
• The viewer is read-only by design. Edit files in your usual editor.
• Reflog is only available for local repos.

Troubleshooting

API (internal)

All routes live under /api/ and require the token header.

Contributing

Issues and pull requests are welcome. There is no build step: edit loom.py or index.html and restart.

Author

MADE BY ECHO404 Twitter: @JeffreyPeter_