Show HN: Epiq – Distributed Git based issue tracker TUI(ljtn.github.io) Issue trackers typically live outside of your workflow, with poor ergonomics. Epiq aims to solve that, bringing issue tracking into your terminal. Multi-user collaboration is achieved via git using user-scoped immutable event logs that converge in memory. Put my all into it. Let me know what you think. |
Two weeks ago I had listed out the problems I could remember offhand: https://news.ycombinator.com/item?id=47956979
It sounds like there's intentionally no attempt to handle the last one (that this is by devs for devs), and points 3 and 4 might be addressed somehow since it mentions syncing automatically. Does it store data separate from git to avoid the first two?
- Issue state is not tied to commits in the checked out repo. Events live in append-only user-scoped logs and are materialized independently of the checked out branch, so switching branches does not change issue state. This is solved with git worktrees.
- Epiq keeps state in a dedicated state branch and does not put issue data into normal code history. The working branch stays clean.
- Sync uses normal git push/pull semantics.
- Multi-user conflicts are prevented because each user writes only to their own immutable event log file. You never co edit a file. Logs converge state in memory from the combined event stream. There’s no shared mutable issue document being edited.
- The non-developer distribution can be addressed with exported state .md files (with the board as ascii). They are currently not generated automatically, but you can generate them at will. [edit - addition: Considerable effort has also been put into making the tool accessible to non-technical people, so there is auto completion, hints, a command palette with descriptions of each command, arrow key navigation and so on. It is my hope that anyone can pick it up rapidly. And a web interface could definitely be crafted for that usecase]
Epiq looks to be written in TypeScript and distributed as JS via NPM. You know what excels at executing JS? The browser.
If you want to actually address the usability problems—then create a CONTRIBUTING.html—linked from the README, that users are instructed to double-click to open (i.e. launch in the browser on any sanely configured system). From there, they can/should be able to load the project either by pointing to it with a filepicker-based workflow that's the same as VSCode's "Open Folder…" workflow, or by dragging and dropping the source tree into the browser window. If you do it right, then this should immediately present them with a browser-based UI for poring over and interacting with all the Epiq data in the repo—down to the Git commands to execute to integrate changes into the Epiq "database".
It's beyond baffling that so many programmers who are nominally JS developers thumb their noses at writing standards-compliant code and instead insist on coding directly against Node's proprietary APIs.
This work tree is not included as part of the standard repo
Then I have two commands, a save and restore. These commands create a remote branch inside the git repo called tasks and updates it with the contents of the .tasks work tree. This remote branch only contains tasks no normal code.
Restore takes the contents of the remote branch and downloads it back to the locally created .tasks work tree
Save and restore are manual processes, but the tool I wrote triggers a save whenever a merge to main occurs.
The one that tied issues to specific commits I think even portrayed the different-states-in-different-branches as a feature, that for example you could easily tell at a glance whether a bug had been fixed on the branch you're on or not. This was also the era when people were figuring out complex branching strategies like gitflow, where that would be a reasonable thing to be uncertain of.
Like I said the problems were part of the design, not incidental, the tradeoffs just ended up not what people wanted.
Also something else I didn't mention before, all of these were command-line, not TUI. I have no idea how that would've changed the result. For example I could imagine automatic background syncing actually being reasonable, sidestepping some of the issues the command-line ones had to work around.
> No non-developer UI for project managers to see or comment on issues.
Strategically, I'd prefer this over anything that offers non-developer UI. My experience with any tool that offers non-developer UI for developer-related activities was overall infuriatingly negative (think Jenkins, JIRA, Github and the likes etc.) Because these UIs will usually expose the underlying functionality in a bad way that will create pathologically bad practices that will require the developers to accommodate the lowest common denominator.
Here's one example: Github or GitLab PR management interface. Before this became "standard practice", PRs used to be deal with from the interface to Git chosen by the developer. It allowed more freedom of editing and communication, but, most importantly, it didn't lock the developers into a few selected choices of reconciling the new changes with the existing code.
GitLab, for example, doesn't even offer the only good way to do that: there's no way, using GitLab interface to rebase the suggested changes on the target branch. All the options it offers in UI are wrong. And yet, companies, like the one I work for, make it a corporate policy to work exclusively through this garbage UI because they make their OPs / IT teams design workflows around it.
As an aside: if a project manager cannot use Git, they shouldn't be a project manager. There are some job requirements that one must meet in order to hold a job, and using the most popular VCS should be one of them. This is just as true as it is true for developers: if they don't know / can't use Git, they shouldn't be in that role. The manager's ineptitude shouldn't be an excuse to make / adopt cruddy software.
I’d (re)consider a couple of things if you intend to work on it and make it viable for a wider audience.
1. Who is it aimed for? If product managers and designers _are_ in scope e.g. you imagine full engineering teams using it, then a TUI isn’t gonna cut it. It’s a great interface choice for devs but I don’t think it’s organizationally viable to force everyone else in the terminal.
2. I’d think about either having a central issues repository as a default / recommended option or creating an easy way for linking issues together across repos. To me, as appealing as it sounds to have your code and issues together, these things often evolve at a different pace. If I want to edit an issue I’m working on to add some new info or address changing requirements, I almost definitely don’t want to commit and push it with my local WIP version of the code.
Let me address these:
1. I envision people already comfortable with the terminal as the first to pick it up, but as someone else pointed out, a considerable amount of effort has gone into lowering the threshold and making it usable for people with limited command-line experience. I can also definitely see a future web UI being added over time.
2. There is no requirement to run Epiq alongside your codebase - you could also use a separate repository dedicated to issue tracking. When you run epiq, it traverses upward until it finds the nearest project definition. In theory, you could initialize Epiq at a higher-level scope and have multiple child repositories share the same board state, although that setup has not been officially verified or supported yet, so I would wait until there is a version that explicitly supports it.
The current TUI is built with Ink, which is a React renderer for the terminal, so conceptually the UI structure already maps naturally to the web.
> The MCP server lets AI tools interact with Epiq in a predictable way.
Or maybe just publish a skill for the agent to use your CLI? The agent alredy uses CLI commands to interact with git itself
There is a small level of noise in TUI output, and structures that are easily parsed by a human can be ambiguous for an agent (for instance column layouts). You could definitely let agents interact with Epiq purely through the CLI, but the idea behind the MCP server is to provide stable, predictable interfaces where determinism matters.
This. Skills effectively turned MCPs obsolete in the vast majority of MCP applications. A single CLI tool implemented following a progressive disclosure style doesn't even need a agent skill for coding agents to use it effectively.
Do I understand correctly that if 2 people add a lot of information to one issue only one of them 'wins' and becomes visible? Or is it more subtle?
If only the latter one becomes visible, how do you get to the edits of the other person and 'merge' it again?
In the event of conflicting updates to the same text block (currently title or description fields), later events take precedence.
What you can do is use commands like ":peek prev" (takes you to the previous edit), ":peek 1h", or other time-travel commands to inspect previous states and manually recover overwritten changes if needed.
Thanks, I think that would work fine in most cases if you can open your editor with the 'prev' version and the current version in 2 panes (or in diff mode).
To be clear, I'm really into this. I'm using a custom git-based agent and this is a viable replacement for its issue tracking.
You're talking about node.js projects running on node.js, and you're complaining that it consumes node.js APIs. Strange.
> You're offering a retort to someone who is communicating their position that you ought not do something, where the retort consists of nothing more than explaining that people are doing it. Yes, clearly. But what the person you're responding to is arguing is that you ought not do it.¶ Consider[…]:
> Person A: Here's little advice: don't take up smoking. Smoking is bad for you.
> Person B: Yet people smoke
The Browser with its sandbox hardened for the internet is the way to go for any future personal/dx tools that were previously node only.
It can't. The CONTRIBUTING.html shell would spit out a file and tell the user what Git commands need to be run—just like project READMEs (or landing pages like jekyllrb.com) show which commands will install the tool.