Reference

Documentation

CLI commands, MCP tools, hooks, and configuration — generated from the same source code that powers the tools.

CLI

Commands

Install globally with npm i -g preclaim, then run any command below.

init

Full setup — auth, project creation/join, and automatic agent detection + configuration

preclaim init
Options
--backend <url>Backend URL (default: https://preclaim.dev)
--project-id <id>Project ID (skip onboarding)
$ preclaim init
login

Authenticate with Preclaim

preclaim login
$ preclaim login
lock

Lock a file

preclaim lock <file>
Options
-s, --session <id>Session ID
-t, --ttl <minutes>Lock TTL in minutes
$ preclaim lock src/api/auth.ts --ttl 30
unlock

Release a file lock

preclaim unlock [file]
Options
-s, --session <id>Session ID
-a, --allRelease all locks for this session
-f, --forceForce-release locks held by any session
$ preclaim unlock src/api/auth.ts --force
status

Show active locks for this project

preclaim status
$ preclaim status
check

Check lock status for files

preclaim check <files...>
$ preclaim check src/api/auth.ts src/lib/db.ts
whoami

Show current user info

preclaim whoami
$ preclaim whoami
config

View or modify project configuration

preclaim config
Options
--get <key>Get a config value
--set <key=value>Set a config value
$ preclaim config --set ttl=30
sessions

Show active sessions for this project

preclaim sessions
$ preclaim sessions
logs

Show recent lock activity for this project

preclaim logs
$ preclaim logs
install-hooks

Install Claude Code hooks in the current project

preclaim install-hooks
$ preclaim install-hooks
open

Open the Preclaim dashboard in your browser

preclaim open
$ preclaim open
info

Show project ID, backend URL, dashboard URL, config, and version

preclaim info
$ preclaim info
doctor

Run health checks: backend, credentials, hooks, heartbeat daemon

preclaim doctor
$ preclaim doctor
upgrade

Update Preclaim CLI to the latest version

preclaim upgrade
$ preclaim upgrade

MCP Server

Tools

Add preclaim-mcp as an MCP server in any compatible agent. These tools are exposed automatically.

preclaim_lock

Lock a file before editing it. Call this BEFORE writing to any file to prevent conflicts with other AI sessions. Returns whether the lock was acquired or if another session holds it.

Arguments
file_pathstringPath to the file to lock (relative or absolute)
ttl_minutesnumberoptionalLock duration in minutes (default: from project config)
preclaim_unlock

Release a lock on a file, or all locks for this session. Call this after committing changes.

Arguments
file_pathstringoptionalSpecific file to unlock. Omit to release all locks.
preclaim_check

Check lock status of one or more files without acquiring locks. Use this to see if files are available before editing.

Arguments
file_pathsstring[]Files to check (1-100 paths)
preclaim_status

List all active locks and sessions for this project. Shows who is working on what.

preclaim_read

Signal that you are reading a file. This lets other sessions know you are looking at this file (soft signal, 60s TTL). Call this when reading files to improve coordination.

Arguments
file_pathstringPath to the file being read

Claude Code

Hook Setup

Run preclaim install-hooks to auto-configure these in .claude/settings.json.

PreToolUseBefore every tool call

The gatekeeper. Intercepts Edit/Write/MultiEdit to acquire file locks before changes, and Read to register soft signals. Discovers config from both the working directory and the file's directory — so locks work even when the session starts from a parent directory. Allows the tool to proceed if the lock is acquired, blocks with a warning if another session holds the lock.

PostToolUseAfter every tool call

Commit detector. Watches for git commit commands and automatically releases all session locks when a commit is detected.

SessionStartWhen a Claude Code session starts

Registers the session with Preclaim, starts the heartbeat daemon for automatic lock expiry, and injects a system message with current lock status. Warns authenticated users when no .preclaim.json is found in the current directory.

StopWhen a Claude Code session ends

No-op by design. Cleanup is handled by the activity-aware heartbeat daemon (locks expire when idle), server-side pg_cron cleanup, and daemon self-exit after inactivity.

Config

.preclaim.json

Created by preclaim init. Modify with preclaim config --set key=value.

KeyDescription
backendURL of the Preclaim backend API (default: https://preclaim.dev)
projectIdYour Preclaim project ID (set during init)
ttlDefault lock TTL in minutes (default: 30)
failOpenAllow tool use when Preclaim is unreachable (default: true)
ignoreGlob patterns for files to never lock (e.g. *.md, dist/**) (default: [])
idleTimeoutMinutesMinutes of inactivity before the heartbeat daemon releases locks