Sea Lite

sea-lite

A work queue for parallel coding agents that can't collide.

Run three agents against one backlog and the failure mode is not that they are slow. It is that two of them pick up the same ticket, both "finish" it, and the one that finishes second overwrites the first. Or one of them dies holding a ticket and nobody else ever touches it.

sea-lite is a small MCP server where tickets are fenced:

• sea_next atomically picks the best eligible ticket and claims it. The caller gets a one-time claim token; every write (sea_update, sea_transition, sea_link) must present it. A write from anyone else is refused and says who holds the ticket and until when.
• Claims are leases (default 15 min, up to 1 h) that renew while the holder is active: every sea-lite tool call by the holder, and the sea-lite heartbeat a hook runs, push the expiry out again. An agent that dies stops renewing; the next reader sees the lapsed lease, treats the ticket as free, and records that it did. No sweeper, no cron.
• A claim can carry a scope: the paths the holder will edit. Two holders' live scopes may not overlap (scope_conflict names the holder, ticket, paths and expiry), and sea_scope_check lets an edit hook refuse a write inside someone else's scope. A holder is an actor label plus a session, so two Claude Code terminals that both run --actor claude are still two holders (see Identity). The numbers that motivated it: PR pairs from different agents conflicted 41.7% of the time, pairs from one agent 19.8% (arXiv 2607.04697) — agents could lock tickets but not each other's files.
• Enforcement outside the model: an edit hook for Claude Code, and a git pre-commit guard (sea-lite precommit --install) that refuses a commit staging files inside someone else's live claim, which works the same for Cursor, Codex, Copilot and humans.
• Tickets belong to the project (git repository) they were created in, so one shared store serves many repositories without one repo's queue or locks leaking into another.
• Tickets carry typed links (depends_on, blocks, parent_of, …). sea_next will not hand out a ticket whose predecessors are still open, and the precedence graph is kept acyclic on every write.
• sea_apply lays down up to 50 tickets and 100 links in one all-or-nothing write, so an epic with its children and dependency edges lands as a unit or not at all — and its links may point at tickets that already exist. Templates let the model write a 20-ticket chain once (for_each + {i} / {value} / {ref} / {prev}); the server expands it deterministically. The result is a ref → id map, not an echo.
• Lean on context: serve --core publishes the nine day-to-day tools in ~12 KB of tools/list (the full fifteen take ~32 KB; 0.4.0 took 59 KB), and results are compact JSON. sea_finish ends work on a ticket — an outcome (done / blocked / abandoned), a note, an optional commit sha, claim released — in one call, for one ticket or many.
• A claim can be bound to a git worktree; removing the worktree (sea-lite release-worktree, a WorktreeRemove hook) releases it.
• Every change is an event on a hash chain — the one kronicle-lite keeps. The same SQLite file holds both. sea_history shows a ticket's record and whether the chain still verifies; sea-lite rebuild replays the tables from the chain.

One process, one file, no accounts. Speaks MCP 2026-07-28 (per-request metadata, server/discover, cacheable tools/list, outputSchema + structuredContent on every tool, multi round-trip confirmation) and still serves 2025-era clients that open with initialize, over stdio and over HTTP — the same process answers both. Runs over stdio next to Claude Code, Cursor, Codex, Copilot, Claude Desktop or any MCP client, or over Streamable HTTP (serve --http, loopback, bearer tokens, one token per actor if you want attributable claims). sea_stats / sea-lite stats account for who held what for how long; sea-lite doctor checks the install. Several server processes (one per agent, or one shared) can point at the same file; SQLite's write lock and BEGIN IMMEDIATE make claims exclusive across processes.

Install

Requires Node ≥ 20. Data lives in ~/.kronicle-lite/kronicle-lite.db (or --data-dir, or $KRONICLE_LITE_DATA_DIR), shared with kronicle-lite if you run that too. One store serves every repository: tickets are keyed by project. The --actor label is what humans see on the board; you do not need a different label per terminal — each server process is its own session (see Identity).

Claude Code

claude mcp add sea-lite -- npx -y sea-lite serve --core --actor claude

--core serves the tools an agent uses day to day (see Profiles); drop it for all fifteen.

Each Claude Code session's server picks up CLAUDE_CODE_SESSION_ID and CLAUDE_PROJECT_DIR, so two sessions in one repo are two holders and their queue is that repo's. Copy skills/work-queue/ into .claude/skills/work-queue/ so the agent knows the claim → scope → work → release loop, wire the edit hook from hooks/README.md (or install the cc-anchor plugin, which ships it) so an Edit/Write inside someone else's scope is blocked before it happens, and add the git guard:

npx sea-lite precommit --install     # .git/hooks/pre-commit

Heartbeat. sea-lite renews a holder's leases on every sea-lite tool call it makes, which covers an agent that keeps using the queue. A long stretch of plain edits and test runs makes no sea-lite call, so also wire a PostToolUse heartbeat: cc-anchor's heartbeat hook is the recommended one (it renews your claims as you work, rate-limited, in the background), or sea-lite heartbeat --hook from hooks/README.md. Measured (agent-memory-bench S13, lease 5 s, task 12 s): without a hook the lease lapses mid-task and the holder learns it only at its next fenced write; with cc-anchor's heartbeat the claim held 3/3.

Cursor

.cursor/mcp.json in the project (or ~/.cursor/mcp.json for everywhere):

{

"mcpServers": { "sea-lite": { "type": "stdio", "command": "npx", "args": ["-y", "sea-lite", "serve", "--actor", "cursor"], "env": { "KRONICLE_LITE_DATA_DIR": "${userHome}/.kronicle-lite" } } } }

Cursor asks before running MCP tools unless you allowlist them; the read-only ones (sea_get, sea_list, sea_history, sea_scope_check, sea_stats) are safe to allow. Put skills/work-queue/SKILL.md into a project rule so the agent claims its paths before editing.

Codex (CLI, IDE extension, app)

~/.codex/config.toml (or .codex/config.toml in a trusted project):

[mcp_servers.sea_lite]

command = "npx" args = ["-y", "sea-lite", "serve", "--actor", "codex"] env_vars = ["KRONICLE_LITE_DATA_DIR"] startup_timeout_sec = 20 default_tools_approval_mode = "writes" # prompt only on write tools

[mcp_servers.sea_lite.tools.sea_transition] approval_mode = "prompt" # terminal states are irreversible

[mcp_servers.sea_lite.tools.sea_finish] approval_mode = "prompt" # closes tickets (terminal, no exit)

Codex reads the server instructions; the loop is in them.

GitHub Copilot coding agent

Repository Settings → Copilot → MCP servers, "MCP configuration". The coding agent runs in a fresh Actions sandbox, so point it at a store the run can reach, and allowlist tools explicitly: GitHub recommends read-only tools, and Copilot code review only loads tools whose annotations.readOnlyHint is true. Ours that qualify: `sea_get`, `sea_list`, `sea_history`, `sea_scope_check`, `sea_stats`.

{

"mcpServers": { "sea-lite": { "type": "local", "command": "npx", "args": ["-y", "sea-lite", "serve", "--actor", "copilot", "--data-dir", "/tmp/sea-lite"], "env": { "SEA_LITE_ROLE": "agent" }, "tools": ["sea_get", "sea_list", "sea_history", "sea_scope_check", "sea_stats"] } } }

Once a server is configured Copilot calls its tools without asking, so add the write tools (sea_create, sea_apply, sea_claim, sea_next, sea_update, sea_transition, sea_finish, sea_link, sea_refresh, sea_release) only if you want the agent taking and closing tickets on its own. Secrets and variables for the env block must be named COPILOT_MCP_*.

Any other client

{ "mcpServers": { "sea-lite": { "command": "npx", "args": ["-y", "sea-lite", "serve", "--actor", "me"] } } }

A 2026-07-28 client probes with server/discover; a 2025 client sends initialize; both are served.

Over HTTP (serve --http)

For a client that cannot spawn a process, or several agents sharing one queue server:

npx sea-lite serve --http --actor owner          # http://127.0.0.1:7418/mcp

npx sea-lite add-token --actor agent-a # prints a token once; stores its sha256 npx sea-lite add-token --actor agent-b

{ "mcpServers": { "sea-lite": { "type": "http", "url": "http://127.0.0.1:7418/mcp",

"headers": { "Authorization": "Bearer " } } } }

• Identity per request. The shared bearer acts as --actor (role --role), and a per-call actor_id is a self-asserted label, as on stdio. An actor token acts as *its* actor (and its entry's role); an actor_id naming anyone else is refused with forbidden. So claims, notes, chain events and sea_stats are attributable per token.
• Both protocol eras, stateless. POST to one endpoint; no session id; GET/DELETE → 405. 2026-07-28 clients send per-request _meta; 2025-era clients (Cursor today) open with initialize and are served by the SDK's stateless legacy fallback from the same tools and the same per-request identity. --legacy reject makes the endpoint modern-only (initialize → 400 / -32022). Missing or wrong bearer → 401; foreign Origin or Host → 403.
• Projects. A team server sees every project unless started with --project KEY (scopes are repo-relative, so run one server per repository or name it).
• One trust domain. Every token reaches the whole store; there are no per-ticket permissions, no read isolation, no TLS. Off-box, put TLS in front. Read docs/THREAT-MODEL.md → "HTTP transport" before exposing it.

Sixty-second tour

No MCP client and no LLM needed: the CLI drives the same queue the agents use. Every line below is run by the test suite against a fresh store.

npm i -g sea-lite                            # or: alias sea-lite='npx -y sea-lite'

export KRONICLE_LITE_DATA_DIR=$(mktemp -d) # a scratch store cd "$(mktemp -d)" && git init -q # any repository: tickets belong to it

sea-lite create "Add rate limiting to login" --triaged

sea-lite