loomx 0.1.0

A CLI tool that adds reference and backlink metadata to markdown documentation files

loomx

A CLI tool that adds reference and backlink metadata to markdown documentation files, helping AI coding agents better understand project context.

What is loomx?

loomx scans your markdown files, extracts links between documents, and adds metadata blocks that clearly show:

• Which files each document references
• Which files link back to each document

This creates a web of connections that makes it easier for both humans and AI to navigate and understand your documentation structure.

Installation

pip install loomx

Or install from source:

git clone https://github.com/pawsong/loomx-py.git
cd loomx-py
pip install -e .

Requirements

• Python 3.9+

Quick Start

1. Navigate to your project directory:

cd /path/to/your/project

2. Update all markdown files with reference metadata:

loomx update

3. Check for broken links:

loomx check

Features

• Smart Link Detection: Uses AST-based parsing for accurate link extraction
• Bidirectional Linking: Automatically calculates and maintains backlinks
• Repository-Aware: All paths are relative to your repository root
• Git-Friendly: Respects .gitignore patterns
• Non-Invasive: Metadata blocks are invisible in rendered markdown
• Fast: Efficiently processes large documentation sets

How it works

loomx adds hidden metadata blocks to your markdown files:

<!-- @loomx
  references:
  - /docs/api-reference.md
  - /docs/getting-started.md
  backlinks:
  - /README.md
-->

# Your Document Title

Your content continues as normal...

These metadata blocks are:

• Invisible on GitHub and other markdown renderers
• Automatically maintained - just run loomx update
• AI-friendly - structured data that coding assistants can parse

Commands

loomx update

Scans all markdown files and updates their reference metadata.

Options:

• --dry-run - Preview changes without modifying files
• --verbose - Show detailed progress
• --path PATH - Specify root directory (default: current directory)

loomx check

Verifies all links between markdown files are valid.

Options:

• --path PATH - Specify root directory (default: current directory)

Configuration

loomx automatically ignores common directories:

• .git
• node_modules
• __pycache__
• .venv
• dist
• build

You can add custom exclusions in pyproject.toml:

[tool.loomx]
exclude = ["tests/fixtures/**", "docs/drafts/**"]

Documentation

• Getting Started Guide
• Configuration Options
• Examples
• Architecture Overview

Development

Setup

# Quick setup (recommended)
./setup.sh

# Or manual setup:
uv venv
source .venv/bin/activate
uv sync --all-groups
uv pip install -e .

Testing

# Run tests
poe test

# Run tests with coverage
poe test-cov

Code Quality

# Run linter
poe lint

# Format code
poe format

# Type checking
poe typecheck

# Run all checks (lint, typecheck, test)
poe check

Other Tasks

# Build package
poe build

# Clean build artifacts
poe clean

Examples

See docs/examples.md for detailed usage examples, including:

• Pre-commit hooks
• GitHub Actions integration
• Monorepo support
• Real-world use cases

Why loomx?

When working with AI coding assistants, providing context about how files relate to each other helps them:

• Navigate documentation more effectively
• Understand the full scope of changes
• Make better suggestions based on related content

loomx makes these relationships explicit and machine-readable.

License

MIT