afiffattouh/handloom

Contents
What you get · How it works · Quick start · Install · Uninstall · Ways to use it · Teams · Client knowledge · Agent CLIs · Guard rails · Run it yourself · Status · Documentation · Contributing
What you get
| | |
| --- | --- |
| **Projects** | A name plus a shared git repository. With no GitHub at all, the hub can hold it for you; or attach one that exists, or have a machine create one on GitHub. Any machine fetches its own copy on demand. |
| **Jobs with a lead** | Each job has its own lead agent, a team of workers, tasks with owners and dependencies, and a brief that says what done looks like. |
| **Profiles and skills** | What an agent may do and know, as versioned, hash-pinned profiles: tools, denied commands, allowed paths, skills. 41 ready-made starters (engineering, design, research, consulting, marketing, sales, finance, HR) and a form that asks "what should it do?" in plain words. |
| **Any agent CLI, any model** | Claude Code, Codex, OMP, Pi and OpenCode, including models running on your own machine. Handloom limits each as far as that CLI allows and says plainly what it cannot enforce. |
| **Proof, not claims** | A task is submitted with evidence. The device runs the job's check, refuses edits outside the profile's paths, merges accepted work into an integration branch and re-checks it. A lead cannot accept failed work. |
| **Only people approve** | Starting and closing jobs, answering questions and writing profiles need a signed-in person. Agents, devices and AI apps cannot. |
| **Web, terminal, CLI, MCP** | A server-rendered web UI, a full-screen terminal console, every action as a command, and an MCP server so your own AI app can look at your work and start jobs. |
| **Client knowledge** | A knowledge repository per client that agents read first; what they learn comes back as a proposal on a branch that only you merge. handloom search finds notes and earlier jobs' work so the next job reuses them. |
Inbox. What needs a person, in one place, live.
A job. Every task with its owner, evidence and check.
An agent. Its state, lease, and a read-only view of its terminal.
Starter library. Ready-made roles, each with its skills.
How it works
1. **You start a job** in the web UI, the console or the CLI: a title, a brief, a machine, optionally a repository and a check command.
2. **The lead plans it.** The hub records a spawn request; the link on that machine makes a git worktree, opens a tmux window and starts the lead from its profile. The lead creates tasks and asks the link to start workers.
3. **Workers build in their own worktrees** and submit with evidence. The link refuses a submit that touches files outside the profile's paths, then runs the job's check.
4. **The lead reviews.** It can accept only work whose check passed. The link merges accepted branches into job/ /integration and re-checks; a conflict goes back to the lead.
5. **You decide.** Questions land in your inbox (and on your phone). When every task is done you look at the result, close the job, and merge the integration branch yourself. Nothing touches your own branches.
The hub never runs a shell or a model, and it runs git only for a project you chose to let it hold (below), so it can be small and public. Everything that runs code lives on machines you own, and the device's word beats the agent's word.
**One job, from your sentence to a branch you can merge.** Read down: each box sits in the lane of whoever does it, and dashed boxes are waiting, not working.
At any step an agent can ask you a question. It lands in your inbox and on your phone, and only you can answer it. If the lead goes quiet its lease runs out, the job shows "lead lost", and you can hand it to another agent.
**Who is responsible for what.** The split is deliberate: the hub can be public and small because it never touches a repository.
Quick start
Four stages, each done once. The long version, with the domain, https and every token explained, is docs/setup.md.
**1. Run the hub** on any server with Docker:
Open https://handloom.example.com/setup, enter the setup code and make your owner account. Keep the admin token somewhere safe. On Dokploy, see docs/deploy.md.
**2. Join each machine** that will run agents. In the web UI go to Machines, Add a machine, give it a name, and paste the one line the page shows on that machine. The page shows a line for each system; the paths are below. When the machine is ready, the page says so by itself. More detail, and what to do when something is missing, is in docs/add-a-machine.md.