Tools
All commands are written in Go and live in cmd/ of the repository. make install at the root builds, tests and installs nexusctl, nexusadm, nexushelm and harnessctl, with their Claude Code hooks; proxyctl installs on its own with make -C cmd/proxyctl install.
Commands for people
| Command | Setup | Purpose |
|---|
flowctl | All | Client of the operator: submit a run (one execution of a workflow; see the glossary), list, get, watch until it ends, cancel, and usage to total tokens per model. --output json prints machine-readable output; exit codes are stable. |
proxyctl | Workstation | Local Traefik reverse proxy in HTTPS on *.localhost for every project of the computer, with mkcert certificates: up, routes add, domains add, domains check. |
nexusadm | Homelab | Cluster administration: node add and node remove, grant for time-limited accesses, secret for the keyring, audit of the API server, doctor to check the nodes, log of the actions taken. |
nexusctl | Homelab | kubectl with a chosen access, every call logged. |
nexushelm | Homelab | helm with a chosen access, every call logged, Helm releases stored in Secrets. |
harnessctl | All | Guard for Claude Code on your workstation: edits to agent rules after confirmation, and folders outside the project opened to an agent for 30 days at most. |
Actions that need cluster administration rights open a confirmation window on your desktop session.
Components of the suite
| Component | Runs in | Purpose |
|---|
nexus-dashboard | One service | Follows the items (units of work, such as a request), shows the questions that runs ask in the view “Waiting for you”, resumes a run when you answer, reads pull requests on Forgejo and drives the operator over its HTTP API. |
nexus-operator | One service | Turns WorkflowRun resources into Kubernetes Jobs, or into Docker containers with its docker engine, and follows each run until it ends. nexus-operator provision <project> prepares the namespaces of a project. |
nexus-agent | The pod of each run | Main container: runs AWF and forwards what it produces to the collector, or straight to the operator on a workstation. Its exit code is AWF’s. |
nexus-collector | The pod of each run (cluster) | Sidecar: receives the messages of the agent and of the plugin on a Unix socket, writes them to its on-disk journal and relays them to the operator over gRPC with mutual TLS. It is the only way out of the pod to the control plane. |
nexus-plugin | Inside AWF | AWF plugin that pushes the events of a run and carries the ask and report operations. |
nexus-exec | The pod of a run with a stack | Runs a program in another container of the pod, with its input, output and exit code. |
Workflows
| Pack | Content |
|---|
openspec-tdd | Pack gplanchat/awf-workflow-openspec-tdd, version pinned in deploy/runner/Dockerfile and installed in the run image: OpenSpec changes with an Elephant Goldfish Model (EGM) review in the design phases and a test written before the code. |
packs/factory | ask, apply-change, apply-many, apply-task, tdd-slice and free-task: apply OpenSpec changes in parallel, one worktree per change, a test-first cycle per task, merges one at a time and a JSON report. Install with bash packs/factory/install.sh. |
Infrastructure
| Folder | Content |
|---|
compose.yaml | The workstation setup. |
infra/ | Ansible playbook and roles of the homelab setup: base system, MicroK8s, Kueue, firewall, DNS, certificate authority, WireGuard, backup target. |
deploy/helm/nexus-factory | Helm chart of the cluster setups. |
api/ | OpenAPI contract of the dashboard. |