[FEATURE]: File locks / Vim-style locks for OpenCode locks

[wojons]

Feature hasn't been suggested before.

• I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

Feature request: File locks / Vim-style locks for OpenCode

Summary

Add support for file locking in sst/opencode, ideally with Vim-style behavior (lock/swap files), so that:

• Multiple OpenCode clients and/or agents don’t stomp on each other’s changes
• We have a foundation for safe concurrent agents working against the same workspace

---

Motivation

Right now, multiple editors/agents interacting with the same repo can easily end up overwriting each other’s changes, especially when:

• Running multiple agents/tools in parallel that all use OpenCode
• Using OpenCode alongside a human editor
• Running long-lived operations (refactors, codegen, formatting) that touch many files

Vim-style file locks (or equivalent) would allow OpenCode to:

• Detect when a file is already “owned” by another process/session
• Warn or prevent conflicting edits
• Provide a basis for coordinating multiple agents that operate concurrently

This is particularly useful for building multi-agent workflows on top of sst/opencode, where several agents may read/write the same files in overlapping time windows.

---

Proposed behavior (high-level)

I’m not attached to any specific API – this is more about desired semantics. A few ideas:

1. Advisory file locks

• opencode (or underlying file layer) exposes an API to:
  • Acquire a lock for a given path: lock(path, options)
  • Release a lock: unlock(path)
  • Optionally check lock status: isLocked(path) or similar
• Locks are per-file (and maybe optionally per-directory / glob)
• If a lock is held:
  • Other writers either fail fast with a clear error, or
  • Block until the lock is released (configurable)

2. Vim-like UX semantics

Vim-style semantics could look like:

• When a file is opened for editing, a lock/marker is created, e.g.:
  • .filename.lock or .filename.swp
• If another OpenCode session tries to open the same file:
  • It receives a “file is already locked” signal
  • It can decide whether to:
    • Open read-only
    • Take over the lock (force)
    • Abort

This doesn’t have to be literally Vim’s format, just the same idea: a simple, visible, file-based lock mechanism that plays nicely in a shared workspace.

3. Concurrency support for agents

With locks in place, higher-level orchestration could:

• Assign different files / directories to different agents safely
• Use lock acquisition failure as a signal to back off or reschedule work
• Run multiple agents in parallel without worrying about silent overwrites

Example desired flow for agents:

1. Agent A wants to edit src/foo.ts → acquire lock.
2. While Agent A holds the lock:
   • Agent B attempting to edit src/foo.ts either:
     • Fails with a structured “locked” error, or
     • Waits up to a configurable timeout
3. On success or failure, agents can coordinate based on lock state.

---

API ideas (sketch)

One possible direction (purely illustrative):

// Advisory lock
const lock = await opencode.lockFile("src/foo.ts", {
  mode: "exclusive",   // "exclusive" | "shared"
  wait: true,
  timeoutMs: 5000,
});

// Use the file safely here...

await lock.release();   // or opencode.unlockFile("src/foo.ts");

[github-actions]

This issue might be a duplicate of existing issues. Please check:

• Concurrent sessions working on different repos interfer each other #4251: Discusses concurrent sessions working on different repos that interfere with each other, which is the core problem file locks would solve
• Concurrency bug: Polaris edit session blocked by self-induced file change #4079: Reports concurrency bugs with file modification detection during concurrent edits
• Idea: use Turso/ZeroMQ/WebSockets for shared event bus, synchronize multiple opencode TUIs and servers #2783: Proposes synchronization solutions for multiple OpenCode processes using event buses

Feel free to ignore if none of these address your specific case.

[rekram1-node]

Yeah i see where ur coming from.

Rn I just use worktrees which is a bulkier solution for sure.

Also related to this is working on code while agent is working on code (like me doing stuff manually) and how we make that interaction potentially better if changed at all.

[wojons]

Correct i run into this often where i and the LLM are in or editing the same file and it just becomes a mess. I used worktrees also as my work around but would be better to have something with better flow

[ShibuyaCyana]

Why was this closed? I see PR #13261, but that addresses async agents, not async file editing. With the implementation of true async agents, this feature becomes even more urgent.