Dudes

Dudes is a supervisor for coding agents, written in Rust. You hire an agent, such as Claude Code,
Codex or Pi, and give it a role. You then talk to it, or give it a goal with a completion check.
A background daemon keeps the agent working until the daemon's own run of that
check passes. The Floor is a 3D office in your browser. It shows each agent at a desk, and what
you see there is what the daemon knows.

Status

Dudes is an early preview (pre-alpha), and commands and configuration keys can still change between
releases. Prebuilt releases for macOS and Linux on x86_64 and arm64 install with one command, as
shown below. Windows can build the binaries but has no prebuilt release or installer. The full first run has been rehearsed only on macOS on Apple silicon. See
Platforms and known limits.

Install

curl -fsSL https://raw.githubusercontent.com/ArcfluxResearch/dudes/main/install.sh | sh
~/.local/bin/dudes quickstart

The script downloads the latest release for your machine, checks it against the release's
SHA256SUMS, and only then installs duded, dudes and dudes-hook in ~/.local/bin, and the
Floor and licence notices in ~/.local/share/dudes. It never uses sudo and never edits your
shell profile. If ~/.local/bin is not on your PATH, it prints the line to add to your shell
profile. Releases cover macOS and Linux on x86_64 and arm64. On Linux the script installs a static
build that runs on any distribution. ~/.local/bin/dudes --version checks the install. To install
a specific version, run the script with sh -s -- --version <version>. You also need at least one of the claude,
codex or pi CLIs, signed in.

To build from source, or on Windows, see Build Dudes from source.
If the daemon later refuses to start because a Floor directory is writable by its group, run the
chmod go-w command that its error names (see Get started).
To remove Dudes, see Where Dudes keeps its data, and how to uninstall.

Quick start

From the repository you want agents to work in:

cd /absolute/path/to/repo
dudes quickstart
dudes floor open

dudes quickstart asks only what it cannot work out, starts the daemon, prints a link to the Floor and can
hire a first agent. Paste the link into any browser; dudes floor open prints a new one later. On a remote
machine, forward the link's port over SSH first, because the link is a loopback address. To hire an agent
yourself and give it
a goal, use the id that dudes hire prints:

dudes hire --name Cody --role "docs writer" --department docs --provider claude \
  --cwd /absolute/path/to/repo
dudes goal --agent <agent id> --text "Create hello.txt that contains the word hello." \
  --hop-cap 2 --check-id hello --check-label "hello.txt exists" -- /bin/test -f hello.txt

The agent takes turns until /bin/test -f hello.txt passes. dudes agents lists every agent and
its status, and dudes stop stops the daemon. Get started is the full
walk-through.

How it works

• Daemon and CLI. The duded daemon runs in the background and owns all state. The dudes
  command talks to it. The Floor is a view of what the daemon knows. It changes that state only
  through the actions you turn on.
• Agents and roles. An agent is one coding-agent CLI that the daemon hired to work in a
  directory. It has a name, a role and a department. The role is a label that the Floor, dudes agents and dudes team show. It is not part of the agent's task, so describe the work in the
  goal or in a chat message.
• Goals and completion checks. A goal is a piece of work plus a command, the completion check.
  Before the agent's first turn, the daemon runs the check once and refuses the goal if the check
  already passes. After each turn the daemon runs the check again. The goal is Done only when the
  check passes in the daemon's own run. What an agent reports about its own work never marks a goal
  Done.
• Limits. Spending ceilings are optional and off by default. A goal also stops at its hop cap,
  and a launch failure puts an agent on Hold. See Goals, completion checks and
  stopping.
• Mail. Agents send each other messages with dudes mail and find colleagues with
  dudes team.
• Worktrees. dudes hire --worktree gives a Claude Code agent in a repository you mark with --trusted its own git worktree and a
  branch named dudes/<id>. Dudes never merges or pushes these branches.
• The Floor. An agent types at its desk during a turn, stands at the goal board while the
  daemon runs the check, waits in the lounge when it needs your answer, and rings the bell when the
  goal is Done. The Floor explains the rest, and Chat lets you
  message an agent from it.

What agents can do on your machine

Dudes runs every agent and every completion check as your user account. It adds no sandbox of its
own. Before you hire an agent, know what each engine can reach:

• Claude Code runs with its permission prompts skipped (--dangerously-skip-permissions), and no
  Dudes setting turns them back on. It can run any command and read and change any file your
  account can.
• Codex runs inside its own workspace-write sandbox. Its commands can read any file your account
  can, and they write only in a few places the full text lists.
• Pi has no sandbox. It can run any command and read and change any file your account can.
• The completion check runs in the agent's working directory with no sandbox. Review what the agent
  changed, tests included, before you rely on a Done.

Your user account is not a security boundary. To limit what agents can reach, run Dudes in a
virtual machine or under a separate user account that holds only the repositories you want agents
to change. The full text has the details.

Documentation

• Get started: the full first run, from dudes quickstart to a goal.
• The Floor: the office view, how it opens and how to serve it.
• Chat: message an agent from the Floor, and Codex streaming.
• Goals, completion checks and stopping: replace a goal, pause, halt,
  retire and stop.
• Give an agent MCP servers: declare servers and opt agents in.
• Configuration: the operator file, settings, budgets and environment
  variables.
• What agents can do on your machine: the full safety text.
• Where Dudes keeps its data, and how to uninstall
• Build Dudes from source
• Platforms and known limits

Help, contributing and security

Ask questions and suggest ideas in Discussions;
SUPPORT.md says where each kind of request goes.
CONTRIBUTING.md lists the checks to run before you push, and
CODE_OF_CONDUCT.md sets the ground rules. Report security problems as
SECURITY.md describes, not in a public issue.

Licence

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or
  https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the
work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any
additional terms or conditions.