how it works.

Installation

Epiq ships as a single binary (with an npm package alternative). The binary installs to ~/.local/bin by default.

Quick install (binary)

curl -fsSL https://raw.githubusercontent.com/ljtn/epiq/main/install.sh | sh

Override the location with EPIQ_INSTALL_DIR (or XDG_BIN_HOME), and pin a version with EPIQ_VERSION=v1.0.0.

Via npm

npm install --global epiq

Verify

epiq --version

Getting started in two steps

Epiq lives inside a Git repository — your issues can live where your code lives.

1. Make sure you are inside a Git repository. For collaboration, use a repo with a remote (e.g. cloned from GitHub).

   # if needed
   git init

2. Run Epiq:

   epiq

On first run this opens an interactive setup wizard that gets you going in about 30 seconds. Once your project is set up, you can also launch the browser GUI:

epiq gui

Two front ends, one board

epiq opens the terminal UI, epiq gui the browser app. They are two views of the same event log in the same repository — switch whenever you like, or keep both open; whatever one writes, the other shows. The rest of this page is split the same way: the terminal, then the browser.

Core concepts

The hierarchy

State is a tree of nodes. From the top down: workspace → board → swimlane → issue. Issues hold a description, tags, assignees, comments, and a full history log. Commands are context-aware — for instance :close only exists for issues.

Event-sourced state

Every change is stored as an append-only event in a user-scoped log, rather than mutating a shared file. The current state is materialized in memory by replaying a merge of all user logs in a deterministic order (time-sortable ULIDs plus a reference to the last known event). This makes concurrent edits converge to the same state and keeps Git merges trivial.

Local-first

All operations apply instantly on your machine. Synchronization happens explicitly with :sync or automatically. When histories diverge, merging the event logs and replaying them leads to a consistent state.

Navigation & keyboard shortcuts

Epiq is keyboard-first and vim-inspired. Navigate with arrow keys or h j k l, enter a node with Enter, and step back out with q or Esc. The two things to always remember: type :help for help, and press ? anytime to open the command palette with every available command.

Command reference

Type : to enter command-line mode, then a command. Commands accept a modifier (in violet) and a free-text argument. Autocompletion suggests valid modifiers as you type, and the set of available commands depends on what is selected.

Create & edit

Issue workflow

View & history

System & sync

Time travel

Because state is a full event log, you can inspect the board as it was at any point in the past. Use :peek with a time offset, or step through history:

# jump to an offset: h, d, w, mo, y (e.g. 3 days ago)
:peek 3d

# or jump to an absolute date
:peek 2026-01-15

# step backward / forward through history
:peek prev
:peek next

# return to the present
:peek now

Where :peek shows a frozen snapshot, :replay plays history forward from that point as an animation — watch the board evolve event by event. The optional second argument sets the playback duration:

# replay the last month of activity
:replay 1mo

# same, spread over a 30 second animation
:replay 1mo 30s

While peeking or replaying, the board is read-only; viewing, yanking to the clipboard, exporting, and configuration remain available.

Export

Run :export to write the current board layout to a markdown file — handy for sharing a snapshot, generating reports, or feeding context to other tools.

:export

Configuration

Adjust settings with :config <setting> <value>.

The board

epiq gui serves the same board in the browser. Add tickets and lanes in place, and narrow a busy board with the filter box — it matches on ref or title.

Tickets & commits

Clicking a ticket opens its panel, docked to the right or along the bottom. Descriptions and comments take markdown, and images can be pasted or dropped straight in.

The Code tab is where the ref convention pays off: every commit whose subject starts with the ticket's ref shows up with its diffstat and per-file diff, and any line can be commented on.

Timeline

Drag the scrubber across the history to check out the board as it was at that moment, as volume per period or as individual events. The header reads Read-only while you are in the past, and Now brings you back.

Sync & Git

Epiq uses Git in the background — no manual Git commands required. Running :sync synchronizes changes between your local state (at ~/.epiq-global/worktrees/<id>/) and the remote. By using Git worktrees, synchronization stays isolated from your regular development workflow.

Changes are append-only events in user-scoped files, so Git merges become trivial combinations of independent files. Later events take precedence when conflicts occur, and idempotent events keep concurrent updates predictable.

MCP & agents

Epiq ships an MCP (Model Context Protocol) server via the epiq-mcp binary, so AI agents can interact with your local instance.

Claude Code

The reliable way to register the server is with claude mcp add — it writes the correct config for you:

# 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-mcp

Verify with claude mcp list (it should report epiq … ✔ Connected). MCP servers load at startup, so restart Claude Code after adding the server.

The Epiq skill

Registering the server tells an agent what it can do; the skill tells it how to work the board — use the MCP tools rather than the CLI, sync on demand, keep tickets small and their status current, and record the outcome as a comment. Epiq's own skill lives at .claude/skills/epiq/SKILL.md. Copy it into your project's .claude/skills/ and trim the rules that are specific to this repository:

mkdir -p .claude/skills/epiq
curl -fsSL https://raw.githubusercontent.com/ljtn/epiq/main/.claude/skills/epiq/SKILL.md \
  -o .claude/skills/epiq/SKILL.md

Other MCP clients

For hand-configured clients, add the following to the client's MCP config file:

{
  "mcpServers": {
    "epiq": {
      "command": "npx",
      "args": ["-y", "-p", "epiq", "epiq-mcp"]
    }
  }
}