wai /waɪ/

Why: AI-assisted development loses the why — after 30+ days untouched, git log, comments, and READMEs tell you what exists but not what shaped it, and context recovery costs 15+ minutes of agent time per project. wai tracks research, reasoning, and decisions alongside the work so wai prime restores full context in under 2 minutes. Status: beta · core commands shipped, calver releases · Motivation & design · charly-vibes Tool Ecosystem wai will enable AI-assisted software developers to recover the full context of a project not touched in 30+ days by reducing context-recovery time from >15 minutes to <2 minutes within 6 months (by February 2027), as measured by time from wai prime to correctly identifying the project's phase, purpose, and most recent decision, compared to reading git log, source comments, and README without wai.

wai — pronounced like "why" — is a command-line workflow manager for AI-driven development. It can also be read as "way", and that's intentional: the tool's focus is capturing why it was built that way.

Most specs define what to build. Wai extends the workflow to also inform — preserving the research, reasoning, and decisions that shaped the design. When you revisit a project months later, the spec tells you what exists; wai tells you why.

Organizes artifacts using the PARA method (Projects, Areas, Resources, Archives) with project phase tracking, agent config sync, handoff generation, and plugin integration.

Design Principles

• Desire Path Alignment — Pave the cowpaths, make common workflows shortest. Example: wai status suggests the next command based on your current phase.
• Self-Healing Errors — Errors suggest fixes, not just report problems. Example: wai doctor --fix auto-repairs common workspace issues.
• Progressive Disclosure — Simple by default, powerful when needed. Example: -v/-vv/-vvv reveals progressively more detail.
• Context-Aware — Offer next steps based on current state. Example: auto-detects git, beads, openspec — no configuration required.

Installation

Binary (curl)

V=$(basename "$(curl -fsSLI -o /dev/null -w '%{url_effective}' \
  https://github.com/charly-vibes/wai/releases/latest)" | sed 's/^v//')
TGT="$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/^x86_64$/amd64/; s/^aarch64$/arm64/')"
curl -fsSL "https://github.com/charly-vibes/wai/releases/download/v${V}/wai_${V}_${TGT}.tar.gz" | tar xz
chmod +x wai && sudo mv wai /usr/local/bin/

Cargo (crates.io)

cargo install wai-cli

Installs the wai binary.

Homebrew (macOS & Linux)

brew tap charly-vibes/charly
brew install wai

Scoop (Windows)

scoop bucket add charly https://github.com/charly-vibes/scoop-charly.git
scoop install wai

From Binary

Download the latest pre-compiled binary from the GitHub Releases page, unpack, and move wai to a directory in your PATH.

From Source

Requires Rust (stable toolchain):

git clone https://github.com/charly-vibes/wai
cd wai
cargo build --release

Quick Start

# Initialize wai in current directory
wai init

# Or run the interactive tutorial (recommended for first-time users)
wai tutorial

# Create a project
wai new project my-feature

# Add research findings
wai add research "Evaluated approach X vs Y - chose X for performance"
wai add research --file notes.md --tags "api,research"

# Check status and get next-step suggestions
wai status

# Move through phases: research → design → plan → implement → review → archive
wai phase next                                # advance to next phase
wai add design "Using microservices pattern"
wai phase next
wai add plan "Phase 1: API, Phase 2: UI"
wai phase next                                # → implement

# Wrap up session: create handoff + show next steps
wai close

Documentation

• Quick Start - Get started in 5 minutes
• Commands Reference - Complete command documentation
• Troubleshooting - Common issues and solutions
• FAQ - Frequently asked questions
• CHANGELOG - Version history and upgrade guide

Concepts

• PARA Method - Project organization
• Project Phases - Workflow stages
• Sessions - The prime→close session lifecycle
• Reasoning - AI-powered oracle and synthesis
• Plugin System - Extensibility and integration
• Pipelines - Multi-step workflows with validation gates
• Agent Config Sync - Configuration management
• Toolchain Synergy - How wai, beads, and openspec work together
• Glossary - Domain-specific terms

Guides

• Adopt Wai in an Existing Repo - Step-by-step adoption guide
• Architecture - Codebase structure for contributors

Development

cargo build                  # Build
cargo run -- status          # Run
cargo test                   # Test
cargo clippy                 # Lint
cargo run -- --help -v       # View advanced help

Pi Extension Package

This repository also exposes Pi workflow guardrails as a local Pi package:

pi install /path/to/wai

For project-local installation, run the command from the repo you want to guard and add -l:

pi install -l /path/to/wai

The package loads extensions/wai-autonomy, which detects wai workspaces and adds autonomous workflow/context guardrails for Pi sessions. It:

• injects wai autonomous-work policy into each Pi turn
• warns as context approaches the wai handoff threshold
• customizes compaction summaries for wai session continuity
• blocks unverified git commit attempts after edits unless you record wai add research "VERIFICATION NOT RUN: <reason>"
• blocks git push unless the current user prompt explicitly authorizes push/release/deploy

You can smoke-test the package from this repo with:

npm run test:pi-extension
pi -e ./extensions/wai-autonomy/index.ts

Contributing

See Development for guidelines on contributing to wai.

License

MIT

---

A note on authorship

All the code in this repository was generated by a large language model. This is not a confession, nor an apology. It's a fact, like the one that says water boils at a hundred degrees at sea level: neutral, technical, and with consequences one discovers later.

What the human did is what tends to happen before and after things come into existence: thinking. Reviewing requirements, arguing about edge cases, understanding what needs to be built and why, deciding how the system should behave when reality —which is capricious and does not read documentation— confronts it with situations nobody anticipated. The hours of planning, of design, of reading specifications until exhaustion dissolves the boundary between understanding and hallucination.

The LLM writes. The human knows what it should say.

There is a distinction, even if looking at the commit history makes it hard to find. The distinction is that a machine can produce correct code without understanding anything, the same way a calculator can solve an integral without knowing what time is. Understanding what that integral is for, whether it actually solves the problem, whether the problem was the right problem to begin with — that remains human territory. For now.

Leer en español

Documentation provenance

Rendered docs are generated artifacts; the repository sources are authoritative — edit the repo sources, not the rendered output.