workingman
slimslenderslacks/workingman
Agent orchestrator: Go daemon driving claude-code agents via .project.yaml state machine
Instalação
npx convez-ai slimslenderslacks/workingman1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
orch — autonomous claude-code project daemon
orch watches one or more directories for .project.yaml files and runs
claude-code agents (project, planning, task, commit, wolf) through a state
machine until the project is done — or blocked, in which case you get a
macOS notification and a wolf-agent session to drop into.
status: ready → planning agent (writes tasks/*.yaml, sets status: working)
status: working → task agent → commit agent → next task → ... → status: done
status: blocked → wolf agent + osascript notification
status: done → terminal
The daemon also reads each project's cron: field; firings re-evaluate the
project as if its .project.yaml had been edited.
Prerequisites
- Go 1.22+
tmux— every agent runs in a detached tmux session you can attach toclaude(claude-code CLI) — the actual agent workerwsp— multi-repo workspace manager. Repos must be registered (wsp registry add ...) before the planning step finishes. If you don't have wsp set up, run with--workspace-manager=stubinstead.- macOS for
osascriptnotifications (optional; wolf still launches without them)
Build
go build -o orch ./cmd/orch
Start the daemon
Pick a directory tree where you'll keep your project files. orch watches
this tree recursively; any subdirectory with a .project.yaml becomes a
project.
mkdir -p ~/orch
./orch --root ~/orch --audit-log ~/orch/audit.log
Repeat --root for multiple trees. Watch the audit log in another shell:
tail -f ~/orch/audit.log
Walk through a project
1. Create an empty project file
mkdir -p ~/orch/my-feature
touch ~/orch/my-feature/.project.yaml
The daemon logs project_empty and launches the project agent in a
tmux session. Attach to it:
tmux list-sessions # find the session name (orch-project-<hash>)
tmux attach -t orch-project-<hash>
The agent reads .orch/instructions.md and interviews you about the
project. When it's done it writes the .project.yaml itself with
status: ready. Detach (Ctrl-b d) any time — the session keeps running.
2. Planning
The moment the project file is saved with status: ready, the daemon
launches the planning agent in the same directory. It writes
tasks/*.yaml (one file per task, with depends_on edges), then flips
.project.yaml to status: working and exits.
3. Tasks
status: working triggers the daemon to:
- Build the task DAG from
tasks/*.yaml. - Pick the first ready task (no uncommitted deps).
- Provision a wsp workspace at
~/dev/workspaces/<branch>/with the repos from.project.yaml. - Launch a task agent in that workspace.
- When the task agent exits with
status: success, launch a commit agent in the same workspace. - When the commit agent exits with
status: committed, pick the next ready task. Repeat until everything is committed, then mark the projectstatus: done.
Task agents retry up to 3 times on status: failed. After the 3rd failure
the project goes status: blocked, you get an osascript notification, and
a wolf agent launches.
4. Stop
Ctrl-C the daemon. In-flight sessions are closed; tmux sessions go away.
Stub mode (no wsp / no repos)
If you want to exercise the orchestration without wsp registered or repos to clone:
./orch --root ~/orch --workspace-manager=stub
Task and commit agents run in $TMPDIR/orch-workspaces/<branch>/ — empty
dirs the daemon creates on demand. The project and planning agents are
unaffected (they don't need a wsp workspace).
Files the daemon writes
Inside each agent's working directory:
.orch/
context.yaml # paths + branch + task name (whatever applies to this Kind)
instructions.md # rendered prompt the agent reads at startup
In the project root:
tasks/*.yaml # written by the planning agent; observed in audit
Daemon-owned writes carry updated_by: daemon in .project.yaml so the
daemon ignores its own fsnotify events.
Observability
- Audit log (
--audit-log): one line per event.tail -fit. - Tmux sessions:
tmux list-sessionsshows every live agent. Attach withtmux attach -t <name>to watch claude work or drive an interactive agent (project / wolf).
Example .project.yaml
description: |
Add a /healthz endpoint to the gateway and a matching probe in the
deploy manifests.
repos:
- org: docker
name: gateway
- org: docker
name: deploy-manifests
branch: feat/healthz-probe
status: ready
cron: "*/15 * * * *" # optional; daemon re-evaluates every 15 minutes
updated_by: agent
See examples/.project.yaml and examples/tasks/*.yaml for the full
schemas.
Cleanup
rm ~/orch/my-feature/.project.yaml
rm -rf ~/orch/my-feature/{tasks,.orch}
wsp rm feat/healthz-probe