Metadata-Version: 2.4
Name: metabrowser
Version: 0.1.1
Summary: Browse local files from your web browser, with extensible plugin-based rendering of Markdown, code, JSON, YAML, logs, and other files.
Project-URL: Homepage, https://github.com/jlevy/metabrowser
Project-URL: Repository, https://github.com/jlevy/metabrowser
Project-URL: Documentation, https://github.com/jlevy/metabrowser#readme
Project-URL: Issues, https://github.com/jlevy/metabrowser/issues
Author-email: Joshua Levy <joshua@cal.berkeley.edu>
Maintainer-email: Joshua Levy <joshua@cal.berkeley.edu>
License-Expression: MIT
License-File: LICENSE
Keywords: browser,developer-tools,jsonl,logs,markdown
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: User Interfaces
Classifier: Typing :: Typed
Requires-Python: <4.0,>=3.12
Requires-Dist: cachetools>=7.1.4
Requires-Dist: frontmatter-format>=0.3.0
Requires-Dist: funlog>=0.2.1
Requires-Dist: json5>=0.15.0
Requires-Dist: jsonschema>=4.26.0
Requires-Dist: kpress==0.2.2
Requires-Dist: pathspec>=1.1.1
Requires-Dist: prettyfmt>=0.4.1
Requires-Dist: psutil>=7.2.2
Requires-Dist: pydantic>=2.13.4
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: ruamel-yaml>=0.19.1
Requires-Dist: starlette>=1.3.1
Requires-Dist: strif>=3.1.0
Requires-Dist: typer>=0.26.8
Requires-Dist: uvicorn>=0.49.0
Requires-Dist: watchfiles>=1.2.0
Description-Content-Type: text/markdown

# Metabrowser

Metabrowser is an extensible, plugin-based file browser that runs as a small, local
server and opens in any web browser.
Use it where you might use an IDE or OS file manager but get beautifully rendered
Markdown, code, YAML, JSON and JSONL, images, logs, and many other file types.

I use Metabrowser because I’m tired of the ugly and often clunky experience of browsing
files, especially Markdown documents, logs, code, and other files while coding with
agents.

It’s also a “meta browser” in the sense that it’s a file-browsing framework: it’s
intended to be agent hackable.
Its plugin architecture means you can ask an agent to add new web-based renderings or
custom views for arbitrary file types or folders.

## Why Use a New Browser-Based File Manager?

I’ve long been frustrated when I try to browse files in macOS Finder, VS Code, or other
tools:

- Why is Markdown rendering often absent or clunky?
- In a folder with 10,000 files, why can’t I easily see which files are largest?
  Or which have been modified recently?
- Why is it so hard to tail log files in a GUI?
- How can I cleanly browse a large YAML, JSON, or JSONL file?
- Do I really have to register customized default apps for every file extension in macOS
  or Windows?
- If I want a graphical rendering for a new language or file format, do I really need to
  ship an entire VS Code extension or a new Electron app?

Metabrowser combines a simple Starlette Python server with a navigator-style web
interface.

Unlike a typical local web view, it’s live and efficient about watching for updates from
lots of files. The server watches the file tree in the background and streams updates to
the frontend.

It especially works well when browsing Markdown docs like agent-written specs.
It supports clean typography and full-featured Markdown rendering via
[KPress](https://github.com/jlevy/kpress).

It aims to be the most readable way to view any common file and is my preferred way to
read Markdown docs.

## Features

- **Complete Markdown support.** Good typography, tables, footnotes, syntax
  highlighting, math, links, images, and print-friendly output (supported via
  [kpress](https://github.com/jlevy/kpress)).

- **Broad file support.** Render common text, syntax highlighted source code, logs,
  images, and tree-parsed JSON, JSONL, and YAML. Clean support for YAML frontmatter.

- **Scalable browsing of large file trees.** Unlike a Finder or IDE/VSCode tree, the
  file and recent views keep file ages, file and folder counts, and aggregate disk usage
  visible while you browse.
  And the streaming architecture easily scales to 100,000 files or more in a folder.

- **A fast, framework-free frontend.** Metabrowser ships direct CSS and JavaScript with
  no browser framework.
  Rendering is quick even for large files and customization is straightforward.

- **Custom rendering for arbitrary file types.** A compact manifest-based plugin
  architecture adds file matching and browser views, with optional Python data hooks and
  JSONL adapters, without changing Metabrowser core.

It doesn’t currently support editing (or commenting on Markdown docs), but it could in
the future.

## Quick Start

Metabrowser requires Python 3.12 or newer and uses [uv](https://docs.astral.sh/uv/).
Node.js and npm are not required to install or run it.
Run the latest published release without installing a global tool:

```shell
uvx metabrowser@latest .
```

This will open the current directory (or any other directory you specify) in your web
browser.

[![Metabrowser showing a file tree and rendered Markdown](images/metabrowser-overview.jpg)](images/metabrowser-overview.jpg)

To make Metabrowser available everywhere as `metab`:

```shell
uv tool install metabrowser
metab .
```

`metab` is the standard installed command.
The `metabrowser` compatibility command matches the package name, which is why the short
`uvx metabrowser@latest ...` form works.

The CLI documents every command and option:

```shell
metab --help
metab serve --help
metab plugins --help
```

See [installation](docs/installation.md) for uv setup and upgrade instructions.

To run an unreleased source checkout, install its exact locks and invoke the local
environment without resolving them again:

```shell
make install
uv --config-file uv.toml run --frozen metab ./path/to/artifacts
```

> [!WARNING]
> Metabrowser is not a secure, public-facing web server.
> It is a local tool for trusted users browsing files locally or via trusted channels
> like ssh. Treat it with the same level of trust you would a shell or OS file manager.
> Use the default `127.0.0.1` binding, load only trusted plugins, and never expose
> Metabrowser directly to the internet.

## What Metabrowser Opens

Built-in plugins provide views for:

- Markdown rendered by KPress, alongside the source.
- JSON, YAML, and other structured documents.
- Coding-agent JSONL logs and generic JSONL streams.
- Text, source code, images, and binary-file metadata.
- Generic chart summaries for supported agent logs.

Gzip and zlib variants of supported artifacts open transparently with bounded
decompression. Format-specific binary stores belong in separately installed plugins,
keeping native readers out of the core package.

Large trees are indexed in the background.
The first preview does not wait for a full recursive crawl, and filesystem events update
the tree and recent-file views while the server runs.

## Common Commands

The short form starts the local server, opens the browser, and serves the selected root:

```shell
# Browse a directory or open one file directly.
metab ./path/to/artifacts
metab ./path/to/artifacts/logs/session.jsonl

# Select a file relative to the served root.
metab ./path/to/artifacts --path logs/session.jsonl

# Start without opening a browser window.
metab serve ./path/to/artifacts --no-open

# Browse a directory on a remote host through an SSH tunnel.
metab remote example-host --path /srv/artifacts

# Print a machine-readable inventory without starting the web UI.
metab walk ./path/to/artifacts --format json
```

The server binds to `127.0.0.1:8411` by default and walks a bounded port range if that
port is occupied.
Do not change `--host` to expose a served root to an untrusted network;
see the [security policy](SECURITY.md).

## Plugins

Metabrowser is designed to be extended.
A plugin can add:

- File-kind matching rules.
- Browser preview tabs implemented in JavaScript.
- Optional Python data hooks for installed plugin packages.
- JSONL event adapters for additional log formats.

Inspect the complete registry and validate every discovered plugin from the CLI:

```shell
metab plugins list
metab plugins list --json
metab plugins show markdown
metab plugins doctor
```

Metabrowser loads plugins only from trusted sources:

1. built-ins shipped in the Metabrowser wheel
2. installed Python packages registered in the `metabrowser.plugins` entry-point group
3. directories explicitly named with `--plugins-dir` or `METABROWSER_PLUGINS_DIRS`

An installed Python plugin must be present in the same uv tool or uvx environment as
Metabrowser. Operator-directory plugins are useful for local JavaScript-only extensions.

For example, load an operator-reviewed plugin directory with:

```shell
metab serve ./path/to/artifacts --plugins-dir ./trusted-plugins
```

The served data tree is never an implicit plugin source.
See the [plugin authoring guide](docs/plugins.md) for the manifest schema, browser SDK,
packaging, lifecycle rules, and security boundary.

## Use With Coding Agents

Metabrowser includes a portable [Agent Skill](skills/metabrowser/SKILL.md).
Install it for supported coding agents with:

```shell
npx skills add jlevy/metabrowser --skill metabrowser
```

The skill requires no persistent Metabrowser installation.
It calls the pinned `uvx metabrowser@0.1.1 ...` runner and uses `--help` on the CLI and
its subcommands as the source of truth.
A globally installed `metab` remains available as the faster local command.

## Develop

Development requires uv 0.11.26 or newer, Node 24.18 or newer on the Node 24 LTS line,
and npm 11.10 or newer on npm 11. The Node and npm requirements apply only to repository
tooling.

The repository uses uv, Ruff, BasedPyright, pytest, Biome, TypeScript check-JS, and
Flowmark:

```shell
make install
make format
make verify
```

`make verify` checks formatting, lint, types, tests, locked dependency audits, source
and wheel builds, artifact inspection, and isolated installed-wheel smoke tests.
See [development](docs/development.md) and [architecture](docs/architecture.md).

## Documentation

- [Installation](docs/installation.md)
- [Plugin authoring](docs/plugins.md)
- [Architecture](docs/architecture.md)
- [Design system](docs/design-system.md)
- [Development](docs/development.md)
- [End-to-end testing](docs/e2e-testing.md)
- [Real-time debugging](docs/realtime-debugging.md)
- [Publishing](docs/publishing.md)
- [Project design and plans](docs/project/README.md)
- [Security policy](SECURITY.md)
- [Roadmap](TODO.md)

## License

Metabrowser is available under the [MIT License](LICENSE).

<!-- This document follows common-doc-guidelines.md.
See github.com/jlevy/practical-prose and review guidelines before editing.
-->
