Local-First Kanban for Teams: How Shared-Folder Collaboration Works
The most common objection to a local-first kanban board is that it cannot work for a team. The usual phrasing is that there are no team features built in, that collaboration happens through a shared folder rather than through invites, and that two people editing at once are therefore at the mercy of whatever Dropbox or iCloud decides to do.
The first two are true and are design choices. The third is not true, and it is the part worth reading carefully, because it is the part that decides whether a folder-based board is safe to put in front of more than one person.
This guide explains how team use actually works when the board is a folder of Markdown files, what the software does when two writers collide, and where the honest limits are.
The shape of the problem
A cloud kanban tool has one copy of the data and many clients. The server is the referee. It holds the accounts, the permissions and the write order, and every client is a view onto its state.
A local-first kanban board inverts that. There is no server and no referee. Each machine holds a real copy of the project on disk, and a file-sync service moves bytes between them. Kanban Pro stores every ticket as a single Markdown file with YAML frontmatter in a folder you choose, so a project is an ordinary directory that any sync tool can carry: iCloud Drive, Dropbox, Google Drive, OneDrive, a Synology share, or a Git repository.
That buys three things a server cannot. The board works with no network. Nobody operates a service that could read your project. And there are no seats, so adding a fifth person or a fifth AI agent costs nothing, because Kanban Pro is free and has no account to create.
It also creates one real engineering problem: with no referee, two writers can reach the same ticket at the same time. Everything below is about that problem.
Why one file per ticket changes the collision maths
In a database-backed tool the whole board is one shared object. In a file-based board the unit of storage is a single ticket.
That is not a cosmetic difference. Two people working on different tickets are writing to different files, so their edits cannot conflict at all. There is no shared row, no shared document, no shared index to serialise against. Sync moves two unrelated files and both land. The overwhelming majority of real team activity falls into this case, which is why the file-per-ticket layout does most of the collaboration work before any conflict logic runs.
The interesting case is the remaining one: two writers on the same ticket.
What happens when two writers hit the same ticket
Every write in Kanban Pro walks the same three layers, whether it comes from the app window, from an embedded terminal running an agentic CLI, or from an agent editing the file directly.
| Layer | What it is | Which collision it catches |
|---|---|---|
| In-process queue | A per-ticket mutex inside the app | Two edits saved milliseconds apart in the same window |
| Cross-process lock | A lockfile held for the duration of the write, with retries | Another process or an external editor such as VS Code or vim writing the same file |
| Content-hash check | The file's hash is compared against the baseline the writer loaded from | The file changed on disk between load and save, which is the definition of a concurrent edit |
The third layer is the one that answers the objection. A writer does not simply overwrite the file it loaded. It checks that the file on disk is still the file it read. If the bytes moved underneath it, the save does not proceed as if nothing happened.
The rule the system holds to is that exactly one writer wins and the loser's work is never silently dropped. The losing version is written to disk as a conflict record, the ticket raises a banner in the app, and the change is logged. Opening the banner gives a resolver with both versions side by side, labelled local and incoming, and three choices: keep local, keep remote, or save a merged version you edit yourself. Resolving archives the conflict rather than deleting it.
This matters because the failure mode people fear from shared folders is the silent one. A conflicted copy appearing in a folder with a filename nobody reads is how work disappears. Surfacing the conflict in the app, on the ticket it belongs to, is the difference between a sync artefact and a decision.
Seeing each other before the collision happens
Detection after the fact is the safety net. Two mechanisms try to stop the collision earlier.
Ticket locks. Opening a ticket's detail view writes a small lock file into the project's .kanban/locks/ directory. Other machines pick it up through the file watcher and show an "In Use" badge on the card. Clicking a locked card warns you first and offers to open it read-only instead. Locks are stored as separate files rather than as a field on the ticket, so signalling "someone is in here" never rewrites the ticket itself and never competes with a real content edit. Locks older than sixty minutes are treated as stale and cleaned up, so a laptop that closed mid-edit does not leave a ticket blocked forever.
Editor leases and heartbeats. Across machines, the ticket editor takes a lease and the holding machine emits a heartbeat. Another machine trying to edit the same ticket sees who holds it and since when, and can either wait or force a takeover after an explicit confirmation that names the machine and warns that unsaved edits there may be lost. A lease whose heartbeat has gone quiet is flagged as stale rather than treated as live.
Neither is a presence cursor. Both are bounded by how fast your sync provider propagates a small file, which is seconds rather than milliseconds. What they give you is the thing that actually prevents lost work in a small team: knowing, before you start typing, that someone else is already in this ticket.
Attribution, which is the other half of teamwork
Knowing who changed what is not a nice-to-have on a shared board. Kanban Pro tracks it in the files themselves rather than in a service.
Every ticket carries modified and modifiedBy in its frontmatter, and the convention is explicit that an AI agent writes its own identifier there rather than borrowing the human's profile name. The activity log turns that into a readable history, and because it is derived from files on disk it survives the app, the machine and the sync provider. Comments with reactions and local profiles sit on top of the same data.
Members are first-class too. A project can carry a team of humans and agents defined as files under .kanban/team/, with personas, mandates and reporting lines, rendered in the app as an organogram you can rearrange by dragging. An agent member can be given a runtime and opened in an embedded terminal on a ticket, and its sessions are listed against it. This is the sense in which "team" includes the agents: they are members with names and mandates, not anonymous processes, and their edits are attributed like anyone else's.
What shared folders genuinely cannot do
Being straight about the limits is more useful than arguing the objection away, and some of the objection is correct.
- No accounts, so no server-side permissions. There is no way to grant one person read-only access to a board and another person write access. Access control is whatever your file-sharing service enforces on the folder. If you need per-user permissions inside the board, this architecture cannot give them to you.
- No real-time presence or live cursors. You will not watch someone else's card move as they drag it. Changes arrive when the sync provider delivers the file, typically within seconds.
- Sync speed is not ours. iCloud, Dropbox and the rest set the latency, and a folder that is not fully downloaded on a machine behaves differently from one that is.
- No audit-grade access logging. The activity log records what changed and who claimed the change. It is not an access-control audit trail, and a person who can read the folder can read everything in it.
- Scale. This design suits small trust-based teams sharing a folder. An organisation that needs onboarding flows, role hierarchies enforced by software, and central administration over hundreds of people is describing a server, and should buy one.
- The Team view is off by default. It is a first-class view but hidden on a fresh install, so a new user has to switch it on in Settings before the organogram appears.
The honest summary is that a folder-based board replaces a permissions system with trust, and replaces real-time presence with fast-enough signalling and a conflict resolver. For a team that already shares a folder and already trusts each other, that trade is usually a good one. For a team that needs software to enforce who may do what, it is the wrong tool and no amount of conflict handling fixes that.
Choosing between the two shapes
Ask which of these you are actually protecting against.
If your risk is a person seeing something they should not, you need enforced permissions and you need a server. If your risk is losing work when two people edit at once, a file-per-ticket board with content-hash checking and a conflict resolver addresses it directly, and does so without anyone else holding your data. If your risk is the vendor changing the terms, going away, or reading your projects, the folder wins outright, because plain Markdown and YAML in a directory you chose stays readable whatever happens to the software that wrote it.
Most small teams discover their real answer is the second and third. Most large organisations discover it is the first.
Frequently Asked Questions
Can two people use the same Kanban Pro board at the same time?
Yes. Put the project folder in a shared location such as iCloud Drive, Dropbox, Google Drive, OneDrive or a Git repository, and each person opens it from their own machine. Because every ticket is a separate Markdown file, two people working on different tickets never touch the same file and their changes both land. On the same ticket, the app takes an editor lease, shows the other machine an "In Use" badge, and falls back to a conflict resolver if both writes go through anyway.
Does Kanban Pro have team features, or only shared folders?
Both, but not the ones a cloud tool means by the phrase. There are no accounts, no invites and no server-side permissions, and that is deliberate. There is a members system with humans and AI agents as first-class entities carrying personas, mandates and reporting lines, an organogram view for the reporting structure, per-change attribution through modifiedBy, an activity log, comments with reactions, ticket locks with an "In Use" indicator, cross-machine editor leases with heartbeats, and a conflict resolver. What is missing is the administrative layer: nothing in the app can stop a person who has the folder from reading or editing any ticket in it.
What happens if two people edit the same ticket at once?
The second writer's save is checked against the file on disk before it is applied. If the file changed after that writer loaded it, the save is not allowed to overwrite blindly. One version wins, the other is preserved as a conflict record, and the ticket shows an "unresolved conflict" banner. Opening it gives both versions side by side with three options: keep local, keep remote, or save a version you merge by hand. Nothing is discarded without someone choosing it.
Is a shared folder safe for a kanban board, or will it corrupt files?
The risk with naive shared-folder apps is that the sync engine resolves a collision by producing a "conflicted copy" file that nobody notices. Kanban Pro guards against that with three layers: a per-ticket queue inside the app, a lockfile that keeps other processes and external editors out during a write, and a content-hash comparison that refuses to overwrite a file that moved underneath the writer. Per-machine state such as session data and caches is excluded from sync so it never replicates between devices in the first place.
How much does Kanban Pro cost for a team?
Nothing. Kanban Pro is free at US$0.00 with no subscription, no one-time purchase and no account. There is no per-seat pricing because there are no seats, so a team of two and a team of ten cost the same, and adding AI agents as members costs nothing either.
Can humans and AI agents work on the same board?
Yes, and it is the case the file-per-ticket design handles best. Agents are added as members with a name, a persona and a mandate, and can be launched in an embedded terminal scoped to a ticket, running agentic CLIs such as Claude Code or OpenAI Codex. Agent writes go through the same three-layer save pipeline as human writes, and agents are expected to set their own modifiedBy identifier so the activity log distinguishes their changes from a person's.
Do we need to be online for the board to work?
No. The board is a folder on your disk, so it works fully offline, including creating tickets, editing, searching and running an agent in an embedded terminal. Sync is a separate concern handled by your file-sync provider, and changes propagate whenever the machine reconnects.
How does this compare to self-hosting a kanban server?
Self-hosting gives you accounts, permissions and real-time state, at the cost of running a server, backing it up, patching it and holding the data in a database. A folder-based board gives you no server to run and a format you can read without any software, at the cost of having no enforced permissions. If your reason for self-hosting was to keep data off someone else's infrastructure rather than to enforce access control, the folder reaches that goal with considerably less to maintain.