loci

<p align="center"> <img src="packages/web/src/assets/logo.svg" alt="Loci Logo" width="128" /> </p>

🗂️ 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.