# <img src="https://raw.githubusercontent.com/remsky/repoglyph-py/main/assets/logo.svg" width="28" height="28" alt=""> repoglyph
[](https://github.com/remsky/repoglyph-py/blob/glyph/okf/index.md)
+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
Standalone CLI on PATH
```bash
uv tool install "repoglyph"
```
**OR** CLI in the active environment
```bash
pip install "repoglyph"
```
Each installs the `repoglyph` command. Python 3.12+. Use `repoglyph[png]` to include the extra for PNG output
## 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.