Wayfinder

Wayfinder is a Bun CLI that turns local Markdown planning maps into a live browser constellation. It shows ticket state, blockers, dependents, progress, and the current frontier while files change underneath it.

Requirements

• Bun 1.3 or newer

Run the CLI

Run without installing:

bunx @wyattjoh/wayfinder [path]

Or install the wayfinder binary globally:

bun add --global @wyattjoh/wayfinder
wayfinder [path]

Usage: wayfinder [path] [--port <port>] [--layout <layout>] [--no-open]

path may be a Markdown map, its directory, or a tree to search. It defaults to the current directory. Wayfinder opens the browser by default and binds only to 127.0.0.1.

Options:

• --port <port> requires a specific available port.
• --layout <layout> selects star (the default constellation) or elk (a top-to-bottom ELK layered dependency graph).
• --no-open prints the URL without opening a browser.

Use the Layout selector in the browser's Settings modal to change layouts. It reloads the current map from the server, preserves the map and ticket-directory selection, and writes the chosen layout into the local URL. A ?layout= URL value overrides the CLI default.

• --help prints usage.
• --version prints the package version.

Unknown flags, invalid ports or layouts, and extra operands fail with usage text. If the default port 7788 is occupied, Wayfinder selects a free port. An occupied explicit port fails.

Find maps and child files

Wayfinder automatically discovers files named map.md to a depth of six while skipping dependencies, build output, and nested repositories.

The browser's Settings modal includes a file tree bounded by the invocation path. Use it to:

• choose any Markdown file when automatic discovery finds no map;
• choose one child-file directory manually;
• resolve a map that has both tickets/ and issues/;
• render a map without child files.

Selections are encoded in the local URL and do not write configuration files. Symlinks and traversal cannot escape the invocation root.

Install the Agent Skill

The repository includes a portable wayfinder-map skill for Claude Code, Codex, and Pi. Install it globally with the external Agent Skills installer:

bunx skills@latest add wyattjoh/wayfinder \
  --skill wayfinder-map \
  --agent claude-code codex pi \
  --global --yes

To inspect discovery before installing:

bunx skills@latest add wyattjoh/wayfinder --list

The skill remains repository-owned under skills/wayfinder-map/. It is intentionally excluded from the npm tarball because the skills installer fetches it from the repository.

Map format

A conventional effort looks like this:

plan/
├── map.md
└── issues/
    ├── 01-establish-constraints.md
    └── 02-implement-it.md

tickets/ is also supported. Ticket files use <digits>-<slug>.md names and may express title, type, status, assignee, blockers, and identity through frontmatter or body metadata. See skills/wayfinder-map/references/map-format.md for the complete tolerant format.

Development

bun install
bun run hooks:install
bun run format
bun run format:check
bun run lint
bun run check
bun test
bun run precommit
bun pm pack --dry-run

Lefthook runs read-only formatting and lint checks against staged files. Type checking and tests remain in CI.

Releases

Run the local release gate before publishing:

bun run build
npm login
npm publish

npm publish runs the same local release gate through prepublishOnly. A local publish is public because publishConfig.access is set to public; never commit npm credentials. Local publishes do not include provenance attestations.

Release Please uses Conventional Commits to maintain versions, CHANGELOG.md, tags, and GitHub releases. Its release workflow runs the same checks and publishes @wyattjoh/wayfinder with OIDC provenance. Before enabling that publication path, configure npm trusted publishing for the wyattjoh/wayfinder GitHub repository and the .github/workflows/release-please.yml workflow.

License

MIT