{"slug": "replay-workflows-with-epiq-the-next-gen-issue-tracker", "title": "Replay workflows with Epiq the next gen issue tracker", "summary": "Epiq launched as an open-source, self-hosted, local-first issue tracker that stores project state as an immutable, Git-backed event log, enabling workflow replay of what moved, when, and by whom. The tool ships an MCP (Model Context Protocol) server via the epiq-mcp binary so agents can interact with tickets, and links commits to tickets by prefixing a commit subject with the ticket ref, which surfaces the commit in the ticket's code-diff tab. Epiq installs via a curl script to ~/.local/bin by default or npm install --global epiq, with version pinning through EPIQ_VERSION=v1.0.0.", "body_md": "*Issue tracking as code. Open source, distributed, local-first, and code-native.*\n\nEpiq provides issue tracking as a portable, integrated part of the development environment, with access to all the powerful tooling developers are used to.\n\nKanban to review workflows in your terminal or in your browser - while keeping all state local, Git-backed, and versioned.\n\nWith great attention to user ergonomics and developer experience, epiq strives to make project management painless and friction free.\n\nAgents now run whole sprints unattended. Because state is a full event log, you can replay the board to find out what moved when, who moved it, and what changed along the way.\n\nPrefix a commit's subject with the ticket's ref to link the two:\n\n```\ngit commit -m \"1YRTG8T ...<some message>\"\n```\n\nLinking 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.\n\nPreserve the linking post-merge via conventions:\n\n- **Rebase-merge** It is advised to rebase-merge so the ref-prefixed commits land on`main` as they are, preserving linking post-merge.\n- 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.\n\nEpiq 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.\n\nEpiq 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.\n\nMost issue trackers live outside your workflow. Instead of a centralized, managed service, Epiq keeps project state alongside your repository, where it travels with your code.\n\nThese design choices result in a system that offers:\n\n- **Workflow replay** , - inspect what happened while you were away, as if it happens now\n- **Simple setup** — no accounts, SaaS, or external services required\n- **Repo-native** — your issues can live where your code lives\n- **Offline-friendly** — works anywhere, with eventual consistency\n- **Fast** — local first, and eventual consistency makes Epiq edits instant\n- **Portable** — runs on your local machine, on a remote Linux server or your grandma’s connected toaster\n- **Command driven** — scriptable and automation-friendly, ready for the agentic era\n\nBinary:\n\n```\ncurl -fsSL https://raw.githubusercontent.com/ljtn/epiq/main/install.sh | sh\n```\n\nInstalls to `~/.local/bin` by default. Override with `EPIQ_INSTALL_DIR` (or `XDG_BIN_HOME`); pin a version with `EPIQ_VERSION=v1.0.0`.\n\n```\nnpm install --global epiq\nepiq --version\n```\n\n1. Make sure you're inside a Git repository\n\n```\n# If needed:\ngit init\n# For collaboration, use a repo with a remote (e.g. clone from GitHub)\n```\n\n1. Run:\n\n```\nepiq\n```\n\nIf it is your first run, this opens the interactive setup wizard that sets you up in about 30 seconds.\n\nThat’s it!\n\nOnce your project is set up, you can also launch the browser user interface with:\n\n```\nepiq gui\n```\n\nOn a machine with no display, or with `--no-open`, it serves without opening a browser; open the URL it prints.\n\nSetup wizard creates:\nUser config persisted in `~/.epiq-global/config.json`.\n\nInitialization creates:\n\n- Project definition in\n`./.epiq/project.json`- Authoritative Git state at\n`~/.epiq-global/worktrees/<id>`- Updates your\n`.gitignore` to ignore local-only `.epiq/log/`\nEpiq manages a dedicated Git state branch and worktree automatically as the source of truth for synchronization.- A local debug log at\n`.epiq/log/epiq.log` — check it first if sync, boot, or a Git operation is misbehaving.\n\nEpiq 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.\n\nThe 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:\n\n```\n# Available everywhere (recommended)\nclaude mcp add --scope user epiq -- npx -y --package=epiq epiq-mcp\n\n# Or only in the current project\nclaude mcp add epiq -- npx -y --package=epiq epiq-mcp\n```\n\nVerify 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.\n\nFind 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`.\n\nEvery 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.\n\nThat 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.\n\nFor 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`:\n\n```\n{\n\t\"mcpServers\": {\n\t\t\"epiq\": {\n\t\t\t\"command\": \"npx\",\n\t\t\t\"args\": [\"-y\", \"-p\", \"epiq\", \"epiq-mcp\"]\n\t\t}\n\t}\n}\n```\n\nOnce registered, agents can interact with your local Epiq instance through the MCP.\n\n`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:\n\n```\nnpm install --global epiq\nwhich epiq-mcp   # use this absolute path in your MCP config\n{\n\t\"mcpServers\": {\n\t\t\"epiq\": {\n\t\t\t\"command\": \"/absolute/path/to/epiq-mcp\"\n\t\t}\n\t}\n}\n```\n\n`npx` remains the simpler option for normal, network-connected setups.\n\nEpiq 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`.\n\nEpiq 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.\n\nAll 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.\n\nState is reconstructed in-memory by replaying a merge of all user logs.\n\nThe current state is derived by replaying events in a deterministic order.\n\nEvents 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.\n\nThis approach:\n\n- Provides stable and reproducible ordering across machines\n- Limits the impact of potential clock drift to small local ordering differences\n- Ensures that concurrent updates converge to the same state\n\nEpiq resolves concurrent changes at the event level:\n\n- Events are designed to be **idempotent** where possible\n- Later events take precedence when conflicts occur\n- Each user writes to their own event log file\n- Git merges become trivial combinations of changes in independent files\n\nEpiq follows a **local-first** model:\n\n- All operations apply instantly on the local machine\n- Synchronization happens explicitly (`:sync` ) or automatically\n- When histories diverge, merging event logs and replaying them leads to a consistent state\n\nFrequent synchronization reduces divergence and keeps the system predictable\n\n🫡 Never leave your editor!", "url": "https://wpnews.pro/news/replay-workflows-with-epiq-the-next-gen-issue-tracker", "canonical_source": "https://github.com/ljtn/epiq", "published_at": "2026-10-06 22:15:06+00:00", "updated_at": "2026-10-06 22:19:33.041702+00:00", "lang": "en", "topics": ["ai-agents", "agent-protocols", "developer-tools", "ai-tools"], "entities": ["Epiq", "Model Context Protocol", "epiq-mcp", "GitHub", "npm"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/replay-workflows-with-epiq-the-next-gen-issue-tracker", "markdown": "https://wpnews.pro/news/replay-workflows-with-epiq-the-next-gen-issue-tracker.md", "text": "https://wpnews.pro/news/replay-workflows-with-epiq-the-next-gen-issue-tracker.txt", "jsonld": "https://wpnews.pro/news/replay-workflows-with-epiq-the-next-gen-issue-tracker.jsonld"}}