awman

What this skill does

# awman

awman is a Rust CLI and TUI for running AI coding agents (Claude Code, Codex, OpenCode, and others) in isolated Docker or Apple Containers sandboxes. It coordinates parallel agent sessions, executes multi-step workflows, and exposes a REST API for headless programmatic control.

**awman is not a tmux wrapper.** The name invites that assumption. awman ships its own tab-based TUI with its own keybindings. Tmux is not a dependency.

awman was previously named **amux**. See "Migrating from amux" below.

Source: https://github.com/prettysmartdev/awman (accessed 2026-06-02)
License: Apache-2.0 | Latest at research time: v0.9.1 (2026-05-28)

## When to Use This Skill

Activate when:
- Setting up a project for parallel agent sessions (`awman init`, `awman ready`)
- Running a chat session or one-off prompt via the awman CLI
- Authoring or executing multi-step workflows (`awman new workflow`, `awman exec workflow`)
- Driving the REST API server (`awman api`) from an automation script
- Migrating an existing amux setup to awman
- Troubleshooting container isolation, worktrees, or config resolution
- Configuring agent selection, container runtimes, or environment passthrough

## Prerequisites

- A container runtime: **Docker** (Linux, macOS, Windows) or **Apple Containers** (macOS 26+). Set via global `runtime` config key. The two runtimes are mutually exclusive.
- Runtime running and healthy before any `awman` session starts.

## Install

Mise is the recommended install path. It manages the version, pins reproducibly, and uses the GitHub releases backend — no extra dependencies.

A ready-to-copy pin lives at `templates/0.9.1/mise.toml` in this skill — copy it into the target repo's `mise.toml` (or merge under `[tools]`) and run `mise install`.

**Global pin (one-time, any project):**
```sh
mise use -g github:prettysmartdev/[email protected]
```

**Per-project pin (recommended for repos that run awman):**
```sh
cp templates/0.9.1/mise.toml <your-repo>/mise.toml   # then: cd <your-repo> && mise install
```

The template's contents:
```toml
[tools]
"github:prettysmartdev/awman" = "0.9.1"
```

**Verify:**
```sh
mise which awman && awman --version
```

Fall back to the upstream installer (`curl -s https://prettysmart.dev/install/awman.sh | sh`) only when mise is unavailable (locked-down CI image, no GitHub release network access). State the reason explicitly when doing so. Building from source requires Rust 1.94+ and `make` (`git clone https://github.com/prettysmartdev/awman.git && cd awman && make install`). Do not use Homebrew, asdf, or mason — none are documented by upstream.

## Migrating from amux

The rename is automatic for existing users:

- Config migrates automatically on first run. Change any `AMUX_*` environment variables to `AWMAN_*` and you are done.
- The binary is now `awman`; the installer offers to clean up old `amux` binaries.
- Config keys under `headless.*` are now under `api.*` (e.g. `headless.workDirs` → `api.workDirs`).
- The server command `amux headless start` is now `awman api start`.
- Per-repo config moved from `aspec/.amux.json` to `GITROOT/.awman/config.json` (see Config below).
- Markdown workflow files (`.md`) are **no longer supported** — use TOML or YAML.

## First-Run Diagnostic

awman is pre-1.0 and ships frequently. Run these before trusting that docs match the installed binary:

```sh
awman --version
awman config show
```

`awman config show` prints the merged effective config (global + per-repo). Use it to verify `runtime`, `default_agent`, and overlay state rather than reading JSON files directly.

## Command Tree

| Command | Purpose |
|---------|---------|
| `awman init [--aspec] [--agent <name>]` | Scaffold project: writes `.awman/config.json` and per-agent Dockerfiles |
| `awman ready [--refresh]` | Verify environment; `--refresh` re-audits and rebuilds the agent Dockerfile |
| `awman chat [--agent <name>] [--auto] [--yolo]` | Interactive agent session in a TUI tab |
| `awman exec prompt "<text>"` | One-off prompt without a persistent session |
| `awman exec workflow <path> [--work-item <nnnn>] [--yolo] [--worktree]` | Run a multi-step workflow file |
| `awman new spec\|workflow\|skill [--interview]` | Scaffold a work item, workflow, or custom skill |
| `awman specs amend <nnnn>` | Update an existing work item |
| `awman status [--watch]` | Session/workflow dashboard |
| `awman config show\|get\|set [--global]` | Inspect/modify merged config |
| `awman api start\|status\|logs\|kill` | Manage the REST API server (default port 9876) |
| `awman remote run\|session` | Drive a remote awman api server |
| `awman` (no args) | Open the TUI |

See `templates/0.9.1/commands.md` for the full v0.9.1 command surface with flags and examples.

## Agents

Supported agents: `claude`, `codex`, `opencode`, `maki`, `gemini`, `antigravity`, `copilot`, `crush`, `cline`.

Each agent has a Dockerfile in `.awman/Dockerfile.<agent>` (seeded from upstream templates). Customize the Dockerfile to add tools or environment configuration for that agent.

**Selection precedence** (highest wins):
1. Per-step `agent:` field in the workflow file
2. `--agent <name>` flag on the CLI invocation
3. `agent` key in per-repo `.awman/config.json`
4. `default_agent` key in `~/.awman/config.json` (global default; factory default: `"claude"`)

## Worktrees

Opt-in via `--worktree` on `awman chat` / `awman exec`. All steps in a single workflow run share one worktree.

Worktrees are **never auto-deleted**. At session end, awman prompts: merge / discard / keep. On abort, the worktree is preserved for manual inspection. Monitor disk use when running repeated `--yolo --worktree` workflow runs.

Containers run `--rm` and auto-remove at session end. Only the Git repository is bind-mounted; `/workspace` inside the container is ephemeral beyond what lands in the Git tree.

## Config Files

awman reads one `config.json` per scope:

| File | Scope | Created by | Commit? |
|------|-------|-----------|---------|
| `~/.awman/config.json` | Global | Manually or `awman config set --global` | No |
| `GITROOT/.awman/config.json` | Per-repo | `awman init` | Yes |

Per-repo takes precedence on overlapping scalar keys. `overlays.skills` and `overlays.directories` merge **additively** across scopes. The repo `.awman/` directory also holds per-agent Dockerfiles seeded by `awman init`. Always use `awman config show` to see merged values rather than hand-editing the JSON.

See `references/config.md` for the full per-key schema (type, default, scope, merge behavior).

## API Mode

`awman api start` runs a REST server on port 9876 (configurable via `--port`). It serves **HTTPS with a self-signed certificate by default** — pass `--dangerously-skip-tls` for plain HTTP in trusted local setups. It accepts bearer-token auth. Sessions are restricted to directories in `api.workDirs` (global config) or passed via `--workdirs`.

**FIFO queue per session.** Submitting a second command while one is in flight enqueues it — submission never blocks and returns immediately with a `command_id`. Poll `GET /v1/commands/:id` or stream `/v1/commands/:id/logs/stream` (Server-Sent Events) to track progress. A `POST /v1/sessions` with a workdir outside the allowlist returns HTTP 403.

Prefer `awman remote` over raw curl when driving the server from the CLI — it carries auth and the session header per the operator-tooling-first convention.

See `references/api.md` for the full endpoint table and curl examples.

## Workflow Authoring

Workflows are TOML (`.toml`) or YAML (`.yml`/`.yaml`) files authored via `awman new workflow [--interview]` and executed via `awman exec workflow <path>`. **Markdown (`.md`) workflows are no longer supported as of 0.9.1.**

Step fields are lowercase only: `name` and `prompt` are required; `depends_on`, `agent`, and `model` are optional. Template variables available in prompts: `{{work_item_number}}` (zero-padded 4-digit), `{{work_item}}` (bare number), `{{work_item_content}}` (full