Metadata-Version: 2.4
Name: repoglyph
Version: 0.3.0
Summary: Generate an isometric city-skyline fingerprint banner (SVG) from a local git repository.
Project-URL: Homepage, https://repoglyph.net
Project-URL: Repository, https://github.com/remsky/repoglyph-py
Project-URL: Issues, https://github.com/remsky/repoglyph-py/issues
Author: remsky
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
License-File: src/repoglyph/render/fonts/OFL.txt
Keywords: banner,git,github,isometric,readme,svg,visualization
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.12
Provides-Extra: png
Requires-Dist: resvg-py>=0.3.3; extra == 'png'
Description-Content-Type: text/markdown

# <img src="https://raw.githubusercontent.com/remsky/repoglyph-py/main/assets/logo.svg" width="28" height="28" alt=""> repoglyph

[![OKF](https://img.shields.io/badge/bundle-OKF-0d1c17?labelColor=4c566a&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI%2BPGcgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjNWVmMmQwIiBzdHJva2Utd2lkdGg9IjIuMiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIj48cGF0aCBkPSJNNiAyaDhsNCA0djE2SDZ6Ii8%2BPHBhdGggZD0iTTE0IDJ2NGg0Ii8%2BPHBhdGggZD0iTTkgOWgyLjVNMTMuNSA5SDE2Ii8%2BPHBhdGggZD0iTTkgMTMuNWg3TTkgMTcuNWg0LjUiLz48L2c%2BPC9zdmc%2BCg%3D%3D)](https://github.com/remsky/repoglyph-py/blob/glyph/okf/index.md)

![tests](https://img.shields.io/badge/tests-104-5ef2d0)
![coverage](https://img.shields.io/badge/coverage-88%25-5ef2d0)

![repoglyph banner](https://repoglyph.net/remsky/repoglyph-py.svg?palette=light&commits=10&detail=40&style=skyline&streets=1.5&text=1.05&skip_dirs=.glyph,plugin)

+Open Knowledge Format bundle generator showing repo churn, file change coupling, and structural fingerprint. 

+Isometric repo-city banners from local git clone. 

(Offline port of [repoglyph.net](https://repoglyph.net); hosted (free)
customization explorer and web-cached banners there.)

## Install

```bash
uv tool install "repoglyph"   # standalone CLI on PATH, or
pip install "repoglyph"       # CLI in the active environment; add the [png] extra for PNG output
```

Each installs the `repoglyph` command. Python 3.12+.

## Usage

<details>
<summary><b>Agent Usage</b></summary>

A usage skill for repoglyph itself can be installed via npx skills, plugin marketplace, or found in this repo ([plugin/skills/repoglyph](plugin/skills/repoglyph))

```bash
npx skills add remsky/repoglyph-py
```
OR
```bash
claude plugin marketplace add remsky/repoglyph-py
claude plugin install repoglyph@repoglyph
```

</details>

<details>
<summary><b>CLI Usage</b></summary>

### Basic usage
```bash
repoglyph                 # current repo w/ defaults
repoglyph ../project
repoglyph . --style skyline --palette neon
```

Writes `<repo>/.glyph/<owner>_<repo>_<style>.svg`, plus a PNG with the `png` extra.

### All flags
| Flag | Default | Meaning |
| --- | --- | --- |
| `--commits N` | `50` | commits used for lit windows |
| `--style NAME` | `oblique` | `oblique`, `skyline`, or `highrise` |
| `--palette NAME\|FILE` | `light` | built-in theme or palette JSON |
| `--size WxH` | `1280x480` | canvas size |
| `--full` | off | fit canvas to the whole city |
| `--out FILE` | auto | output SVG path |
| `--out-dir DIR` | `<repo>/.glyph` | folder for all outputs |
| `--svg` / `--no-svg` | on for a banner, off with `--okf`/`--skill` | write the SVG |
| `--png` / `--no-png` | on for a banner, off with `--okf`/`--skill` | write the PNG (needs the `png` extra) |
| `--skip-commons` | off | drop lockfiles from the city |
| `--staged` | off | draw HEAD + staged changes |
| `--okf [DIR]` | off | write an OKF context bundle |
| `--skill [DIR]` | off | skill-compliant OKF bundle (default `.claude/skills/repo-map`) |
| `--inventory` | off | add per-district docs with full file listings to the bundle |
| `--cache` | off | save repo data for `--from-cache` |

`repoglyph --help` for the rest.

### Styles
- `oblique`: flat cabinet-oblique map (default)
- `skyline`: one building per file
- `highrise`: one tower per district, floors are subdirs

</details>

## OKF / Skill Generation

`--okf` writes markdown context files from the same repo data: an index, a
repository summary, hotspots (churn ranking plus change-coupling hubs mined
from commit history), and a per-district stats table (files, bytes, depth,
churn, largest file). That's a flat handful of documents by default;
`--inventory` adds one document per district with its full file listing. A
reader working in a checkout can list files itself, so the default bundle
carries only what a listing can't show. In bundle mode no banner is drawn; add
`--svg` or `--png` if you also want the image.

See it live: the [`glyph` branch](https://github.com/remsky/repoglyph-py/tree/glyph/okf)
holds the bundle for this repo, regenerated by CI on every push to `main`.

```bash
repoglyph . --okf
```


Or shortcut with `--skill` to generate with skill-compliant filenames and frontmatter, so an agent can quickly get its bearings on any repo. 

```bash
repoglyph . --skill # -> .claude/skills/repo-map 
repoglyph . --skill <custom output path>
```

<details>
<summary><b>Limits</b></summary>

- Shows folder structure, not runtime architecture.
- Lit windows and coupling use the sampled commit window, not full history.
- File bytes proxy size.

</details>

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

Apache-2.0. Bundled Monaspace Xenon fonts are SIL OFL.
