aiwg

AIWG

Reusable project context and specialist workflows for the AI tools you already use.

Plan software, coordinate specialist reviews, prepare campaigns, investigate incidents, organize research, curate media, and maintain operational knowledge. AIWG combines agents, skills, rules, templates, and workflow utilities around these tasks, adapting them to your existing AI provider.

Project artifacts carry decisions from one session to the next. Domain frameworks supply the procedures; addons extend them with writing profiles, task loops, memory, testing tools, decision support, and other capabilities. The sections below show what you can do, how the pieces work together, and how to use them.

The simplest setup is to paste this into a supported AI provider:

Install or repair AIWG for this project by following
https://aiwg.io/setup.aiwg.yaml
Explain the plan before changing anything, preserve my existing work, and ask
me only for choices you cannot safely determine.

The installer detects old, broken, duplicate, and development-mode installs, then guides you through repair or update. Once the CLI is healthy, guided setup records an interview plan, lets you review it, and applies the selected frameworks and integrations through the existing deployment owners. The apply report distinguishes core readiness from optional integration failures.

For long-running agents that need an isolated executor, optionally install AIWG Cockpit with a self-hosted Agentic Sandbox executor you control and audit:

Install or repair AIWG Cockpit and Agentic Sandbox by following
https://aiwg.io/agentic-sandbox/setup.aiwg.yaml
Install the required prerequisites, explain the plan before changing anything,
preserve my existing work, and ask me about the isolation, network, storage,
and access choices you cannot safely determine.

This option audits the host, installs the approved Docker or KVM/libvirt runtime and sandbox prerequisites, connects Cockpit to the real executor, applies your resource and access choices, and verifies the control and audit path end to end.

If you prefer to install manually:

npm i -g aiwg
cd /path/to/your/project
aiwg setup --scope project --providers <provider>
aiwg setup --review
aiwg setup --apply

Replace <provider> with your AI tool's name, such as claude, codex, copilot, cursor, omp, or pi.

The interview saves a plan without changing provider configuration. Review is read-only; apply asks for confirmation and reports the verified outcome. Optional Jev decision offload and direct workers require explicit opt-in. Repeating apply resumes unfinished actions and leaves completed actions alone. See the guided setup reference for headless flags, credential references, scope choices, and recovery. For a direct complete-system deployment, aiwg use all --provider <provider> remains available.

For the complete beginner path and provider-name table, see Install, Connect, and Verify.

For a lightweight install that resolves signed, versioned resources from the release host, install the executable:

npm i -g @aiwg/cli

Find the architecture-evolution workflow, read its requirements, and help me apply it to this project.

See Web-Backed AIWG Resources for source selection, exact-version overrides, cache verification, offline use, and the current framework-graph constraints.

For a larger project, ask your AI assistant to establish project policy as well. The agent-led setup conversation should establish remotes, issue storage, delivery behavior, signing policy, and provider choices; the assistant discovers the project-setup workflow and handles its tools.

macOS users: if npm fails with EACCES under /usr/local/lib/node_modules, use the macOS Install Guide. Agents and stewards setting up AIWG end-to-end should use the Agentic Install Runbook.

Get Started · Features · Agents · Decision Support · Documentation · Community · Badges

---

Installation Troubleshooting

Optional native features

The base global install intentionally excludes native packages whose lifecycle scripts require explicit trust. Core deployment, discovery, and provider tooling work without them. Enable only the capability you need:

Enable the native features needed for interactive terminals, semantic search, or graph-backed artifacts in this workspace. Explain which dependencies are required, install only the selected features, and verify they load.

The feature installer writes a private manifest and lockfile under the AIWG user data directory and approves scripts only for that feature. Do not set a broad user-level npm allow-scripts policy. If an older install left native package files present but unbuilt, aiwg doctor reports the broken capability and the same scoped rebuild command.

macOS npm EACCES

If npm install -g aiwg fails with EACCES while writing to /usr/local/lib/node_modules/aiwg, npm is using a system-owned global install directory. The Node.js setup guide covers the supported runtime and version-manager choices. After setting up Node, run:

npm install -g aiwg
aiwg doctor

If Node is already installed and you need a quick recovery, one manual alternative is a user-owned npm prefix. Choose this only after checking your existing Node version-manager configuration:

npm config set prefix ~/.local
echo 'PATH="$HOME/.local/bin:$PATH"' >> ~/.profile
echo 'source ~/.profile' >> ~/.zprofile
source ~/.profile
npm install -g aiwg

See macOS Install Guide for the full walkthrough. Avoid sudo npm install -g aiwg as the default fix; it can create root-owned npm files that break later upgrades.

aiwg command not found

If aiwg is not found after npm i -g aiwg, the npm global bin directory is not on your PATH. Confirm and fix:

Diagnose why this shell cannot find AIWG. Check the npm installation and PATH, and apply the appropriate local fix.

You can also invoke AIWG without adjusting PATH by using npx aiwg doctor. For a broader health check — version, deployed providers, missing dependencies, kernel-skill probes — run aiwg doctor. See the troubleshooting guide for the full recovery paths.

---

What AIWG Is

AIWG gives your AI assistant reusable project context and specialist workflows. Its deployment layer connects those instructions to your provider: aiwg use copies markdown and YAML source files into the paths each provider reads, so one source of truth works across 18 named provider integrations. A nineteenth generic adapter emits portable files for unrecognized or custom harnesses and is not counted as a named integration.

Around that core, AIWG ships agent-facing utilities for work that benefits from additional structure: persistent artifact memory (.aiwg/), background orchestration, autonomous loops, artifact indexing, cost telemetry, health diagnostics, and more. These are tools the agent calls when the task calls for them — you stay in chat. Most are opt-in. The deployment layer works standalone as plain text files the platform reads natively.

Project scope, user scope, and multi-project workspaces

aiwg use supports project deployments, additive user mirrors, and a user-global bootstrap:

• Project scope — default. Run aiwg use all --provider <provider> from a project root and the artifacts land in that provider's project paths. This keeps project-specific instructions associated with the intended repository. Some providers also use user-level surfaces; check the reported deployment scope. This is the simplest start for a single project.
• User scope (additive mirror) — aiwg use all --provider <provider> --scope user keeps the project deployment and mirrors it to ~/.claude/agents/, ~/.claude/skills/, etc.
• Global bootstrap — aiwg use all --provider claude --global installs framework and kernel assets in native user-level paths while leaving only lightweight context and provider bootstrap files in the current project. Ask the assistant to connect additional projects without deploying their own skill copies.

Several repositories under one assistant or orchestrating session are supported. See Working Across Multiple Projects for setup, access, and sharing boundaries.

Shared user-level instructions can be useful for personal conventions, while project-local instructions keep a team's requirements and decisions with its repository. Review both scopes when a provider uses them together. The installer and provider inventory describe where files will go, so you can distinguish instructions that follow you across projects from instructions intended for this workspace.

See the Agentic Install Runbook for the zero-to-running setup path, and the CLI reference (under aiwg use → "Scope models") for the per-provider details and the global-install rough-edge inventory.

Simple Building Blocks

AIWG's workflow source is readable and editable. The main building blocks are:

• Agents — specialist role instructions, such as Security Auditor or Test Architect, with defined responsibilities and supported tool access.
• Skills — reusable procedures an agent can find from a goal and follow during a task.
• Commands — explicit ways to request a workflow through the provider or CLI.
• Rules — constraints for the assistant to follow, with tool-based checks where configured.
• Behaviors — lifecycle actions and hooks on providers that support them.
• Templates — structures for requirements, briefs, review reports, runbooks, and other outputs.

Many assets use Markdown with YAML metadata; hooks and utilities may also include executable scripts or structured