Workflies Documentation

Everything you need to install Workflies, set up a project, and run a team of people and AI agents on it.

Overview

Workflies is a project tracker that lives inside your git repository. Tickets, the workflow, releases and the team are plain files under a .wflies/ folder, versioned and shared by git exactly like your code. A single program, wflies, runs on your computer and gives you:

• A web board — called Airfield — at http://127.0.0.1:7333.
• An MCP server that coding agents (Claude Code, Cursor, Codex, VS Code Copilot…) use to read, claim and update tickets.
• A command line for everything, with --json output for scripts.
• A REST API that the board and the phone app are built on.

All four go through the same core, so a rule you set applies identically whether a change comes from you on the board, from a script, or from an agent.

Principles

• The file format is the product. Your tickets are readable JSON and markdown. If Workflies disappeared tomorrow, your history would still be in your repo.
• Nothing to host. No accounts, no server, no subscription. git push and git pull are the sync.
• Conflicts are normal, never fatal. The format is designed so branches rarely conflict, and wflies resolve repairs the ones that do.
• People stay accountable. Agents do the work; only a person can clear a human gate or override a rule.
• Process is data. Your workflow is a short YAML block and a few markdown guides — not an engine with scripts.

Requirements

Installation

Releases are published at github.com/AharonDL/workflies-releases. Every release carries archives for each platform, the installer, and a checksums.txt with SHA-256 hashes.

Install script (macOS and Linux)

$ curl -fsSL https://wflies.com/install.sh | sh

The script:

1. detects your OS and CPU architecture;
2. finds the latest release (or the one in WFLIES_VERSION);
3. downloads the matching archive and checksums.txt;
4. verifies the SHA-256 hash and stops before installing anything if it does not match;
5. installs wflies into /usr/local/bin, or ~/.local/bin if that is not writable, and tells you if the folder is not on your PATH.

$ curl -fsSL https://wflies.com/install.sh | WFLIES_VERSION=v1.2.3 WFLIES_INSTALL_DIR="$HOME/bin" sh

https://wflies.com/install.sh forwards to the installer attached to the latest release, https://github.com/AharonDL/workflies-releases/releases/latest/download/install.sh. The script needs curl, tar and sha256sum or shasum — all standard on macOS and Linux.

Homebrew (macOS)

$ brew install --cask aharondl/workflies/wflies

The cask comes from the AharonDL/homebrew-workflies tap and clears macOS's quarantine flag so the binary runs straight away.

Windows

1. Download wflies_<version>_windows_amd64.zip from the latest release.
2. Unzip it and move wflies.exe into a folder on your PATH.
3. Open a new terminal and run wflies --version.

Everything works on Windows except wflies service install (start at login), which is macOS and Linux only — run wflies start instead.

Manual download

Each archive holds the wflies binary, LICENSE and THIRD_PARTY_NOTICES.txt. Verify before installing:

$ sha256sum --ignore-missing -c checksums.txt                 # Linux
$ shasum -a 256 --ignore-missing -c checksums.txt             # macOS
$ tar -xzf wflies_*_darwin_arm64.tar.gz && sudo mv wflies /usr/local/bin/

Check the install

$ wflies --version
wflies v1.2.3

Quickstart

This takes a project from nothing to a board with an agent working on it. Run every command from your project's root folder — project commands do not search parent folders.

1. Initialise the project

$ cd ~/code/acme-app
$ git init -b main          # only if it is not a git repo yet
$ wflies init
Initialized Workflies project at /home/dana/acme-app (prefix ACMEAPP)
Starter team: agent, dana-lee
Registered. To see it, run `wflies start` and open the URL it prints — it serves every registered project.

wflies init creates .wflies/ with the default workflow and a guide for each status, adds you (from your git name and email) and the project's agent to the team, installs a git merge driver for Workflies files, and registers the project on this computer. Re-running it is safe; it never overwrites existing files.

Options: --prefix ACME sets the ticket id prefix (default: from the folder name). --autonomy free|copilot|tower chooses how many human gates you start with (see Autonomy levels).

2. Connect your coding agent

$ wflies init agent claude-code
Onboarded runtime "claude-code"

Use cursor, codex or vscode for the other agents. See Agent setup for exactly what is written.

3. Start the board

$ wflies start
Workflies is running at http://127.0.0.1:7333
It runs in the background and keeps going when you close this terminal.
Log: /home/dana/.config/wflies/agent.log
Stop it with `wflies stop`; check it with `wflies status`.

Open the board in your browser. One background process serves every project registered on the computer. To have it start automatically at login, run wflies service install (macOS and Linux).

4. Create a ticket

On the board, press Fold an idea — or from the terminal:

$ wflies create --title "Add CSV export to reports" --type story --priority high \
    --description "Users want to download a report as CSV."
Created ACMEAPP-51b9: Add CSV export to reports (status: ideas)

5. Hand it to the agent

In Claude Code:

/wf-ticket ACMEAPP-51b9

The agent adopts the project's agent member, reads the guide for the ticket's status, writes what that status needs (a UX section, acceptance criteria, an architecture plan, a test plan…), and moves the ticket forward. When the next status is one only a person may enter, it asks you with request_gate and moves on. Your requests appear on the board's Tower as calls — clear them with one click.

6. See a gate in action

Try to move the ticket straight to Ready:

$ wflies update ACMEAPP-51b9 --status ready --as dana-lee
Cannot move to "ready" — gate check failed:
  [x] section Architecture — Add a non-empty `## Architecture` section to the ticket body.
  [x] checklist-exists Acceptance criteria — Add an `## Acceptance criteria` section with at least one `- [ ]` item.
  [x] checklist-exists Test Plan — Add an `## Test Plan` section with at least one `- [ ]` item.
Use --override --reason "..." to proceed anyway.

Every surface — board, CLI, REST and MCP — returns the same list of what is missing and how to fix it. Agents fix it and retry; they can never override.

7. Share it

$ git push

That is all. A teammate who pulls and runs wflies start sees the same board. With the board running, Workflies commits its own .wflies/ changes for you every 30 seconds (it never pushes).

Upgrading

1. Get the new binary the way you installed it: re-run curl -fsSL https://wflies.com/install.sh | sh, or brew upgrade --cask wflies, or download the new Windows zip.
2. Restart the background server: wflies stop && wflies start. Running agent sessions survive the restart and are picked up again.
3. Update each project: in the project folder run wflies update. It applies data migrations, refreshes the agent onboarding blocks, runs the health check, and also migrates every other registered project. wflies update --check shows what it would do without changing anything.
4. Refresh skills when release notes say they changed: wflies generate skills.

Uninstalling

1. Stop the background server: wflies stop. If you installed the login service: wflies service uninstall.
2. Remove the binary: brew uninstall --cask wflies, or delete /usr/local/bin/wflies (or ~/.local/bin/wflies), or delete wflies.exe on Windows.
3. Optionally remove this computer's Workflies state — the project list, logs, agent run history and phone pairings: ~/Library/Application Support/wflies (macOS), ~/.config/wflies (Linux) or %AppData%\wflies (Windows).

Your projects' .wflies/ folders are untouched: they are plain files in your repositories and stay readable without Workflies. To stop serving one project without uninstalling, run wflies forget <path-or-name>.

How Workflies works

Everything that matters is a file under .wflies/ in your repository. The wflies program reads and writes those files and keeps a small disposable index (SQLite, under .wflies/.cache/, never committed) so the board stays instant on large projects. Delete the index and it is rebuilt from the files.

One background process — started with wflies start — serves every project registered on your computer: the board, the REST API, live updates, file watching, autocommit, agent runs and the optional phone connection. It listens only on 127.0.0.1. Coding agents reach Workflies through wflies mcp, a small MCP server they launch themselves.

All writes, from every surface, go through one core that enforces your workflow. There is no way around a gate that only one surface knows about.

Tickets

Ids

A ticket id is your project prefix plus four random characters: ACME-7k3d. Ids are random, not counters, so two branches can create tickets at the same time without colliding. In the rare case that they do, wflies resolve renames the younger one and rewrites references to it.

Types and fields

Sections

A ticket's body is a list of named sections — Description, UX, Acceptance criteria, Architecture, Test Plan, Root Cause and so on — each holding markdown. Gates read sections by name, so "the ticket needs an Architecture section" is a rule Workflies can check.

On disk

Each ticket is two files: tickets/ACME-7k3d.json with its fields and sections, and tickets/ACME-7k3d.log.jsonl, its append-only activity log.

{"id":"ACME-7k3d","title":"Add keyboard shortcuts to the board view","status":"in-progress",
 "type":"story","priority":"high","assignee":"agent","delegate":"claude-code",
 "body":[{"heading":"Description","content":"…"},
         {"heading":"Acceptance criteria","content":"- [ ] `j/k` navigate cards\n- [x] `s` cycles status"}]}

The activity log

Every change is a line in the log: field changes, comments, progress notes, questions and answers, approvals, overrides, agent sessions with their summaries and token usage, links to branches, commits and pull requests, and notes left by merges. Each line records the actor (a member) and, for agents, via (the runtime). The log is never rewritten, which gives every ticket a complete audit trail.

Epics

An epic is not built itself — its children deliver it. In the default workflow an epic skips In Progress and Code Review, needs at least one child to leave Ideas, and is Done when all its children are. An epic can be flown as a route.

The graveyard

Done and archived tickets with no activity for 30 days move to .wflies/graveyard/<year-month>/, keeping the live project small. Browse them on the board's Plane graveyard page or with wflies graveyard list, and bring one back with wflies graveyard revive <id>. Change the delay with settings.graveyard.after (off disables it).

Checklists

Checklists in sections have three states:

- [ ] Export includes every visible column            # open
- [x] Download starts within one second                # done
- [>] Works with 100k rows — measured 40k locally; full size needs the staging data, settles in QA   # deferred

A deferred line (- [>]) is an honest "this cannot be settled here": it must say what was proved instead and where the rest gets settled. A deferral without a reason is refused everywhere. Deferred lines let finished work leave the build (the checklist-done rule accepts them), but they must be proved before Done (checklist-verified does not). Tickets with deferrals show an N deferred chip on the board.

Statuses & status guides

You name your statuses; each belongs to one of five fixed categories — backlog, unstarted, started, done, canceled — so tools always know what a status means. The default workflow is:

Bugs also need a Root Cause section to be Done; spikes need Findings and Decision.

Status guides

Each status can have a guide, .wflies/statuses/<status-id>.md: plain markdown describing what a ticket needs before it may leave that status. It is the operating manual for whoever holds the ticket — a person or the agent. Agents read it before working and read the next status's guide before moving on. Workflies prefixes each guide with a generated line saying whether a person must move tickets in and which entry check applies, so a guide can never drift from its gate. Only a person can edit a guide — an agent may not rewrite its own instructions.

WIP limits

A status can set an advisory wip limit, shown as 4/6 on the column and highlighted when exceeded. It never blocks a person; an agent's claim refuses a status that is over its limit.

Gates & recipes

Workflies calls this branch protection for tickets. A recipe is a named checklist of rules; a status says which recipe a ticket must satisfy to enter it. Your Definition of Ready and Definition of Done are just recipes.

workflow:
  statuses:
    - {id: ready, name: Ready, category: unstarted, requires: dor, human-gate: true}
    - {id: done,  name: Done,  category: done, requires: {default: dod, bug: dod-bug}}
  recipes:
    dor:
      name: Definition of Ready
      require:
        - {rule: section, value: Description}
        - {rule: checklist-exists, value: Acceptance criteria}
        - {rule: field, value: estimate, severity: warn}
  overrides: {allowed: true, require_reason: true, agents: false}

Rules

Every rule has a severity: block (default) stops the move; warn lets it through and names what was missing. The vocabulary is deliberately closed — no scripts, no plugins — so every rule can explain exactly how to fix itself:

{"to": "ready", "allowed": false,
 "unmet": [{"rule": "section", "value": "Description", "severity": "block",
            "fix": "Add a non-empty '## Description' section to the ticket body."}]}

Tightening a gate never invalidates tickets already past it: gates apply on entry. wflies doctor --gate-audit lists every ticket that would fail today's gates.

Workflow presets

Add common stages with wflies workflow apply <preset> or Settings → Workflow:

• qa-stage — an In QA status with its own entry check.
• design-stage — an In Design status and a design sign-off before development.
• bug-triage — a Triage inbox and a severity field required on bugs.
• agent-first — a strictly machine-checkable Ready gate and a WIP cap on development.
• release-layer — release notes and a sign-off required on epics.

An invalid workflow never locks you out: Workflies falls back to warn-only rules and shows a banner until it is fixed.

Human gates & overrides

A status marked human-gate: true can only be entered by a person. When a ticket meets everything for the next status and that status is human-gated, the ticket needs you: it shows on the Tower with an Approve button (Clear) and Send back (Send around). An agent asks with request_gate and a short note, then carries on with other work. Sending a ticket back records why, and the agent has to change something before asking again.

Overrides. A person may move a ticket past a failed rule with a reason; the override is recorded permanently in the log and shown on the ticket. Agents can never override — that setting cannot be turned on.

Autonomy levels

How much the agent may do without you is set by which statuses are human-gated. Three named levels:

Any other combination is Custom — the default workflow (Ready and QA gated) shows as Custom (QA, Ready). Switch with wflies autonomy copilot or Settings → Workflow → Autonomy; you see which waiting tickets the change would release before confirming. Autonomy only ever removes approvals — questions, conflicts and set-aside work always reach a person.

Your team

A project has people and exactly one agent. Members are markdown files in .wflies/members/ with a short charter. The status guides — not job titles — tell the agent what each piece of work requires, so the same agent can plan, build, review and verify.

$ wflies members list
agent     agent   Agent
dana-lee  person  Dana Lee
$ wflies members add --key sam --name "Sam Ortiz" --email [email protected]
$ wflies members sync          # add people from the git history

Removing a member leaves a tombstone, so history stays intact; their tickets are reassigned or unassigned. Work is attributed in two parts: the actor (the member) and via (the runtime that did it).

Agent setup

wflies init agent <runtime> registers the MCP server with your agent and writes the onboarding it reads at the start of every session.

Skills are also written to .agents/skills/, the shared Agent Skills location. Any other MCP client can run the server directly:

{"mcpServers": {"wflies": {"command": "wflies", "args": ["mcp"]}}}

The onboarding text sits between <!-- wflies:begin --> and <!-- wflies:end --> markers. wflies update refreshes only what is inside them and notices hand edits; set settings.auto-refresh-onboarding: false to stop it. Skills are rewritten only by wflies generate skills.

What the onboarding tells the agent

• Start every ticket session with adopt_member, and read the guide for the status it is in.
• Keep going through as many statuses as the ticket will go; stop only at a human gate, an approval, a decision that is genuinely a person's, or access it lacks.
• Finish the work in the ticket rather than filing follow-ups.
• Never create branches or worktrees and never merge — Workflies owns the workspace.
• Run only the tests that cover the change.
• Record a verification pass with qa-verified after re-running the test plan.
• Write comments for a person: a few plain sentences, one question at a time.

Skills

You don't need the slash commands: "work on ACME-7k3d" or "clear the code review column" trigger the same skills.

How an agent works a ticket

1. Adopt. adopt_member returns the agent's charter, the rules, every status with its guide and whether it is human-gated, and the current release.
2. Claim. claim_task takes an expiring lease (one hour by default, renewed by activity) so two agents never work the same ticket.
3. Work. The agent does what the status guide asks and writes it into the ticket's sections.
4. Follow next. Every ticket the agent reads carries a next.do: write, move, request_gate, verify, merge, wait, complete, stop… The agent does what it says.
5. Ask when needed. post_progress with kind: question flags the ticket as blocked on you and notifies you.
6. Finish. complete_task records a summary and moves the ticket; report_usage records tokens and cost.

Agents are asked to end every commit with a Workflies-Ticket: <id> trailer so commits can be attributed to tickets.

Runs, queue & autopilot

Besides an agent you drive in your own terminal, Workflies can launch agents itself. Connect a runtime in Settings → Agents & models (Claude Code, Codex or Cursor; their CLIs must be installed) and choose which models to offer.

Start agent work

On any ticket, start a supervised run. Its activity streams live to the ticket, and it writes a summary at the end even if the board was closed. A run cannot end "completed" with work left: the agent is told what remains and gets another turn; after several turns without progress it parks as Stopped short for you to look at.

Run queue

A hand-ordered list of tickets for the agent to work one after another.

Autopilot

Picks eligible work by your rules: which statuses and release, which model per status or type, how many in parallel, retries, a budget per run and a spend cap per day or week. Autopilot settings live on your computer only — a teammate's git pull can never switch it on.

Machine limit

Settings → Machine caps how many agent sessions run at once on this computer (by default a quarter of your CPU cores, at most 4).

See every live and parked run on the Agent runs page, and cost by ticket, epic, release, model or day on Usage & cost. From the terminal: wflies agent sessions lists them and wflies agent stop-sessions stops them.

Flight attendant

Not everything is a ticket. The Flight attendant (the call button in the top bar) takes free-form requests about the whole project — "go through everything waiting for me", "order my epics and queue them" — and does them with the same one-click actions you have on the board. It can propose approvals for you to accept, but never approves or signs anything off itself.

MCP tools

wflies mcp is a stdio MCP server. It finds the project by walking up from the current folder to the nearest .wflies/ (or use --project). Every write goes through the same rules as the board.

Some tools appear only inside a particular kind of run: route for routes; plan_publish, plan_file and plan_complete for planning sessions; request_update, request_ask, request_propose_clearances, launch_runs, rank_tickets and project_action for the Flight attendant; release for the release manager. create_task, list_tasks and get_task also accept a project to work across registered projects.

The board (Airfield)

Open http://127.0.0.1:7333. Tickets are planes, you are the tower, the agent is the pilot. A fixed colour key runs through everything: amber a person is needed, mint the agent is working, blue cruising, and coral for trouble.

Tower

Your home screen: everything that needs you — approvals, questions, merges, trouble — ordered by impact and clearable in place. Keyboard: J/K to move, A to approve.

Flight board

The board. Drag cards between columns; columns you can't drop into are tinted, and a refused drop opens the list of what to fix. Select several cards to move, assign, queue or launch them together.

Hangar

The backlog, grouped by status and ranked by drag, with a Needs grooming view.

Ticket page

One Now card says the single next action; sections carry gate badges; the side rail shows the next status's checklist; the timeline is the activity log.

Routes, Releases, Plans

See the sections below.

More

Flight attendant, Crew (team), Agent runs, Landings (merges), Tests, Usage & cost, Views (saved filters), Plane graveyard.

Settings

Workflow, Agents & models, Autopilot, Routes, Machine, Phones, Notifications, Appearance and a Health check.

Press ⌘K / Ctrl K anywhere for the command palette. The project switcher shows every registered project with its counts.

Releases

A release groups the tickets that ship together. Records live in .wflies/releases/<id>.md and move planned → open → releasing → released (or canceled).

$ wflies release create --name "Payments polish" --version 1.4.0 --target 2026-11-01 \
    --goal "Card payments without a reload" --current
$ wflies release open payments-polish
$ wflies release show payments-polish --readiness

• Current release. At most one; new tickets join it automatically (settings.releases.auto_join).
• Modes. shared work lands on your main branch; branch cuts wf/release/<id> when the release opens and ships it in one merge.
• Readiness — "Nothing missing?" Facts, never locks: unfinished tickets, required test suites passed on the exact commit, merge state, how far behind main, migrations, release notes, release steps.
• Release run. wflies release run <id> (or the button) bumps version files, writes the changelog, runs your before-release steps and required suites on the exact commit, tags it, merges and pushes, runs after-release steps and closes the release. Releasing is always a person's decision. Follow it with wflies release status; wflies release stop stops it before it merges.
• Release manager. If a suite fails or a merge conflicts, an agent can be woken in a sandbox to fix it. It can only report "ready" or "escalate" — it never tags, merges or ships; a code change it makes waits for your OK.
• Trust. Commands committed to the repo (test suites, release steps) run only after a person on this computer has trusted their exact content.

Releases were called sprints before; wflies sprint still works as an alias.

Plans

For a bigger idea, choose Plan it. In a planning session you are the product owner and the agent acts as architect, product designer, security reviewer and researcher. It investigates and experiments in its own branch, then publishes a plan: a summary, the design, questions for you, red flags, suggested changes, research with sources, and a preview of the tickets. You comment and it revises until you approve one revision; then it writes the detailed design and files groomed, ordered epics and tickets. The plan lands in docs/plans/<slug>/. Find them on the Plans page.

Routes

Fly this route hands a whole epic to the agent: every child planned, built, reviewed, merged and verified — with every gate still applied.

• Flight control — a deterministic scheduler — launches work, enforces concurrency, retries and merges.
• The lead pilot plans the children and makes decisions (retry, split, escalate); it is woken only when a decision is needed.
• Each child is flown by a wingman in its own branch and worktree, cut from wf/route/<epic>.
• Children declare the areas of the code they touch; overlapping areas never fly at once.
• Nothing reaches your main branch until the route lands. At Free flight it lands itself when its test plan passes; otherwise you get one Clear all & land that approves each child in order.

Defaults (concurrency, cost cap, models, plan review) live in settings.routes and Settings → Routes.

Merging & wflies resolve

The file format is built so that branches rarely conflict:

• One file per ticket, random ids — different tickets never touch the same file.
• Activity logs are append-only and merged as a union.
• Fields are grouped and time-stamped; if only one side changed a group, that side wins.
• The ticket body merges section by section.

When two branches really did change the same thing, the newer value wins and the losing value is written to the ticket's log as a resolve-note — nothing is silently lost. Text both sides edited in the same section is kept side by side for you to pick.

$ git merge feature-branch
CONFLICT (content): Merge conflict in .wflies/tickets/ACME-7k3d.json
$ wflies resolve
Resolved 1 file(s).

wflies init installs a git merge driver and .gitattributes, so local merges usually resolve on their own. GitHub and GitLab don't run merge drivers; with the board running, Workflies notices conflict markers after a pull and resolves them automatically.

Git sync & workspaces

Sync is git. Push and pull as usual; tickets only reach others on branches that are merged.

Autocommit. While the board is running, Workflies commits its own .wflies/ changes 30 seconds after the last write, with messages like wflies: 3 ticket updates (ACME-7k3d…). It never pushes, never touches other files and never commits during a merge or rebase. Set autocommit to immediate or off in config.yml.

Workspaces. settings.workspace.mode: isolated gives each ticket its own branch and worktree when development starts, merged back at the status you choose (merge-at), by a person or the agent (merged-by). Worktrees live beside your repository in .wflies-worktrees-<repo>/. In the default shared mode everyone works on the current branch.

Test suites

Declare your test suites in config.yml and run them from the Tests page, on a schedule, or as part of a release:

settings:
  tests:
    suites:
      - id: unit
        name: Unit tests
        command: go test ./...
        report: reports/junit.xml      # optional: JUnit XML; else written to $WFLIES_TEST_REPORT
        timeout-minutes: 30

Workflies reads JUnit XML (Go, pytest, Jest, node --test and others), shows each suite's last result, a 20-run history and what is newly failing, and can file a "fix it" ticket for the agent. A new or changed suite must be trusted on your computer before it runs. Suites listed in settings.releases.required_suites must pass on the exact commit a release ships.

Phone app

The app is the same board, on your phone, talking directly to the wflies on your computer — no account and no cloud copy of your tickets.

Pairing a phone

1. Turn phone access on — it is off by default: Settings → Phones, or wflies mobile enable. Then restart: wflies stop && wflies start.
2. Choose Pair a phone, or run wflies pair. A QR code appears; it works once, for two minutes.
3. In the app, choose Pair with a computer and scan it.
4. Both screens show four words. If they don't match, press Don't pair — something is in the middle.
5. Approve on the computer and choose what the phone may do (read, write, launch agents), which projects it sees, and when access expires (7, 30 or 90 days, a year, or never).

After that the phone reconnects by itself. Manage phones with wflies devices list and wflies devices revoke <id>; wflies mobile disable stops answering phones but keeps pairings.

Security. Phone and computer authenticate each other with certificates pinned at pairing (mutual TLS) — no passwords, tokens or accounts. Keys are stored outside your repository. A phone can never reach the computer's own control endpoints, whatever it was granted.

Connect from anywhere

At home the phone talks to your computer over your own network. Away from home you have two options:

• Your own network path — a Tailscale name, a tunnel or a forwarded port: wflies mobile enable --remote-url <address>. Workflies only hands that address to the phone.
• The Workflies relay — wflies mobile relay on or the toggle in Settings → Phones, then restart. Phones you already paired use it automatically.

What the relay can and cannot see. The encrypted connection between your phone and your computer runs through the relay, end to end; the relay only passes bytes it cannot read or alter. It cannot see tickets, code or messages and cannot act for you. It keeps no accounts and no database. It records which computer and phone connected, when, how much data passed, and the IP addresses — kept for 7 days. Your home network is still used first whenever it works. wflies mobile relay off turns it off.

Notifications

With a phone paired, Workflies can tell you when something needs you. Your computer decides what is worth a notification — categories: needs me, trouble, routes, plans, attendant and watched tickets — and you can silence them for an hour, until tomorrow, or until turned back on. Watch any ticket with the bell on its page.

On iPhone, notifications are delivered by push through the relay and Apple, encrypted on your computer with a key only your phone holds: the relay and Apple only ever see "Workflies — New activity", and the phone decrypts the real text. Otherwise notifications appear while the app is open. Configure them in Settings → Notifications.

CLI reference

Every command accepts --json for machine-readable output and -h for help. Project commands run in the project's root folder. Errors exit with status 1 unless noted.

Setup & maintenance

wflies init [--prefix P] [--autonomy free|copilot|tower]

Create .wflies/, the default workflow and guides, the agent and you as members; install the merge driver; register the project. Safe to re-run.

wflies init agent <claude-code|cursor|codex|vscode>

Connect a coding agent: MCP registration plus onboarding files.

wflies generate skills

Rewrite every agent skill file and remove ones this version no longer ships.

wflies update [--check]

With no ticket id: run data migrations, refresh onboarding blocks, run the health check and migrate other registered projects. Does not replace the binary. --check changes nothing.

wflies doctor [--gate-audit] [--kill-orphans]

Check data files, workflow config and agent setup. Exits 0 when clean, 2 with warnings, 1 with errors. --gate-audit lists tickets failing today's gates; --kill-orphans stops stray processes from test runs.

wflies index check · wflies index rebuild

Compare the local index with the files (exit 1 on disagreement), or rebuild it — always safe.

wflies resolve

Repair conflicted .wflies/ files after a merge or pull.

wflies workflow apply <preset>

Add qa-stage, design-stage, bug-triage, agent-first or release-layer to the workflow.

wflies autonomy [free|copilot|tower|custom:<ids>] [--yes]

Show or change the autonomy level, with a preview of what it would release.

wflies completion <bash|zsh|fish|powershell>

Print a shell completion script.

Tickets

wflies create --title T [--type] [--priority] [--assignee] [--description] [--epic] [--parent] [--estimate] [--labels a,b] [--sprint <release|none>]

Create a ticket in the first status of the workflow. It joins its epic's release or the current one unless told otherwise.

wflies list [--status] [--assignee] [--epic] [--label] [--sprint] [--query Q] [--ready] [--archived]

List tickets. --ready is the agent's pull queue: not started, not blocked, not claimed.

wflies show <id>

Fields, sections and the activity log.

wflies update <id> [--title …] [--status S] [--labels a,b] [--set field=value] [--set "body:Heading=text"] [--as member] [--as-agent] [--override --reason R]

Edit a ticket. Status changes are gate-checked; --override with a reason lets a person past a failed rule.

wflies comment <id> <text> [--as member] [--via runtime]

Add a comment.

wflies ready <id> · wflies close <id>

Move to the default not-started status / archive it. Gate-checked; take --as, --override, --reason.

wflies claim <id> --as member [--via runtime] [--lease 1h]

Claim a ticket with an expiring lease. Never crosses a human gate.

wflies release <ticket-id> --as member

Hand back a claim before its lease runs out.

wflies graveyard list|retire|revive <id>|cleanup

Browse, retire, bring back or permanently delete retired tickets. cleanup previews first and needs --yes --confirm <count> --as <member>.

$ wflies update ACME-51b9 --set "body:Acceptance criteria=- [ ] CSV download button" --as dana-lee
$ wflies list --status ready --json

Members

wflies members list

Everyone on the team.

wflies members add --key K [--name] [--email a,b] [--capacity N] [--charter text | --charter-file F]

Add a person.

wflies members remove <key> (--reassign-to K | --unassign) [--yes] [--as member]

Remove a member, reassigning or unassigning their tickets.

wflies members sync

Add people from the git history.

Releases

wflies release list · show <id> [--readiness]

List releases (the current one is marked) / show one, optionally with its readiness facts.

wflies release create --name N [--id] [--version] [--goal] [--start] [--target] [--mode shared|branch] [--base] [--current]

Create a planned release.

wflies release edit <id> …

Edit name, version, goal, notes, release notes, retro, dates, mode, branch, or the current pin.

wflies release open <id> · cancel <id>

Open a release (cutting its branch in branch mode) / cancel one that has not shipped.

wflies release run <id> [--yes] · status <id> · stop <id>

Run, follow or stop a release run. Needs the background server.

wflies release steps propose <file|->

Validate release steps and save them for a person to review and trust.

Background server

wflies start [--addr 127.0.0.1:7333] [--foreground]

Start the background server for every registered project and register the current one. If it is already running, just registers.

wflies stop [--force]

Stop it. Agent sessions keep running.

wflies status

Address, uptime, log file and projects. Exits 3 if not running, 4 if a project cannot be read.

wflies service install [--addr] · service uninstall

Start automatically at login (systemd user unit on Linux, LaunchAgent on macOS).

wflies forget [path-or-name]

Stop serving a project and remove it from this computer's list. Never deletes files.

wflies agent sessions · wflies agent stop-sessions [--project slug]

List agent sessions on this computer / stop them, letting each write its summary.

wflies mcp [--project path]

The MCP server for coding agents (stdio).

There is no logs command: the server log is agent.log in the machine folder, and wflies status prints its path.

Phones

wflies mobile enable [--port 7334] [--remote-url URL] · mobile disable · mobile status

Turn phone access on or off, or check it.

wflies mobile relay on|off [--yes]

Connect from anywhere through the encrypted relay.

wflies pair [--scopes read,write] [--projects …] [--expires 30d] [--extend-on-use]

Pair a phone. Scopes: read, write, launch-agents, release. Expiry: 7d, 30d, 90d, 1y, never.

wflies devices list · devices revoke <device-id>

List or revoke paired phones.

Files & directories

In your repository

.gitattributes               # merge rules for .wflies, added by init
.wflies/
├── config.yml               # workflow, settings and saved views
├── config.log.jsonl         # audit log of workflow changes
├── VERSION                  # data format version
├── agentsetup.json          # fingerprints of generated agent files
├── tickets/
│   ├── ACME-7k3d.json       # the ticket
│   └── ACME-7k3d.log.jsonl  # its activity log
├── members/<key>.md         # people and the agent
├── statuses/<status-id>.md  # status guides
├── releases/<id>.md         # releases
├── attachments/<ticket>/    # files attached to tickets
├── graveyard/<yyyy-mm>/     # retired tickets
└── .cache/                  # local index — never committed

On your computer

Per-machine state lives outside your repositories and is never committed:

It holds registry.json (registered projects), agent.log (the server log), connected agent runtimes, autopilot and queue settings, agent run history, test run history, which committed commands you trusted, and phone pairings and keys.

Configuration

.wflies/config.yml is committed and shared by the team. Most of it is edited from Settings on the board.

prefix: ACME
autocommit: batch                 # batch | immediate | off
workflow:                         # omit to use the default workflow
  statuses: [ … ]
  recipes: { … }
  overrides: {allowed: true, require_reason: true, agents: false}
settings:
  workspace: {mode: shared, merge-at: code-review, merged-by: human, base: main}
  graveyard: {after: 30d}
  persistent-session: true        # one agent conversation per ticket
  auto-refresh-onboarding: true
  tests: {suites: [ … ]}
  routes: {max-wingmen: 2, cost-cap-usd: 0}
  releases:
    auto_join: true
    version_scheme: semver
    tag_pattern: "v{version}"
    version_files: [package.json]
    changelog: CHANGELOG.md
    required_suites: [unit]
    steps: [ … ]
filters:                          # saved views
  - {id: 01J8Z5R9M7TC0F4X1B2K5N8QPD, name: Mine, assignee: ["@me"]}

Environment variables

Test suites receive WFLIES_TEST_REPORT, WFLIES_TEST_SUITE, WFLIES_COMMIT, WFLIES_BRANCH and CI=1; release steps receive WFLIES_RELEASE_ID, WFLIES_RELEASE_VERSION, WFLIES_RELEASE_TAG and WFLIES_RELEASE_COMMIT.

Ports & network

Otherwise Workflies makes no network calls. The local API has no login because it only answers your own computer; it also refuses requests from other websites in your browser.

Doctor & troubleshooting

wflies doctor (also Settings → Health check) checks that every file parses, references point at things that exist, the workflow is valid, guides match their gates, agent setup files are current, the index agrees with the files, and that no phone keys ended up inside a repository.

"not a Workflies project (no .wflies directory found)"

Run the command from the project's root folder, or run wflies init there.

The board does not open

Run wflies status. If nothing is running, wflies start; if it fails, it prints the last lines of agent.log. Another program on port 7333? Use wflies start --addr 127.0.0.1:7400.

My agent doesn't see Workflies tools

Re-run wflies init agent <runtime>, restart the agent, and check that wflies is on the PATH the agent uses.

A move is refused

The refusal lists each unmet rule with its fix. Fix them, or — as a person — override with a reason.

A merge left conflicts in .wflies/

Run wflies resolve. Any section edited on both sides is shown on the ticket for you to pick.

The board looks out of date

wflies index rebuild. The index is only a cache of the files.

macOS says the binary can't be opened

xattr -d com.apple.quarantine "$(command -v wflies)"

The phone can't connect

wflies mobile status on the computer. Away from home you need the relay or your own --remote-url. If the app asks you to update, see Update Workflies.

FAQ

Does Workflies send my tickets anywhere?

No. Tickets live in your repository and go wherever you push it. The optional phone relay only carries encrypted traffic it cannot read.

Do I need an account?

No. There are no accounts. Identity comes from git.

How much does it cost?

Workflies is free to use. Agents you connect are billed by their own providers; Workflies shows you that usage.

Can I use it without an AI agent?

Yes — it is a complete tracker for people. Agents are optional.

Can several people use one project?

Yes. Everyone clones the repository and runs wflies start; git keeps everyone in sync, and Workflies resolves the merges.

Can an agent skip my approval?

No. Agents cannot enter a human-gated status or override a rule — on any surface.

What happens to my data if I stop using Workflies?

Nothing. It stays in your repository as readable JSON and markdown.

Where do I follow news?

On Instagram at @workfliesapp, and in the release notes.