Epiq is a self-hosted issue tracker that allows you to review workflows in real time or after the fact via replay. It persists state as an immutable event log, versioned and synchronized via Git.
Most issue trackers live outside your workflow. Instead of a centralized, managed service, Epiq offers issue tracking as an integrated part of the development environment offering workflow replay and inline code-diffs, tackling the review bottleneck with time-travel, filtering, and a tight code integration.
All state is kept local, Git-backed, and versioned.
Agents now run whole sprints unattended. Because state is an event log, you can replay the board to find out what moved when, who moved it, and what changed along the way.
Prefix a commit's subject with the ticket's ref to link the two:
git commit -m "1YRTG8T ...<some message>"
Linking makes a commit show up in the ticket code-diff tab. You can comment on selected lines, and also file a new ticket straight from the selection. The MCP exploses this reference as a ref property agents can refer to.
Preserve the linking post-merge via conventions:
- Rebase-merge It is advised to rebase-merge so the ref-prefixed commits land on
mainas they are, preserving linking post-merge. - Squashing within one ticket's commits is fine as long as the result keeps the prefix. Do not squash commits carrying different refs into one.
A board can read commits from other repositories too — handy when the board lives in a repo of its own. Connect one from the GUI (the Repos section of the settings panel behind the gear, or Connect repo in the palette), the TUI (:config repoConnect <url>, :config repoDisconnect <name>) or the MCP (epiq_repo_connect, epiq_repo_disconnect).
Connecting is a board-wide action: every contributor's epiq downloads the repo on their next sync. So it takes two steps. The first clones the repo into a staging area and shows what it is and what it costs — its size, host, default branch and latest commit, and how many of its commits name tickets on this board (none suggests the wrong repo) — and writes nothing. Only a confirm connects it: the TUI takes the same line again with confirm, the MCP a second call with confirm: true. Options of a connected repo change at once. branches is default (the default) or all; since is how much history to clone: board (since the board was created, the default), all, or a date; label is what the repo is called on the board — its URL's basename unless set, which is how a fork and its upstream are told apart.
The list is part of the board: connecting, changing and disconnecting are board events, so they sync like any other change and never conflict — nothing to commit. Epiq keeps its own read-only bare clone of each repo under ~/.epiq-global/repos/, fetched on sync with your usual git credentials (ssh-agent or a credential helper; a passphrase prompt cannot be answered) — never on startup. A commit shows once it is pushed and the board has synced.
A board reads at most 20 repos; one connected past that is listed but not fetched until one ahead of it is disconnected. Each clone may take at most 2 GB of disk on your machine; :config repoCloneMaxMb <MB> changes that, in your own config. A fetch that would pass it is stopped and undone, and the repo says so. The Repos section shows what each clone takes on this machine, and the total. Autosync fetches each at most once a minute; a sync you ask for always fetches. Widening since fetches the older history, narrowing it keeps what is already cloned. Disconnecting a repo deletes its clone, on every machine as it syncs; worktrees of one board share a clone. A repo is something every contributor can fetch, so a local path is refused. A connected repo that is itself an epiq board lends its commits, never its board's event log.
Since anyone on the board can connect a repo, URLs are read with care: only https, http, ssh, git and user@host:path URLs are accepted, never one carrying a password or a user before an http host, and git runs in the clones with none of your hooks, attribute drivers or command-running transports.
Epiq originated from the command line and offers a first-class terminal experience, but also features a browser interface powered by the same Git-backed event engine.
Fundamental design choices gives a system with:
- Workflow replay, - inspect what happened while you were away, as if it happens now
- Simple setup — no accounts, SaaS, or external services required
- Repo-native — your issues can live where your code lives
- Offline-friendly — works anywhere, with eventual consistency
- Fast — local first, and eventual consistency makes Epiq edits instant
- Portable — runs on your local machine, on a remote Linux server or your grandma’s connected toaster
- Command driven — scriptable and automation-friendly, ready for the agentic era
Binary:
curl -fsSL https://github.com/raw/ljtn/epiq/main/install.sh | shInstalls to ~/.local/bin by default. Override with EPIQ_INSTALL_DIR (or XDG_BIN_HOME); pin a version with EPIQ_VERSION=v1.0.0.
npm install --global epiqepiq --version- Make sure you're inside a Git repository
# If needed:
git init
# For collaboration, use a repo with a remote (e.g. clone from GitHub)- Run:
epiqIf it is your first run, this opens the interactive setup wizard that sets you up in about 30 seconds.
That’s it!
Once your project is set up, you can also launch the browser user interface with:
epiq guiOn a machine with no display, or with --no-open, it serves without opening a browser; open the URL it prints.
Setup wizard creates: User config persisted in
~/.epiq-global/config.json.
Initialization creates:
- Project definition in
./.epiq/project.json- Authoritative Git state at
~/.epiq-global/worktrees/<id>- Updates your
.gitignoreto ignore local-only.epiq/log/Epiq manages a dedicated Git state branch and worktree automatically as the source of truth for synchronization.- A local debug log at
.epiq/log/epiq.log— check it first if sync, boot, or a Git operation is misbehaving.
Epiq provides a MCP (Model Context Protocol) server for agents to interact with, making it easy to plug into modern agent frameworks. The server is exposed by the epiq-mcp binary that ships with the package.
The reliable way to register the server is with the claude mcp add command — it writes to the correct config file for you, so you don't have to hand-edit JSON:
# Available everywhere (recommended)
claude mcp add --scope user epiq -- npx -y --package=epiq epiq-mcp
# Or only in the current project
claude mcp add epiq -- npx -y --package=epiq epiq-mcpVerify the connection with claude mcp list (it should report epiq … ✔ Connected). MCP servers are loaded at startup, so restart Claude Code after adding the server before its tools become available.
Find skill at .claude/skills/epiq/SKILL.md that documents a recommended workflow for working the Epiq board. epiq_skill_install writes the same file into any repository that lacks it, so a project set up from an agent gets the rules too — after epiq_project_init, since init refuses a repository with uncommitted files; it leaves an identical copy alone and refuses to overwrite a differing one unless told to with force.
Every process — your TUI, your GUI, each agent's MCP server - writes as your user, so by default the board cannot tell one agent from another. The MCP allows agents to assume an identity, so at the start of a session, tell your agent which name it should assume.
That agent then shows up in the contributor list, assigns itself rather than you, and authors its own events. This can be useful when tracing many agents at the same time. Consider reusing names instead of inventing one per session, or the registry fills with single-run identities.
For clients that are configured by hand, add the following to the client's MCP config file — note this is not the same as Claude Code's ~/.claude.json; Claude Desktop uses claude_desktop_config.json:
{
"mcpServers": {
"epiq": {
"command": "npx",
"args": ["-y", "-p", "epiq", "epiq-mcp"]
}
}
}Once registered, agents can interact with your local Epiq instance through the MCP.
npx -y -p epiq epiq-mcp resolves the package against the npm registry every time it starts, even if it's already cached locally. In agent sandboxes with restricted network access, this can make the MCP server appear to hang. If you're running Epiq's MCP server in such an environment, install it globally once and point your MCP config at the resolved executable directly, bypassing npx (and the registry lookup) entirely on every subsequent start:
npm install --global epiq
which epiq-mcp # use this absolute path in your MCP config{
"mcpServers": {
"epiq": {
"command": "/absolute/path/to/epiq-mcp"
}
}
}npx remains the simpler option for normal, network-connected setups.
Epiq uses Git in the background - no manual Git commands are required. Running :sync synchronizes changes between your local state (persisted at ~/.epiq-global/worktrees/<id>/) and the remote state. By utilizing Git worktrees, synchronization stays isolated from your regular development workflow. Project tracking metadata is stored in .epiq/project.json.
Epiq is designed to provide robustness in a distributed, Git-backed environment where multiple users may update state concurrently. Instead of mutating shared files, Epiq uses an event-sourced model to prevent merge conflicts and make concurrent changes predictable.
All changes are stored as append-only events in user-scoped files, rather than modifying a shared state file. This avoids in-place edits to the same lines and significantly reduces the likelihood of Git conflicts.
State is reconstructed in-memory by replaying a merge of all user logs.
The current state is derived by replaying events in a deterministic order.
Events use a composite of time-sortable IDs (ULIDs) and a reference to the last known event ("edge"). On creation, events are appended relative to the last known event. If multiple events share the same reference point, their relative order is resolved using their time-based IDs.
This approach:
- Provides stable and reproducible ordering across machines
- Limits the impact of potential clock drift to small local ordering differences
- Ensures that concurrent updates converge to the same state
Epiq resolves concurrent changes at the event level:
- Events are designed to be idempotent where possible
- Later events take precedence when conflicts occur
- Each user writes to their own event log file
- Git merges become trivial combinations of changes in independent files
Epiq follows a local-first model:
- All operations apply instantly on the local machine
- Synchronization happens explicitly (
:sync) or automatically - When histories diverge, merging event logs and replaying them leads to a consistent state
Frequent synchronization reduces divergence and keeps the system predictable
🫡 Never leave your editor!