Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/virsanghavi/axis/llms.txt

Use this file to discover all available pages before exploring further.

list_locks gives you a real-time snapshot of every file currently locked on the project. For each lock it tells you who holds the file, what they are doing with it, when they took the lock, and when it auto-expires. This makes it the primary tool for collision avoidance at session start and for diagnosing stale locks that need force_unlock.
Call list_locks together with list_jobs at the start of each session to get a complete picture of what’s in progress before claiming work.

​
Parameters

​
projectName
string
The Axis project to query. Defaults to the auto-detected project name derived from the nearest .git or package.json, or from a committed .axis/axis.json. In a multi-repo org, pass projectName explicitly to query a specific project.

​
Return value

An array of lock objects. An empty array means no files are currently locked on the project.
FieldTypeDescription
filePathstringPath of the locked file, normalized relative to the repo root.
agentIdstringThe agent currently holding the lock.
intentstringWhat the agent stated it will do with the file when it called propose_file_access.
acquiredAtstringISO 8601 timestamp when the lock was granted.
expiresAtstringISO 8601 timestamp when the lock auto-expires (30 minutes from grant).
contentHashstringSHA-256 fingerprint of the file’s content at the moment the lock was granted. Used by verify_file_lock and guarded_write for tamper detection.

​
Example output

[
  {
    "filePath": "src/auth.ts",
    "agentId": "dana-claude-code",
    "intent": "refactor auth to issue JWTs instead of session cookies",
    "acquiredAt": "2025-01-15T14:30:00Z",
    "expiresAt": "2025-01-15T15:00:00Z"
  },
  {
    "filePath": "src/session.ts",
    "agentId": "sam-cursor",
    "intent": "migrate session store to Redis",
    "acquiredAt": "2025-01-15T14:45:00Z",
    "expiresAt": "2025-01-15T15:15:00Z"
  }
]
contentHash is present when the lock was granted via the local stdio server or a Supabase-backed project. Locks without a stored hash return the field as undefined; verify_file_lock reports UNKNOWN for those.

​
When to call list_locks

On session start

Synchronize before starting work. Knowing which files are locked tells you which jobs are safe to claim without immediately hitting a REQUIRES_ORCHESTRATION on the first edit.

Before attempting an edit

Check who holds a file before calling propose_file_access. If it’s locked you can read the intent and decide whether to wait, pick a different file, or coordinate via update_shared_context.

After a long wait or interruption

Assumptions go stale. If your session paused, another agent may have locked or released files since you last looked. Refresh before editing.

​
Reading lock age

The difference between acquiredAt and now tells you how long the lock has been held. Axis auto-expires locks after 30 minutes, so a lock approaching or past its expiresAt time is a signal that the holder may have crashed. 
acquiredAt:  2025-01-15T14:30:00Z
expiresAt:   2025-01-15T15:00:00Z   (30 min window)
now:         2025-01-15T14:58:00Z   → 2 minutes until auto-expiry

→ Wait for expiry rather than force-unlocking.
If a lock is older than 25 minutes and the holding agent is clearly not responding, see force_unlock for the admin override.

​
Relationship to other tools

ToolHow list_locks helps
propose_file_accessCheck list_locks first to see if a file is locked before requesting it, so you can plan around conflicts before hitting REQUIRES_ORCHESTRATION.
force_unlocklist_locks gives you the agentId and acquiredAt needed to determine whether a lock qualifies for force-unlock (age > 25 min, agent clearly crashed).
list_jobsPair list_locks with list_jobs — jobs tell you what is planned; locks tell you what is actively being written right now.

Build docs developers (and LLMs) love

Get started for freeTalk to us