{"id":49554079,"url":"https://github.com/ljtn/epiq","last_synced_at":"2026-05-06T00:06:37.822Z","repository":{"id":354663038,"uuid":"1006740535","full_name":"ljtn/epiq","owner":"ljtn","description":"CLI based issue tracker TUI - distributed and  backed by git","archived":false,"fork":false,"pushed_at":"2026-05-03T01:09:27.000Z","size":1639,"stargazers_count":12,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-03T01:29:18.129Z","etag":null,"topics":["command-line","git-based","issue-tracker","kanban","offline-first","productivity","task-manager"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/epiq","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ljtn.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-22T22:50:09.000Z","updated_at":"2026-05-02T23:20:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ljtn/epiq","commit_stats":null,"previous_names":["ljtn/epiq"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/ljtn/epiq","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ljtn%2Fepiq","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ljtn%2Fepiq/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ljtn%2Fepiq/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ljtn%2Fepiq/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ljtn","download_url":"https://codeload.github.com/ljtn/epiq/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ljtn%2Fepiq/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32672688,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-05T11:29:49.557Z","status":"ssl_error","status_checked_at":"2026-05-05T11:29:48.587Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["command-line","git-based","issue-tracker","kanban","offline-first","productivity","task-manager"],"created_at":"2026-05-03T01:12:43.974Z","updated_at":"2026-05-06T00:06:37.785Z","avatar_url":"https://github.com/ljtn.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003e ⓘ First stable release scheduled for end of April 2026\n\n# Epiq\n\n_Distributed CLI based issue tracker TUI_ backed by git.\n\nIssue tracking is a part of the development lifecycle, but it often becomes a painful context switching exercise with poor ergonomics. `Epiq` provides issue tracking as a portable, integrated part of the development environment, with access to all the powerful tooling developers are used to. Epiq allows you to manage all your projects directly via the command line in a visual kanban board and edit content in your favorite editor.\n\nWith great attention to user ergonomics, epiq intends to make project management painless and friction free again, and has developer satisfaction as its primary target.\n\n```\n'███████╗██████╗ ██╗ ██████╗ '\n'██╔════╝██╔══██╗██║██╔═══██╗'\n'█████╗  ██████╔╝██║██║   ██║'\n'██╔══╝  ██╔═══╝ ██║██║▄▄ ██║'\n'███████╗██║     ██║╚██████╔╝'\n'╚══════╝╚═╝     ╚═╝ ╚═══▀▀╝ '\n 🫡 Never leave your editor!\n```\n\n## What is epiq?\n\nEpiq is a vim-inspired issue tracker fully integrated in the terminal that brings the tooling to the developers’ fingertips - in their comfort zone.\n\nEpiq renders your issue board directly in the terminal using ASCII and stores its state as an event log, versioned and synchronized through Git.\n\n![Epiq cli kanban view](https://raw.githubusercontent.com/ljtn/epiq/main/resources/overview.png)\n![Epiq cli log view](https://raw.githubusercontent.com/ljtn/epiq/main/resources/log.png)\n\n## Features\n\n- Issue tracking — track work in tickets with name, description, tags, assignees, history log, etc.\n- Ergonomics — fast keyboard-driven ux, command line with history, syntax highlighting etc.\n- Time travel — inspect your app 1h, 1 week or 1 year ago\n- Filtering — query issues by description, tags, assignees, etc.\n- Autocompletion — minimize typing, stay in flow\n- Multi-user — real-time synchronization of board\n- Traceable event log — state is a full history of every change ever made\n\n## Why epiq?\n\nMost issue trackers live outside your workflow. Epiq brings issue tracking into your editor and your repo—where you already work.\n\nThese design choices result in a system that is:\n\n- **Zero setup** — no account registration required\n- **Repo-native** — your issues can live where your code lives\n- **Offline-friendly** — works anywhere, with eventual consistency as a promise\n- **Speed** — local first, and eventual consistency makes epiq edits instant\n- **Portable** — run 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- **Versioned** — every change is tracked and recoverable through Git\n\n---\n\n## MCP \u0026 Agent Compatibility\n\nEpiq provides a MCP (Model Context Protocol) server for agents to interact with, making it easy to plug into modern agent frameworks.\n\nTo register Epiq with MCP-compatible clients (e.g. Claude Desktop), add it as a server using the `epiq-mcp` binary. Example configuration:\n\n```json\n{\n\t\"mcpServers\": {\n\t\t\"epiq\": {\n\t\t\t\"command\": \"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---\n\n### Example workflow:\n\nAn issue lifecycle as epiq commands:\n\n```\n 1.  epiq new issue \"Fix login bug\"\n 2.  epiq assign @john\n 3.  epiq tag urgent\n 4.  # move with keys to reflect progress\n 5.  epiq close\n```\n\n## Installation\n\nInstall globally via npm:\n\n```bash\nnpm install --global epiq\n```\n\nVerify:\n\n```bash\nepiq --version\n```\n\n---\n\n## Getting Started\n\nIn any folder, run:\n\n```bash\nepiq\n```\n\nIf it is your first run, this opens the interactive setup wizard that sets you up in about 30 seconds.\n\nFrom here, you can start running commands or use keyboard shortcuts to navigate.\n\nThis creates settings in `~/.epiq-global/**` and initializes synchronization for your repository. A local `.epiq` folder will also be created in your repository.\n\n\u003e Epiq will execute git commands on your behalf in order to sync your work with a dedicated state branch remotely.\n\n## Usage Guide\n\n### Help\n\n- The first thing to know is that you always can access help with `:help`.\n\n### Navigation\n\n- The second thing to know is that you can navigate with the keyboard using arrow keys or `h` `j` `k` `l`.\n- You can enter nodes with `enter`, and navigate out of a context with `q` or `esc`\n\n### Commands\n\n- If you type `:` you are put in command line mode and can now insert commands.\n- Commands are context-aware, so for instance `:close` only exists for issues.\n\n### Create nodes: issue | swimlane | board\n\n- Create nodes with `:new issue|swimlane|board \u003cName of new node\u003e`.\n\n### Move nodes\n\n- Move nodes by pressing `m`. This sets you in a move state, after which you can navigate as normal, navigate to the target location, then press m again to confirm new location.\n\n### Filtering\n\n- Apply filters with the `filter` command followed by a target, and a qualifier. So in order to filter all issues with a `prio` tag you can write `:filter tag prio` and hit `enter`. You can build a combination of filters by running several filter commands in succession.\n\nClear all filters with `:filter clear`\n\n### Close issue\n\n- Close issues with `:close`. This moves the issue to a special board named `Closed` which you can find if you navigate up (press `q`) a few times.\n\n### Reopen\n\n- You can reopen a task by visiting the `Closed` board, selecting an issue and typing command `:reopen`. This will restore the issue to its last previous location.\n\n### Reuse command\n\n- Pro tip: just like in any terminal - if you need to do repeating tasks over and over again, you can just put yourself in the command mode, and then press arrow up, in order to access the last executed command. This helps a lot when you create tasks with similar names, or add the same tag to many tickets and so on.\n\n---\n\n## How epiq is synchronized\n\nEpiq uses Git in the background to synchronize state between clients. No manual git commands are required to make it work. Running `:sync` pulls and pushes changes between your local state and the remote state.\n\n- Your issue data is stored in a dedicated branch managed automatically by epiq\n- A local `.epiq/` folder is created in your project as a local cache\n\nThe `.epiq/` folder is non-authoritative and used for caching and local tracking. Epiq automatically ensures it is gitignored on every sync.\n\n## Conflict Avoidance \u0026 Data Integrity\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 minimize merge conflicts and make concurrent changes predictable.\n\n### Event-sourced state\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\n### Deterministic materialization\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\n### Conflict handling model\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\nBecause events are append-only and scoped to 1 file per user, Git merges become trivial combinations of changes in independent files.\n\n### Local-first with eventual consistency\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\n\u003e Frequent synchronization reduces divergence and keeps the system predictable\n\n---\n\n🫡 Never leave your editor!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fljtn%2Fepiq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fljtn%2Fepiq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fljtn%2Fepiq/lists"}