🗂️ Loci

Local-first harness and ticket operations. Run it in any project, track work with your AI assistant via CLI or MCP.

Why Loci?

Loci is a lightweight local-first harness system that runs entirely on your machine. Your AI coding assistant (Claude, Gemini, Cursor, etc.) can read and update workflow tickets directly via loci CLI or MCP.

Install

Recommended one-line install (macOS Apple Silicon + Linux x86_64/aarch64):

curl -fsSL https://raw.githubusercontent.com/thienhm/loci/main/scripts/install.sh | bash

Install a specific version:

curl -fsSL https://raw.githubusercontent.com/thienhm/loci/main/scripts/install.sh | bash -s -- v2.0.1

Transition bootstrap (legacy Bun launcher):

bun install -g github:thienhm/loci
loci update

During the transition, loci update refreshes both the managed Rust binary and the global Bun package that still provides loci serve and loci open.

Managed binary location: ~/.loci/bin/loci

What's New In 2.0.1

Loci 2.0.1 is a patch release for the Rust-primary 2.0 line:

• loci update now refreshes both the managed Rust binary and the global Bun wrapper used by loci serve and loci open.
• Dashboard reads now recover from local SQLite open edge cases and keep healthy registered projects visible.
• Ticket creation no longer reports a hard failure when only the post-create registry summary refresh fails.
• CLI help and release documentation now describe the loci update / loci upgrade boundary more clearly.

Quick Start

# In your project directory
loci init

# Optional: start the server + web UI
loci serve

# Optional: open the web UI in your browser
loci open

The web UI is available at http://localhost:3333 by default.

Connect Your AI Assistant

CLI (Recommended)

Use the local CLI directly in your agent workflow. loci init generates project instructions and foundation docs:

• AGENTS.md
• LOCI.md
• loci/project.md
• loci/architecture.md
• loci/validation.md
• loci/guardrails.md
• loci/current-state.md
• loci/glossary.md
• loci/backlog.md

MCP

Loci also exposes an MCP server at http://localhost:3333/mcp (requires loci serve to be running).

Claude Desktop / Claude Code

{
  "mcpServers": {
    "loci": {
      "url": "http://localhost:3333/mcp"
    }
  }
}

Gemini CLI (~/.gemini/settings.json)

{
  "mcpServers": {
    "loci": {
      "url": "http://localhost:3333/mcp"
    }
  }
}

Cursor / Windsurf

{
  "loci": {
    "url": "http://localhost:3333/mcp"
  }
}

CLI Reference

Project

Command	Description
loci init	Initialize Loci in the current project
loci doctor	Check harness/project health
loci serve	Start the MCP server and web UI
loci open	Open the web UI in your browser
loci update	Update the managed Rust binary and transitional Bun wrapper
loci upgrade	Upgrade project templates/data

Tickets

Command	Description
loci list [--json]	List workflow tickets
loci add "title" [--json]	Create a workflow ticket
loci get <id> [--json]	Get one ticket by ID
loci status <id> <status> [--json]	Update ticket status
loci patch <id> [--assignee] [--progress] [--priority] [--labels] [--json]	Update ticket fields
loci plan, loci ready, loci validate, loci evidence, loci trace, loci summary, loci review	Harness workflow commands

Docs & Attachments

Command	Description
loci doc read <id> <filename> [--json]	Read a ticket document
loci doc write <id> <filename> --content "..."	Write a ticket document
loci attachments <id> [--json]	List attachments for a ticket

How It Works

• Project docs live under loci/ (human/agent-visible context and workflow packets)
• Operational state lives under .loci/ (SQLite + local tool state)
• The CLI is local-first and does not require a running server for core workflows
• The MCP server and web UI are served by loci serve

Updating

loci update

This installs the managed Rust binary and refreshes the global Bun loci package so TypeScript fallback commands such as loci serve use the latest server/web code. If the wrapper refresh fails, the command prints the manual recovery command:

bun remove -g loci && bun install -g github:thienhm/loci

If you're on an older install and loci update cannot run yet, bootstrap once manually:

bun remove -g loci && bun install -g github:thienhm/loci

Then run:

loci update

Migration Notes

• loci sync has been retired. Use loci upgrade.
• loci skill has been retired from product CLI.

Contributing

See CONTRIBUTING.md.

License

MIT — see LICENSE.