🛠️ Unix Executable Emulators for Windows

16 standalone UNIX utilities written in V — bridging the gap between Windows and UNIX shell environments for AI agents and developer tools.

🇧🇷 Leia em português

• Why This Exists
• Quick Start
• Tool Reference
  • File Listing & Inspection
  • File Content
  • Search & Filter
  • File Operations
  • Utilities
• Argument Policy
• Testing
• Architecture
• Building
• RTK on Windows — Agent Prompt Template

Windows lacks native equivalents of standard UNIX commands (ls, grep, find, etc.). While PowerShell provides aliases, they are incompatible with external programs that expect real executables on PATH.

The core motivation is token economy for AI agents. When an LLM calls PowerShell cmdlets like Select-String or Get-ChildItem, the output is verbose, object-formatted, and often hundreds of lines. This wastes thousands of tokens per call — tokens you pay for.

These executables produce dense, UNIX-style plain-text output consumable in a single glance. Paired with rtk (AI proxy), they let agents execute CLI operations with short pipelines like:

rtk grep -n "pattern" path | rtk head -n 80
rtk findd ./src -name "*.ts" | xargs grep "TODO" | rtk head -n 200

To get the most out of this setup, use the agent system prompt provided in AGENTS_SUGGESTION_FOR_RTK.md. It enforces mandatory rtk wrappers, forbids verbose PowerShell cmdlets, and auto-excludes binary/dependency directories — all designed to minimize token waste.

The binaries:

1. Work as real executables — callable from any shell, script, or external tool (e.g., rtk, AI agents like Codex/Gemini)
2. Return POSIX exit codes — 0 for success, 1 for no match/error, 2 for usage errors
3. Support common GNU/UNIX flags — progressively implementing the most-used flags
4. Handle Windows paths — backslash/forward-slash normalization, PATHEXT support
5. Auto-exclude noisy directories — node_modules, .git, vendor, etc. are skipped by default in recursive scans
6. Auto-detect literal patterns — grep bypasses the regex engine when the pattern has no meta-characters, cutting RAM from GBs to MBs

• V compiler installed and on PATH

cd executables
.\build.bat
# or
powershell -File .\build.ps1

cd executables\exe_ls
.\build.bat

Binaries are compiled to the project root (two levels above each exe_<tool> directory). Place them in a directory on your PATH.

ls -la .
grep -rn "TODO" ./src --include="*.v"
find . -iname "*.txt" -type f
cat -n file.txt | head -n 20
sort data.csv | uniq -c

ls [OPTIONS] [FILE...]

pwd [OPTIONS]

Outputs forward-slash paths for UNIX compatibility.

which [OPTIONS] COMMAND...

Searches PATH directories and respects PATHEXT on Windows.

cat [OPTIONS] [FILE...]

Reads from stdin when no file is specified or file is -.

head [OPTIONS] [FILE...]

tail [OPTIONS] [FILE...]

Performance: Uses seek-from-end approach — handles multi-GB files without loading them into memory.

grep [OPTIONS] PATTERN [FILE...]

Performance: Auto-detects literal patterns to bypass the regex engine, circular buffer for context lines (O(1) vs O(n) for before-context), auto-excludes node_modules/.git/vendor/etc in recursive scans, iterative BFS-based directory traversal.

find [PATH...] [OPTIONS]

Supports combining multiple filters with -o (OR logic). Glob patterns use * and ?.

Performance: Regex patterns are pre-compiled once at startup, not per-file.

sort [OPTIONS] [FILE...]

uniq [OPTIONS] [INPUT [OUTPUT]]

cp [OPTIONS] SOURCE... DEST

mv [OPTIONS] SOURCE... DEST

rm [OPTIONS] FILE...

mkdir [OPTIONS] DIRECTORY...

touch [OPTIONS] FILE...

xargs [OPTIONS] [COMMAND [ARGS...]]

Examples:

find . -name "*.txt" | xargs grep "TODO"
find . -print0 | xargs -0 wc -l
echo file1 file2 | xargs -I {} cp {} /backup/
ls *.log | xargs -n 2 echo "Batch:"

For any flag that is not yet implemented, the tools return a standardized error message:

TODO (UNIX WINDOWS): THIS ARGUMENT HAS NOT YET BEEN IMPLEMENTED.
USE AN ALTERNATIVE METHOD, AS THE "ls" COMMAND DOES NOT YET HAVE THIS ARGUMENT "-la".

This message is designed for AI agents to understand and use alternative approaches.

Each tool has integration tests in its tests/ directory:

# Run tests for a specific tool
cd executables\exe_grep
v test tests/

# Run all tests
Get-ChildItem -Directory exe_* | ForEach-Object {
    Write-Host "Testing $($_.Name)..."
    Push-Location $_.FullName
    v test tests/
    Pop-Location
}

Tests use os.execute() to run the compiled binary and verify exit codes and output. New features and optimizations require new tests — see AGENTS.md for the full testing policy.

executables/
├── AGENTS.MD          # Agent-facing documentation & testing policy
├── README.md          # This file
├── README.pt-br.md    # Brazilian Portuguese version
├── build.ps1          # Build all tools
├── build.bat          # Wrapper for build.ps1
├── exe_ls/            # Each tool in its own directory
│   ├── main.v         # Entry point & argument parsing
│   ├── lister.v       # Core logic (directory listing)
│   ├── filedata.v     # Data structures
│   ├── options.v      # Options struct
│   ├── utils.v        # Utility functions
│   ├── build.bat      # Individual build script
│   └── tests/
│       └── ls_test.v  # Integration tests
├── exe_grep/
│   ├── main.v
│   ├── matcher.v      # Regex/fixed-string matching engine
│   ├── processor.v    # File processing & output
│   ├── filters.v      # --exclude/--include handling
│   ├── options.v
│   └── tests/
│       ├── grep_test.v
│       ├── context_test.v
│       ├── exclude_test.v
│       ├── literal_test.v
│       └── autoexclude_test.v
└── ...                # 14 more tools following the same pattern

• Directory naming: exe_<command> (e.g., exe_ls, exe_grep)
• Build output: Each build.bat compiles to ../../<command>.exe (the bin/ root)
• Build flags: All builds use -prod for optimized release binaries
• Module: All files use module main
• Options: Parsed with V's flag module, stored in an Options struct

cd executables\exe_ls
v -prod -o "..\..\ls.exe" .

cd executables
.\build.ps1

cd executables\exe_ls
v -o "..\..\ls.exe" .

To get the most out of these tools with rtk, use the agent system prompt provided in AGENTS_SUGGESTION_FOR_RTK.md. It enforces:

• MANDATORY use of rtk wrappers for CLI operations on Windows
• FORBIDDEN use of native PowerShell cmdlets (Select-String, Get-Content, Get-ChildItem) for file/text operations
• Short UNIX-style pipelines with rtk grep ... | rtk head ...
• Targeted paths/extensions over broad recursive scans from .
• findd | xargs grep to narrow by directory and file type before running grep
• Auto-exclusion of binary files, node_modules, .git, build/, dist/, etc.
• Auto-exclusion of binary extensions: *.exe, *.dll, *.sqlite, *.png, *.pdf, *.zip, etc.

See the file for the full ready-to-copy prompt and examples.

Why this matters: PowerShell cmdlets produce verbose, object-formatted output that wastes thousands of AI tokens per call. These UNIX-style tools output dense plain text — a single rtk grep ... | rtk head -n 80 can replace a 200-line PowerShell output with 3-5 lines the LLM can consume instantly.

Internal tooling — part of the rtk ecosystem.