Pearls

Git-native issue tracking for the age of agentic development.

Pearls is a fast, local-first issue tracker that lives in your repo, speaks in structured data, and behaves like a serious engineering tool. No cloud lock-in. No daemon circus. No mystery state.

v0.4.0 upgrade note

This release adds recoverable atomic task updates and an embeddable Rust graph service. It also changes prl ready to show only unblocked Open tasks and makes the post-merge hook reject missing dependency endpoints. See the changelog for the full list.

Back up the complete .pearls directory before upgrading, and do not run older Pearls writers alongside v0.4.0. Repositories from v0.3.8 without transaction metadata are initialized automatically on the first v0.4.0 read; task files are preserved. If a repository reports schema version 1 transaction metadata, run prl init to upgrade it, or prl doctor --fix if its task data also needs repair. See the upgrade and rollback guide for recovery details.

Why Pearls

• Local-first: task records live with your code in .pearls/issues.jsonl and .pearls/archive.jsonl
• Agent-ready: strict schema, dependency graph, finite-state transitions
• Git-native: merge driver + hooks for real workflows
• Single binary: prl is all users need in their PATH
• Small: example macOS release binary is ~10MB (Beads bd is ~31MB on the same platform; sizes vary by target and build flags)
• Rust-fast: optimized for tight human and agent feedback loops

If markdown TODOs feel too fuzzy and SaaS trackers feel too heavy, Pearls is the middle path that actually scales.

Install

Fastest install:

cargo install --git https://github.com/mrorigo/pearls pearls-cli

Install from local checkout:

cargo install --path /path/to/pearls/crates/pearls-cli

Ensure prl is on PATH so Git hooks and merge drivers can invoke it.

60-Second Start

git init
prl init

prl create "Ship launch page" --priority 1 --label marketing,web
prl create "Wire merge driver docs" --priority 2 --label docs

prl list --status open --sort updated_at
prl ready

MCP Mode

Run the MCP stdio server for agent clients:

prl mcp --repo .

Core Commands

• prl init: initialize .pearls, hooks, and Git merge integration
• prl create, prl update, prl close: lifecycle operations
• prl list, prl show, prl ready: discovery and execution flow
• prl mcp: MCP stdio server for agent tooling
• prl link, prl unlink: dependency management
• prl comments: add, list, and delete issue comments
• prl meta: structured per-issue metadata
• prl doctor: integrity checks and optional repairs
• prl compact: archive old closed issues
• prl sync: Git sync workflow helper
• prl hooks: run hook actions directly
• prl merge: merge-driver entrypoint for JSONL conflicts

Documentation

• User guide: docs/USER-GUIDE.md
• Embedded Rust API: Graph service
• Whitepaper: docs/WHITEPAPER.md
• Deep architecture: docs/PEARLS.md
• End-to-end sample: examples/WORKFLOW.md

Agent Skill

There is an agent skill defined for using the CLI, see skills/pearls-cli.

Do not give your agent both the CLI skill and the MCP server, or the agent might get confused!

Project Layout

This workspace ships six crates:

• crates/pearls-core: models, storage, graph, FSM, identity
• crates/pearls-cli: prl command-line application
• crates/pearls-app: shared application services
• crates/pearls-mcp: MCP stdio server implementation
• crates/pearls-merge: semantic JSONL merge engine
• crates/pearls-hooks: pre-commit and post-merge validations

Build and Test

cargo check
cargo fmt
cargo clippy -- -D warnings
cargo test

Engineering Standards

Pearls follows the Microsoft Pragmatic Rust Guidelines. See AGENTS.md for repository-specific coding standards.

License

MIT