# Getting Started ## Install Requires [Node.js](https://nodejs.org/) 18+. ```bash npm install -g weyaw ``` The correct pre-built binary for your platform (Linux x64, macOS ARM64, or Windows x64) is installed automatically via an optional dependency. No Rust toolchain needed. Verify: ```bash aw --help ``` If the `pi` command is available, successful interactive runs of bare `aw` and `aw install` also check whether Weyaw is configured as a Pi package. When it is missing, AW prints the manual installation command: ```bash pi install npm:weyaw ``` AW does not execute that command or write Pi settings. JSON, redirected, and other non-interactive invocations do not probe Pi or add guidance output. The root package also installs the documentation in its `docs/` directory. To locate a global npm installation, run `npm root -g` and open `weyaw/docs/getting-started.md` beneath the reported directory. ### From source Requires Rust 1.96+ ([rustup](https://rustup.rs)): ```bash git clone https://github.com/jsnzwu/weyaw.git cd weyaw cargo build --release # Binary at target/release/aw ``` Inside a Weyaw source checkout, use the checkout-local wrapper for current source behavior: ```bash node bin/aw-debug.js --help ``` This prefers `WEYAW_RS_BIN` when set and otherwise uses the `target/debug/aw` built in that same checkout. Each checkout therefore reports its own built behavior, and a Git worktree needs its own `cargo build --bin aw` before its wrapper describes the code in it. Setting `WEYAW_RS_BIN` to a binary from another checkout runs that binary instead, which is useful for commands that do not depend on the code under test but is not evidence about the current checkout. For interactive source-checkout testing, bare `node bin/aw-debug.js` and its `install` command suggest installing the resolved checkout as a local-path Pi package when Pi is available and Weyaw is absent. Use the packaged `aw` command in normal installed projects; do not use a possibly older global command as evidence for uncommitted checkout behavior. ## Quick start ### 1. Set up a project ```bash cd your-project aw init "This project does X, using Y stack" aw install --target agents ``` `aw init` creates a `.aw/` workspace with a project profile, blueprint, and roadmap seed. The description you provide helps agents understand the project scope. `aw install --target agents` installs generated skills under `.agents/skills/`; use `--target claude-code` for Claude Code or `--target codex` for Codex. ### 2. Start a task In an agent session, use the workflow skill: ```text $aw-task Add rate limiting to the API ``` Weyaw creates a task with a unique ID and a full artifact workspace under `.aw/tasks///`; the task directory moves between lifecycle groups as its state changes. The `$aw-task` router runs brainstorm when direction is unclear, then continues through analyze, plan, execute, verify, review, consolidate, and commit as required by the task. For lower-level CLI automation, `aw create --agent-runtime "Add rate limiting to the API"` creates the task record; the caller must obtain that exact value from its own Agent environment. The agent skill still owns roadmap association and the full lifecycle. ### 3. Check status ```bash aw status ``` See active tasks, their current step, and any open items. ### 4. Inspect artifacts in the terminal (optional) ```bash aw tui ``` Opens the terminal inspector for task artifacts, plans, execution notes, and verification results. Those observation tabs remain read-only. Settings is the only writable tab and provides typed controls for the complete project `config.toml`. It keeps edits in memory, validates before saving, preserves raw interpolation expressions and TOML comments, rejects stale external changes, and asks before leaving or quitting with unsaved work. After a successful save, apply or skip the proposed Agent Server and Index Server operations in one modal. The web dashboard is unmaintained and can no longer be started; see [Dashboard](dashboard.md). ### Agent Server ownership and recovery Agent Server belongs to the nearest initialized project through its canonical artifact root. Disposable lifecycle, queue, claim, permit, heartbeat, and reconciliation state lives under `.aw/.runtime/agent-server`; durable Agent evidence lives under `.aw/agents//sessions//`. A main checkout, linked task worktrees, and multiple Agent or Pi sessions share one pool when they resolve to the same canonical root. Another project owns an independent pool; Weyaw creates no machine-global project registry or queue. The default is eight fixed slots per project through `agent_server.project_concurrency`. Current `config.toml` is strict, versionless, and complete. Run `aw config repair` when the current template is incomplete or incorrectly typed; repair does not read or convert retired config formats. Normal installed projects run the npm/system `aw` executable directly. In a Weyaw development checkout, build and run that checkout's `target/debug/aw`, normally through `node bin/aw-debug.js`; Agent Server records its original path, digest, file instance, package version, canonical root, and runtime-config identity but never copies it into `.aw`. Provider launch uses the recorded normalized `PATH` directly. A profile that intentionally needs shell syntax must name it explicitly, for example `["bash", "-lc", "..."]`; recorded shell metadata does not implicitly start a login or interactive shell. Check and recover the pool from inside the initialized project: ```bash aw agent-server status aw agent-server restart ``` `status` and readiness are pure observations: they do not refresh heartbeats, reconcile capacity, or rewrite authority. Restart after package upgrades, source rebuilds, executable deletion or replacement, worker-runtime config changes, stale heartbeat evidence, or exhausted automatic reconciliation. Restart preserves the original timeout of an old generation's in-flight sessions while fencing it from new claims. Foreign-host ownership fails closed unless the user explicitly supplies `--confirm-host-takeover`. Never repair these conditions by editing runtime files, starting hidden workers, or copying a binary into the project. ## Agent integration Weyaw works through agent skills — prompts recognized by coding agents (Claude Code, Codex, etc.) in the project session. The skills are registered in `.agents/skills/` for current Codex repositories and in `.claude/skills/` for Claude Code. The `codex` target installs skills in `.codex/skills/`. Common skills to use in an agent session: | Skill | Purpose | |---|---| | `$aw-init` | Set up or reconcile project context | | `$aw` | Inject lightweight workflow context without starting work | | `$aw-task ` | Start task work from an intention | | `$aw-resume ` | Continue a recorded task | | `$aw-status` | Report workflow state | | `$aw-health` | Check or repair artifact consistency | | `$aw-help` | Suggest the next useful action | | `$aw-goal ` | Run an ordered roadmap batch serially | See [Skills](skills.md) for the full reference. ## Next steps - [Concepts](concepts.md) — Task lifecycle, artifacts, and workflow model - [CLI](cli.md) — Full command reference - [Artifacts](artifacts.md) — What lives in `.aw/` and why - [Dashboard](dashboard.md) — Why the web UI is sealed, and what replaces it