Weyaw

Weyaw is a local, artifact-backed workflow for agent work.

It exists for projects where agent work should be resumable, inspectable, and grounded in project files rather than scattered across chat history. Weyaw keeps the work loop small: define the intention, record the plan, execute with evidence, verify the result, and preserve useful knowledge for future agents.

Motivation

Agent sessions are good at local reasoning, but they are easy to interrupt and hard to audit after the fact. Weyaw treats agent work as a project artifact:

• Tasks have durable state and lifecycle.
• Plans, execution notes, verification, and summaries are written down.
• Project guidance stays close to the code.
• Work can be resumed without reconstructing context from memory.

The goal is not to replace human judgment or turn every change into process. The goal is to make non-trivial agent work easier to continue, review, and trust.

Scope

Weyaw supports today:

• Local project onboarding and task routing.
• Persistent task artifacts for plan, execution, verification, review, and consolidation.
• Project-scoped agent skills for common workflow actions.
• Roadmap and blueprint notes for project direction and design decisions.
• Health checks for workflow artifact consistency.
• Local management for incremental todo work through the project workflow workspace, normally .aw, plus constraints, process records, and task state.

Weyaw has growing support for:

• A terminal inspector (aw tui) whose Settings tab is the only writable TUI surface. All observation tabs, JSON output, and scripted fallback remain read-only. The web dashboard is unmaintained and its start entries are sealed.
• Official trigger-driven Agent coordination with task or runtime-operation owners, bounded read-only fan-out, frozen-worktree project writers in Brainstorm/Analyze/Execute, artifact-root control chains, and interruption-safe groups.
• Local lexical indexing over project and workflow evidence, with current search, published source-map, and bounded explore-plan surfaces. Semantic retrieval and graph queries remain unavailable.

Weyaw is planned to support:

• Project-management views over retained project artifacts beyond the current task loop.

Weyaw does not try to be:

• A replacement for Git history or normal source-control practice.

Common Skills

Use these prompts from an agent session in a Weyaw project:

$aw
$aw-init <project context>
$aw-help
$aw-blueprint <design or standards update>
$aw-commit <task-id>
$aw-config <configuration intention>
$aw-index <index intention>
$aw-roadmap <roadmap update>
$aw-uiux <interface context>
$aw-task <task intention>
$aw-resume <task-id>
$aw-status
$aw-health
$aw-dream <reconciliation context>
$aw-goal <roadmap item ids>

Typical use:

• $aw injects lightweight project workflow context without starting a task.
• $aw-init establishes or reconciles project context.
• $aw-help suggests the next useful Weyaw action.
• $aw-blueprint updates durable design language or standards.
• $aw-commit stages and commits one active task after explicit confirmation.
• $aw-config inspects, explains, or changes typed project configuration through Weyaw-owned commands.
• $aw-index inspects index capability, freshness, and discovery surfaces.
• $aw-roadmap updates project direction without starting implementation.
• $aw-uiux provides interface-design guidance only when UI/UX judgment is explicitly requested.
• $aw-task starts scoped task work from an intention.
• $aw-resume continues recorded work.
• $aw-status reports current workflow state.
• $aw-health checks workflow consistency and requires explicit approval for unsafe or destructive repairs.
• $aw-dream diagnoses post-onboarding blueprint-versus-code drift through the normal task workflow without applying fixes itself.
• $aw-goal executes an explicitly ordered batch of roadmap items serially.

Brainstorm, Analyze, Plan, Verify, and Review use Host-owned todo dependency DAGs. Stable rows carry explicit depends_on[]; multiple dependency-ready rows may be active, and tracked steps cannot complete until every retained node is done. Execute does not duplicate this state: it merges Plan dependencies with explicit execution-only rows. Each logical Wave is the complete stable-order dependency-ready layer and is never split by node count, Action fan_out, worker availability, capacity, or queue state. When at least two assignments are Agent-safe, the Host publishes all of them in one task-owned group; exactly one stays Host-owned. Configured Action, group, project, and worker capacity determine which published sessions are running or queued. While Agents run, the Host may continue dependency-, write-scope-, and resource-disjoint Host work.

Normal workflow artifacts no longer require whole JSON or Markdown payload staging. aw artifact analysis|plan|execution|action-log|verify|consolidate|commit exposes semantic mutations, while aw artifact section and aw artifact text edit registered documents locally. Exactly-one opaque payloads use --input or --input-file <path|->; aw write remains only for complete-document creation or strict repair. aw contract list|show|validate exposes the compiled artifact registry read-only, and aw step enter composes replay-safe start, render, Dynamic Guidance, and Clap-derived command specs into one typed result.

Configured source repositories use one of two fixed VCS kinds: git or none. Repository reads, writes, indexing, and source-writable Agent execution remain available for vcs = "none"; Weyaw does not probe for or launch Git on those paths. Commit gates skip non-Git repositories, while Git worktrees and Agent change review or adjustment return a structured repository_vcs_unsupported refusal when Git capability is required.

Installation

Requires Node.js >=18.0.0.

npm install -g weyaw

The correct pre-built binary for your platform is installed automatically. No Rust toolchain needed. Verify with aw --help.

Initialize a project and install the project-local agent skills:

cd your-project
aw init "Short project summary"
aw install --target agents

Pi users can install Weyaw once as a user-global Pi package:

pi install npm:weyaw

When pi is available but that package is not configured, successful interactive runs of bare aw and aw install print this command as an actionable hint. Weyaw never runs the Pi installation or writes Pi settings; JSON, redirected, and other non-interactive command output is unchanged.

The package adds a read-only contextual HUD backed by the matching Weyaw CLI. With only project context, Weyaw publishes the project name through its weyaw footer status key. After a successful task-owning AW CLI JSON result confirms a runnable task, it publishes the full canonical task id followed by the visible Agent count, for example TSK-20260812-2341-responsive-hud · 2 AGT. Weyaw does not own or replace Pi's footer. A footer owner such as Pi Choco Chips may combine the weyaw and mcp statuses as TSK-… · 2 AGT · MCP 1/1, reserving the marker suffix and truncating only the task id by terminal display cells. The widget above the editor shows normalized current-step todos and the widget below the editor shows only task-scoped Agent information. Todo styling uses the active Pi theme: doing is accent and bold, done is dim and struck through, and pending text uses the normal text color.

Both widgets use one shared responsive breakpoint: compact presentation below 100 columns and detail presentation at 100 columns or above. When logical Waves exist, the task heading always renders the complete ordered chain: detail rows use progress · Step Wave(current/total) [P1] → [P2] → [P3,P4]; compact rows use IDs such as progress · Step Wcurrent/total [1]→[2]→[3,4] only when compaction stays one-to-one across the complete current workload and otherwise retain full IDs such as [S1,X1,X2]. Neither tier drops Waves, wraps the chain in parentheses, or replaces ids with +N; long headers wrap across terminal-safe rows. Detail todo rows use P1 · Title; compact rows use 1. Title under the same unambiguous compaction rule and otherwise retain the full ID, such as S1. Title. Grouped Agents render under one GroupID heading instead of repeating the Group id or assignment position on child rows. Compact Group headings show id, active/total progress, and aggregate used tokens; detail headings add the active label while keeping the same aggregate used-token total because summed Group context limits are not meaningful. Each Agent retains its own full-width row because Group members may use different Action presets and execution identities. Group and Agent fields use two-space list columns instead of repeated middle-dot separators. Compact Agent rows use a stable status-marker, mode, harness/profile, authored title, used-token, and Action-order-preset sequence. Detail rows add id, full status, token budget, and append turn count only above one plus try N only above the first attempt. Historical rows without identity retain the label-first fallback. HUD compact mode still includes only queued/running Agents, while expanded mode includes all bounded Agent rows under their Groups; this inclusion choice is independent of responsive presentation. Todo, Group, and Agent rows use Pi's terminal-cell-safe truncation only when their rendered text exceeds the current width. Percentages are not shown.

/aw-hud, /aw-hud compact, and /aw-hud expanded are immediate local Pi UI commands: they never submit a model message or enter the follow-up queue. Compact mode shows at most three completed todos and only queued/running Agents; expanded mode shows all completed todos and all Agents. Pi never renders Agent abstracts; expanded mode changes inclusion only. Resizing changes only layout, not which rows the selected mode includes. The mode is runtime-local and resets to compact after /reload.

The extension reconstructs only ephemeral context from paired AW Bash tool calls and structured results in the current Pi branch. Skill-message names, arbitrary task-id text, and reference-only commands such as aw read, aw check, aw status, and aw observe cannot switch the HUD task. It does not auto-select repository tasks, persist session bindings, write transcript entries, read or watch .aw directly, or create project-local .pi/extensions files. All workflow data comes from the package-matched aw observe activity projection in the nearest initialized project.

See Getting Started for full details and first steps.

Agent Server project pools

Agent Server is project-bound by the canonical artifact root. Its disposable control plane lives under .aw/.runtime/agent-server, while durable Agent evidence lives under .aw/agents/<group-id>/sessions/<session-id>/. Main checkouts, linked task worktrees, and concurrent Agent or Pi sessions resolving to one canonical root share the same project pool. Separate projects own independent pools; there is no host-global registry, supervisor, queue, or concurrency budget.

Each project pool defaults to eight fixed worker slots through agent_server.project_concurrency. Every parallel-safe official Action also defaults to fan_out=8, including complex reasoning; the temporary broad-control Action remains fixed at 1. Current config.toml is strict, versionless, and complete. Use aw config repair to restore the current template when required fields are missing or incorrectly typed; repair does not interpret retired fields or layouts.

Installed projects execute the npm/system aw binary directly. Source development executes that checkout's target/debug/aw directly, normally through node bin/aw-debug.js. Generation evidence records the original executable path, digest, file instance, package version, canonical artifact root, and worker-runtime config identity; no project-local executable copy is created. Provider commands execute directly from the submitter's recorded normalized PATH; shell metadata is diagnostic and does not trigger hidden login or interactive shell initialization.

Use aw agent-server status for a read-only view of .aw/.runtime/agent-server, lifecycle state, generation, fixed-slot heartbeats, queue, and capacity. Run aw agent-server restart after an npm upgrade, source rebuild, executable deletion or replacement, worker-runtime config change, stale heartbeat, or exhausted reconciliation. Restart fences the old generation from new claims, starts one current generation, and lets old in-flight sessions finish under their original timeout before retiring drained workers. Foreign-host ownership fails closed; takeover requires --confirm-host-takeover. Do not edit runtime files or invoke hidden worker commands.

Every Agent launch creates one group, including singleton groups with group_size = 1. group.json alone owns task or project attribution. Each assignment authors one stable semantic agent_id, one required title of at most 48 terminal display columns, and one objective; durable identity is group → session → turn.

Durable group, session, turn, prompt, response, message, and segmented event evidence remains under .aw/agents. Task and project views are read-time projections from group ownership. Deleting .aw/.runtime after stopping services discards only rebuildable process state; it does not remove durable Agent history.

For AGT-X, runtime status, observed_changes, and review_decision are independent facts. Completion does not prove a change occurred or was accepted, observed changes do not prove semantic success, and acceptance requires an explicit parent review decision.

Documentation

• Getting Started
• Concepts
• CLI
• Skills
• Artifacts
• Dashboard
• Release

Design Principles

• Keep workflow state local to the project.
• Prefer small, explicit task steps over hidden agent memory.
• Record evidence for changes that matter.
• Keep human decisions visible.
• Treat generated and runtime artifacts as separate from source design.

Development

Version notation

All version constraints in this section are inclusive. For example, >=18.0.0 means that development requires version 18.0.0 or newer.

Tooling prerequisites

Dependency	Minimum version	Used for	Notes
Rust toolchain (including cargo)	>=1.96.0	Building, testing, and packaging the Rust CLI	rust-toolchain.toml currently selects 1.96.0.
rustfmt and clippy	Bundled with Rust >=1.96.0	Formatting and linting	Both are requested by rust-toolchain.toml.
Node.js	>=18.0.0	The npm wrapper, package checks, and Dashboard tooling	This matches the root npm package's engines.node constraint.
npm	The version bundled with a supported Node.js installation	Installing, building, testing, and packaging the Dashboard	No separate npm minimum is declared by the project.
Git	>=2.5.0 for repositories configured with vcs = "git"	Cloning, commit gates, task worktrees, and Agent change review or adjustment	Git is not required or launched for repositories configured with vcs = "none".
Bubblewrap (bwrap)	>=0.11.0 on Linux/WSL when Agent execution is enabled	Provider-neutral AGT-R/AGT-X filesystem sandbox	Readiness smoke-checks the sandbox; every Agent launch fails closed when it is unavailable.
Platform C linker/build tools	No project-specific minimum	Linking Rust binaries	Use the standard compiler/linker toolchain for the host platform.

Install the pinned Rust toolchain and the Dashboard dependency graph with:

rustup toolchain install 1.96.0 --profile minimal --component rustfmt --component clippy
npm --prefix dashboard ci

cargo downloads the Rust dependency graph automatically. The two lockfiles are the complete, reproducible source of truth for transitive dependencies:

• Cargo.lock pins Rust crates for the CLI and crates/index-core.
• dashboard/package-lock.json pins all Dashboard npm packages.

Use commands such as cargo build --locked or cargo test --locked, plus npm ci, rather than manually installing individual transitive dependencies.

Direct code dependencies

The following table records the direct dependency lower bounds. The manifests retain their actual compatibility ranges (such as Cargo's default caret ranges and npm's ^ ranges); the lockfiles above select exact versions.

Component	Direct dependencies
Rust CLI	anyhow >=1.0, axum >=0.8, workspace index-core, clap >=4.5, serde >=1.0, serde_json >=1.0, sha2 >=0.10, tokio >=1.0, libc >=0.2, fs4 >=0.13, tiktoken >=3.5.1, unicode-segmentation >=1.13, ratatui >=0.30.2, crossterm >=0.29.0, rmcp >=3.1.2, notify >=8.2.0; Windows only: windows-sys >=0.61; test-only: tower >=0.5.
crates/index-core	anyhow >=1.0, ignore >=0.4, regex >=1.12, serde >=1.0, serde_json >=1.0, tantivy >=0.26.
Dashboard runtime	@lucide/vue >=1.21.0, pinia >=3.0.2, vue >=3.5.14, vue-router >=4.5.1.
Dashboard development	@types/node >=22.15.21, @vitejs/plugin-vue >=5.2.4, @vue/test-utils >=2.4.6, jsdom >=26.1.0, typescript >=5.8.3, vite >=6.3.5, vitest >=3.2.1, vue-tsc >=2.2.10.

The Dashboard dependencies are required when modifying or building the frontend. No aw command builds it any more: the dashboard is unmaintained and its start entries are sealed, so a frontend build is a manual npm --prefix dashboard run build.

Release-only dependencies

These are not needed for ordinary Rust or Dashboard development. Install only the tools needed for the target or publish operation you intend to perform:

Scenario	Additional dependency	Minimum version
Run scripts/release.sh	Bash (the script uses associative arrays), tar, and sha256sum	Bash >=4.0; no project-specific minimum for the host utilities
Package a Windows archive from Linux/WSL	x86_64-w64-mingw32-gcc, MinGW headers, and zip	No project-specific minimum
Build macOS ARM64 from Linux	cargo-zigbuild and Zig	No project-specific minimum
Upload a GitHub Release	GitHub CLI (gh)	No project-specific minimum
Publish npm packages	npm credentials with publish access	Node.js >=18.0.0

See Release for the target triples and platform-specific installation commands.

Rust checks

Run the focused local checks before handing off Rust changes:

cargo fmt --check
cargo test --locked --all-targets

Npm Package

The public root npm package exposes the Rust command as aw, installs the matching platform package, and includes the user and agent documentation under docs/.

For current-source workflow evidence in this checkout, use node bin/aw-debug.js; a globally installed aw may represent an older release.

Run the focused package checks with:

npm run pi:extension-test
npm run pi:install-guidance-test
npm run package:metadata-test
npm run package:smoke