README
¶
osc8wrap
A CLI tool that wraps any command and converts file paths and URLs in output to clickable OSC 8 hyperlinks.
Installation
From source
go install github.com/mash/osc8wrap@latest
Binary releases
Download from GitHub Releases.
Usage
osc8wrap [options] <command> [args...]
<other command> | osc8wrap [options]
Options
--scheme=NAME- URL scheme for file links (default:file)--domains=LIST- Comma-separated domains to linkify withouthttps://(default:github.com)--no-resolve-basename- Disable basename resolution (default: enabled)--exclude-dir=DIR,...- Directories to exclude from basename search (default:vendor,node_modules,.git,__pycache__,.cache)
Options can also be set via environment variables. CLI flags take precedence.
| Flag | Environment Variable |
|---|---|
--scheme |
OSC8WRAP_SCHEME |
--domains |
OSC8WRAP_DOMAINS |
--no-resolve-basename |
OSC8WRAP_NO_RESOLVE_BASENAME=1 |
--exclude-dir |
OSC8WRAP_EXCLUDE_DIRS |
Examples
# Make file paths in build errors clickable
osc8wrap go build ./...
# Make grep results clickable
osc8wrap grep -rn "TODO" .
# Make Claude Code output clickable
osc8wrap claude
# Use vscode:// scheme to open files in VS Code at specific line
osc8wrap --scheme=vscode go build ./...
# Set default scheme via environment variable
export OSC8WRAP_SCHEME=cursor
osc8wrap go test ./...
# Pipe mode (auto-detected when stdin is not a terminal)
grep -rn "TODO" . | osc8wrap
cat build.log | osc8wrap --scheme=vscode
What it does
- Detects file paths (absolute and relative) in command output
- Detects
https://URLs - Converts them to OSC 8 hyperlinks that work in supported terminals
- Runs commands through a PTY, so colors and interactive programs work
- Supports pipe mode for processing output from other commands
Supported patterns
| Pattern | Example |
|---|---|
| Absolute path | /path/to/file.go |
| With line number | /path/to/file.go:42 |
| With line and column | /path/to/file.go:42:10 |
| Relative path | ./src/main.go:10 |
| Extensionless path | ./README, /path/to/LICENSE |
| *file names | Makefile, Dockerfile |
| HTTPS URL | https://example.com/docs |
File paths are only linked if the file exists. Extensionless files are supported when they have a path prefix (/, ./, ../) or end with file (e.g., Makefile, Dockerfile, Gemfile).
Basename resolution
When a path like main.go:10 doesn't exist relative to the current directory, osc8wrap searches for the file in the project and creates a link to the matching file.
How it works:
- On startup, osc8wrap builds a file index in the background
- In git repositories: uses
git ls-filesfor fast indexing - Otherwise: walks the filesystem, skipping excluded directories
- In git repositories: uses
- When a path doesn't exist at the literal location, the index is consulted
- Files are matched by basename, then filtered by path suffix if the input contains
/ - When multiple files match, the most recently modified file is selected
Examples:
| Input | Actual file | Result |
|---|---|---|
main.go:10 |
src/main.go |
Links to src/main.go |
to/file.go:5 |
path/to/file.go |
Links via suffix match |
file.go:1 |
a/file.go, b/file.go |
Links to most recently modified |
Notes:
- Resolution only occurs when the literal path doesn't exist
- If the index isn't ready yet, unresolved paths are left as plain text
- Disable with
--no-resolve-basenamefor faster startup on large codebases
Editor schemes
By default, file links use the file:// scheme. To open files directly in your editor at the specific line, use an editor-specific scheme:
| Scheme | URL format |
|---|---|
| file | file://hostname/path |
| vscode | vscode://file/path:line:col |
| cursor | cursor://file/path:line:col |
| zed | zed://file/path:line:col |
Any scheme name is accepted and will be formatted as {scheme}://file{path}:{line}:{col}.
Terminal support
See OSC 8 adoption in terminal emulators for a list of supported terminals.
License
MIT
Documentation
¶
There is no documentation for this package.
Source Files