links-issue-tracker

README

links (lit)

An issue tracker that lives inside your git repo and is built for AI agents to drive.

links-issue-tracker — the CLI is lit — keeps your backlog in the repository, next to the code it describes. There's no server to run, no account to create, and no web app to keep in sync. Issues live in an embedded Dolt database, so every change to a ticket is a versioned, committed database mutation that travels with your code through the git remotes you already use.

It's designed so an autonomous coding agent can pull the next piece of work, claim it, finish it, and file follow-ups — coordinating with you and with other agents through one small, predictable CLI.

Why it's interesting

• The backlog ships with the code. Clone the repo, get the issues. No external service, no drift between "what the tracker says" and "what the branch contains."
• Every mutation is a commit. State is a Dolt database, so issue history is real, auditable version history — not an activity log bolted onto a SaaS.
• Built agent-first. Commands like lit ready, lit start, and lit done return guidance, not just data — the workflow an agent should follow is baked into the output.
• One write boundary, one identity per clone. All worktrees of a clone share one issue view (keyed off git rev-parse --git-common-dir). You never edit the database by hand.
• Minimal and deterministic. Inspired by beads, lit deliberately keeps a small surface area and prefers explicit errors over silent fallbacks.

Get started

Requirements

• A git repository (or worktree)

lit ships prebuilt, self-contained binaries — no Go toolchain and no system ICU/zstd needed to run them. The dolt CLI isn't required either; the Dolt storage engine is compiled in. (It's only a test oracle when developing lit itself.)

Install

Install the latest release onto your PATH (downloads the right binary for your OS/arch, checksum-verified):

curl -fsSL https://raw.githubusercontent.com/promptctl/links-issue-tracker/master/scripts/install.sh | bash -s -- --latest-release
lit version

Prefer to grab the archive yourself, pin a version, or build from source? See docs/introduction/installation.md — it covers manual download, --from-release <tag>, and the Go build (the fallback for unsupported platforms or hacking on lit).

A 60-second tour

From inside any git repository:

lit init                                              # set up the workspace for this clone
lit new --title "Build the landing page" \
        --topic landing --type task                   # file your first issue
lit ready                                             # see what's workable, in priority order
lit start <id>                                        # claim a ticket
lit done <id>                                         # finish it (a two-step confirm follows)

lit init also wires this repo for agents: it adds a short lit section to AGENTS.md and CLAUDE.md telling any coding agent to run lit quickstart before touching work.

Pointing an AI agent at it

If you want an agent (Claude Code, Cursor, etc.) to do the work, give it docs/agent-setup.md — a concrete, copy-pasteable install + workspace-init + core-loop guide written for agents. In a repo that's already initialized, the agent's entry point is simply lit quickstart, which prints the live command reference.

How it works

• Storage — issues are rows in an embedded Dolt SQL database under $(git rev-parse --git-common-dir)/links/. Each lit write validates input, updates rows in a transaction, and commits the working set, so local state is durable after every change.
• Sync — lit sync mirrors that Dolt data through your existing git remotes; remote config is derived from git remote -v, so there's nothing extra to configure.
• Automation — lit hooks install adds a shared pre-push hook (once per clone) that attempts a sync on push without ever blocking it.

More depth: docs/introduction/what-is-links.md · docs/concepts.md · docs/architecture.md.

Credit

links is directly inspired by beads by Steve Yegge. The core idea — treat issue tracking as part of the repository workflow so humans and agents coordinate through a fast local CLI and syncable state — is his. links is an independent implementation of that idea with a deliberately minimal, agent-native surface.

Contributing

See CONTRIBUTING.md for dev setup, the build/test/lint commands, and the branch & PR conventions.

Code of Conduct

This project follows the Code of Conduct.

Security

To report a vulnerability, see the Security Policy.

License

links is released under the MIT License.