claude-code-browser

A tiny local dashboard for people who keep many repos open and use Claude Code.

claude-code-browser scans a folder of local projects, shows every immediate child directory as a card, and gives you a one-click way to open Claude Code in that repo. It also includes a workspace-wide Markdown reader for top-level README.md, CLAUDE.md, AGENTS.md, ROADMAP.md, CHANGELOG.md, and other *.md files.

No package manager. No build step. No database. One Python file, stdlib only.

Why

If you only work in one repo, cd project && claude is enough. If you switch between dozens of repos, the small friction adds up: remembering paths, opening a terminal, finding the right README, then repeating the same steps again.

This project keeps that workflow in one local browser tab:

• scan a folder containing your repos
• browse projects as cards
• open Claude Code in the selected repo
• reveal a repo in your OS file manager
• read workspace Markdown without leaving the browser

Quick Start

Download the single file and run it:

curl -O https://raw.githubusercontent.com/caspianchan31/claude-code-browser/main/server.py
python3 server.py --root ~/code

Then open http://localhost:8765.

Or clone the repo:

git clone https://github.com/caspianchan31/claude-code-browser.git
cd claude-code-browser
python3 server.py --root ~/code

Usage

python3 server.py [--root DIR] [--port N]

Flag	Default	Notes
--root	current directory	Directory to scan. One card per immediate subdirectory. Symlinks are followed.
--port	8765	HTTP server port. The server binds to 127.0.0.1 only.

Environment variables work too:

CCB_ROOT=~/code CCB_PORT=8799 python3 server.py

Screens

Project Grid

The home page shows one card per project. Each card includes the resolved path, detected top-level Markdown files, and quick actions.

Workspace Docs

The docs page has a project sidebar, file tabs, syntax highlighting, and sanitized Markdown rendering.

Markdown Discovery

Only top-level Markdown files are listed. The ordering is optimized for agent-oriented repos:

1. README.md
2. CLAUDE.md
3. AGENTS.md / AGENT.md
4. ROADMAP.md
5. CHANGELOG.md
6. all other *.md files alphabetically

Recursive discovery is intentionally out of scope for now. The goal is a fast workspace overview, not a full documentation search engine.

Platform Support

Action	macOS	Linux	Windows
Browse project grid	yes	yes	yes
Read Markdown docs	yes	yes	yes
Reveal in file manager	open -R	xdg-open	explorer /select,
Launch Claude Code in terminal	Terminal.app through osascript	tries x-terminal-emulator, gnome-terminal, konsole, then xterm	cmd /k

The browser and Markdown reader are cross-platform. Terminal launching is best-effort because terminal apps differ by machine.

HTTP Routes

Route	Method	Purpose
/	GET	Project grid
/docs	GET	Markdown reader
/api/scan	GET	JSON list of scanned projects
/api/md?project=NAME&file=README.md	GET	Read a safe top-level Markdown file
/api/asset?project=NAME&path=screenshots/grid.png	GET	Read a safe relative asset referenced by Markdown images
/api/open	POST	Reveal a project in the OS file manager
/api/claude	POST	Launch Claude Code in a terminal at the project path

Example scan response:

[
  {
    "name": "my-app",
    "real_path": "/Users/me/code/my-app",
    "mtime": 1760000000.0,
    "md": ["README.md", "CLAUDE.md"]
  }
]

Security Model

This is designed as a local-only developer tool:

• The HTTP server binds to 127.0.0.1, not 0.0.0.0.
• /api/md only serves *.md files from resolved project directories.
• /api/asset only serves non-hidden relative files inside a resolved project directory, primarily so Markdown images render in the docs page.
• Markdown filenames containing /, \, or a leading . are rejected.
• Resolved Markdown paths must remain inside the selected project root.
• The claude executable is resolved with shutil.which("claude"), with a fallback to ~/.local/bin/claude.
• Markdown HTML is sanitized in the browser with DOMPurify.

Do not run this behind a public reverse proxy. It is meant for your own machine.

Troubleshooting

claude does not launch

Make sure the claude command is available in the environment used to start the server:

which claude

If your shell can find claude but the launched terminal cannot, start server.py from the same shell profile you normally use for Claude Code.

The grid is empty

--root should point at the folder containing your repos, not at a single repo:

python3 server.py --root ~/code

The app scans only immediate child directories.

The docs page has no files

Only top-level *.md files are shown. Nested docs such as docs/guide.md are intentionally ignored.

CDN assets are blocked

The docs page loads marked.js, DOMPurify, and highlight.js from CDN. If your network blocks those requests, the project grid still works, but Markdown rendering will not.

Demo Video

The animated README demo is built with Remotion:

cd video
npm install
npm run render

The render writes screenshots/demo.mp4. The README GIF is derived from that rendered video.

Non-goals

This tool deliberately does not include:

• token, cost, or Claude usage monitoring
• an embedded terminal in the browser
• git status, branch info, or commit history
• recursive Markdown discovery
• Markdown editing
• remote access or team hosting

Those features may be better served by dedicated tools. This project stays focused on local repo launching and quick docs reading.

License

MIT - see LICENSE.