Run and coordinate AI code agents from your terminal.
Go from issue to PR with repeatable container-isolated workflows.
awman (Agent Workflow Manager) is a developer tool that adds structure and automation to the whole agentic software development lifecycle: from issue to merged PR.
4 stages of improved agentic software development with awman
- Isolate your code agents with containers and worktrees 🛑
- Run multiple agents in parallel with the TUI 🔄
- Turn your team's development lifecycle into repeatable workflows 📈
- Automate the rest — build a squad of agents to tackle recurring work, fan out to your homelab or cluster with API mode 🤝
curl -s https://prettysmart.dev/install/awman.sh | shThe installer detects your platform and puts awman on your PATH.
Other installation options
With mise — using the GitHub backend:
mise use -g github:prettysmartdev/awmanTo pin to a specific version: mise use -g github:prettysmartdev/awman@0.11.1
From GitHub Releases — download the binary for your platform from GitHub Releases:
| Platform | Asset |
|---|---|
| Linux (x86_64) | awman-linux-amd64 |
| Linux (ARM64) | awman-linux-arm64 |
| macOS (Intel) | awman-macos-amd64 |
| macOS (Apple Silicon) | awman-macos-arm64 |
| Windows (x86_64) | awman-windows-amd64.exe |
From source — requires Rust 1.94+ and make:
git clone https://github.com/prettysmartdev/awman.git
cd awman
sudo make install# 1. Initialize your repo (once per project)
awman init
# 2. Open the TUI
awman
# 3. Start an agent session
chat
# 4. Optionally run the Dockerfile.dev refresh agent to# ensure all your project's tools get installed
ready --refreshSee the Getting Started Guide for a full walkthrough.
Open new tabs in the TUI with Ctrl+T. Each tab is independent — its own working directory, its own container — and keeps running in the background while you work in another tab. Switch with Ctrl+A / Ctrl+D.
When an agent goes quiet for 30 seconds, whether it's stuck or just finished and waiting on you, its tab turns yellow so you know where to look.
A workflow breaks complex work into phases — plan → implement → review → docs. Each phase is a separate agent session in its own container, so you review the output between phases and decide whether to continue, retry, or redirect.
Workflows are TOML or YAML files in your repo. Steps declare their dependencies with depends_on, and independent steps run in parallel. Around them, setup and teardown phases prepare the branch and handle the finish: run tests, commit, push, open the PR, and block on CI until it goes green. Any of those can carry an on_failure block that launches an agent to fix the problem and retries.
Two things make this more than a prompt runner:
- Per-step agents. Any step can name the
agentandmodelit runs with, so you can have Codex implement and Claude review in the same pipeline. Steps that don't specify one use your project's default. - Per-step overlays. Each step declares exactly what it needs from the host —
ssh()to push,env(GITHUB_TOKEN)to open a PR,skill(review)for a review checklist. Nothing gets host access it didn't ask for.
awman exec workflow ./aspec/workflows/implement-pr.toml --work-item 0027The --work-item is optional: pass one to substitute a spec you've written into the prompts, or leave it off. See Workflows for the full file format, template variables, and the control board.
A complete workflow file
title = "Implement Feature"
[[setup]]
type = "checkout_create_branch"branch = "feature/{{work_item_number}}"base = "main"
[[step]]
name = "plan"prompt = "Read work item {{work_item_content}} and produce an implementation plan."
[[step]]
name = "implement"depends_on = ["plan"]
agent = "codex"prompt = "Implement work item {{work_item_number}} according to the plan."
[[step]]
name = "review"depends_on = ["implement"]
agent = "claude"prompt = "Review the implementation for correctness and style."overlays = ["skill(review)"]
[[teardown]]
type = "run_shell"command = "make test"
[[teardown]]
type = "commit_changes"message = "Implement {{work_item_number}}"add_all = true
[[teardown]]
type = "push_branch"overlays = ["ssh()"]
[[teardown]]
type = "create_pull_request"title = "Implement {{work_item_number}}"overlays = ["env(GITHUB_TOKEN)"]Supported agents: claude, codex, opencode, maki, gemini, antigravity, copilot, crush, cline.
Don't want to write the file at all? awman exec workflow --dynamic --work-item 0027 puts a leader agent in a container, has it design a workflow for that work item, validates the result, and runs it. See Dynamic Workflows.
Workflows still need you to start them. Your squad is a group of agents that work on your behalf while you're doing something else. You give the squad tasks — "when a new issue is opened, triage it and post a plan", "if any open PR has failing tests, fix them" — and it watches for each one and runs a workflow when it fires.
awman squad start --background
awman squad add --name issue-triage \
--description "When a new issue is opened, analyze it and post a plan as a comment." \
--interval 30m --overlay "env(GITHUB_TOKEN)"On each interval one of your squad's agents decides whether the condition is actually met. If it is, the squad designs and runs a workflow for it unattended. Each task gets a durable workspace that persists across runs, so state carries between them.
Run awman squad for a TUI tab showing every task your squad is on as a card with its last and next run — press Enter for details, t to have the squad tackle a task right now, a to attach to a live run. See squad.
--yolo configures an agent to use its built-in "no permission checks" mode and keeps a workflow moving without you. Use it when the task is well specified and you want to come back to a finished result.
awman exec workflow ./aspec/workflows/implement-pr.toml --yolo --work-item 0042When a workflow step agent completes its work, a 60-second countdown starts and then advances the workflow automatically; any output from the agent cancels it. The countdown shows in the tab bar, so you can watch several autonomous runs at once without switching between them.
With exec workflow, --yolo automatically runs in an isolated Git worktree — review the whole diff as a unit and merge or discard it. For lighter autonomy, --auto approves file edits but still asks before shell commands.
awman api start exposes awman over HTTP, so heavy workflows can run on a build server or a fleet of agent-runner boxes instead of your laptop.
# On the remote machine (prints an API key on first run)
awman api start --port 9090# From your laptop
awman config set --global remote.defaultAddr <host>
awman config set --global remote.defaultAPIKey <key>
awman remote session start --workdir /workspace/myproject
awman remote exec workflow aspec/workflows/implement-pr.toml --work-item 0027 --session <id> --followRemote commands run in containers with the same isolation as local ones, and every input, output, and log is kept on the server under ~/.awman/api/ for auditing. The HTTP API is available directly to any client too. See API & Remote Mode.
Point new spec, exec workflow, or exec prompt at an issue with --issue — no local work item file needed:
awman new spec --issue 84 # turn an issue into a work item spec
awman exec workflow ./implement-pr.toml --issue 84 --worktree
awman exec prompt "Security review this" --issue 84A bare number resolves against the repo's GitHub remote; owner/repo#84 and full URLs work too. Issues are fetched via the gh CLI, a GITHUB_TOKEN, or unauthenticated for public repos. See GitHub Integration.
Every agent runs inside a container built from Dockerfile.dev — agents never touch your host machine directly.
- Only the current Git repository is mounted into the container by default
- Credentials are passed as environment variables and masked in displayed commands — never written to files inside containers
- Overlays are the only way in: opt a session into SSH keys, env vars, extra directories, or your skills library, one at a time
- awman itself is a statically compiled Rust binary — nothing running in a container can modify it
Docker, Apple Containers (macOS 26+), and Docker Sandboxes (docker-sbx-experimental, microVM isolation) are supported runtimes. See Runtimes and Security & Isolation.
awman # open the TUI
awman init [--agent <name>] # set up a project
awman ready [--refresh] # verify environment; rebuild Dockerfile.dev
awman chat [--agent <name>] [--plan] [--auto] [--yolo]
awman exec prompt "<prompt>" [--issue <ref>] # run a one-off prompt in a container
awman exec workflow <path> [--work-item <nnnn>| --issue <ref>] [--yolo] [--worktree]
awman exec workflow --dynamic --work-item <nnnn> [--leader <agent::model>] # let a leader agent design the workflow
awman new spec [--interview] [--issue <ref>] # create a work item (optionally from a GitHub issue)
awman new workflow [--interview] # create a workflow file
awman new skill [--interview] # create a skill file
awman specs amend <nnnn># update a spec to match what was built
awman status [--watch] # dashboard of all running agent containers
awman clean [--dry-run] [--yes] # remove stopped containers, stale images, and completed workflow data
awman config show # view all config values
awman squad # open your squad's TUI tab
awman squad start [--background] # put your squad on duty (starts the squad daemon)
awman squad add --name <name> --description <text> [--interval <dur>] # create a new task for your squad to tackle
awman squad trigger <name># have your squad tackle a task now, ignoring its schedule
awman squad list | show <name>| pause <name>| resume <name>| remove <name>
awman api start [--port <n>] # start the HTTP API server (generates API key on first run)
awman api status |kill# check or stop the API server
awman remote session start --workdir <dir># create a session on a remote server
awman remote exec workflow <path> [--follow] # run a workflow on a remote API server
awman remote exec prompt "<text>" [--follow] # run a one-shot prompt on a remote API serverEvery subcommand works in CLI mode and in the TUI command box (without the awman prefix). API mode accepts exec prompt and exec workflow.
- Getting Started
- Concepts
- Using the TUI
- Agent Sessions
- Security & Isolation
- Workflows
- Dynamic Workflows
- Configuration
- Overlays
- API & Remote Mode
- GitHub Integration
- Runtimes
- squad
- Cleaning Up
- Architecture
See LICENSE for details.