There's also Beans, doing MD-based ticketing in your project. It's really good. (Disclaimer: I've contributed a few of the agent rules.)

https://github.com/hmans/beans

> Beans is an issue tracker for you, your team, and your coding agents. Instead of tracking tasks in a separate application, Beans stores them right alongside your code. You can use the beans CLI to interact with your tasks, but more importantly, so can your favorite coding agent! > > This gives your robot friends a juicy upgrade: now they get a complete view of your project, make suggestions for what to work on next, track their progress, create bug issues for problems they find, and more.

Much, MUCH less invasive than beads (basically just a CLI tool and a `.beans.yml` & `.beans/` in your project, and a joy to work with. CLI, TUI, labels, status, types (epic, feature, task etc.), GraphQL query interface (agents love that).

It's good.

I just asked Claude to create a memory system for itself for one of my projects. It created a file based utility written in Rust on its own. I offered it to use beads but it declined as beads is a task tracker and what we needed was a spec tracker.

Long winded way to say that it’s now easier to just create something to fit your needs… like 3D printing components.

Claude Code already has a built-in task tracker for short/mid term tracking.

I would love to have a nix flake to install it easily with nix! Given it's built in bash that should be basically no issue whatsoever.

Thanks a lot for this! I was interested in beads but found the author's approach to software development quite erratic and honestly a bit unprofessional. Yes, LLMs are great, but no they shouldn't be the lead developer.

Beads is an incredibly difficult-to-follow mess for something that is at its core a pretty simple idea. You distilled it to its core, I will absolutely be checking this out :)

I have been looking at this problem space, including beads recently.

I wasn't able to find something AI-native that supported subissues, and worked across projects. I require git worktrees on my programming work now, and I want it to be able to handle integration with systems like Linear or even GH issues (which was my preferred ticketing system before CLIs emerged)

The idea is in part, ~I have 15 minutes right now, what is the most important thing to put attention to? Be routed to the project and go immediately to work with a CLI.

I'm using Claude Code and codex for programming and administrative chores now. For example, managing the process of finding and selecting an arborist.

My main personal project, focuses on making Claude Code and Codex conversations useful (https://Contextify.sh). I use uses pure markdown (TODOS.md) for issue management and it is at its limit.

I'm less concerned about the DB's storage location. I don't think it needs to be stored with each project, but each project does need to be able to access it.

I suspect that I'll ultimately want to host it.

Looks great, well done.

What I do not understand about beads or alternatives such as this is: why not just use github issues? Or is it just the aversion of being tied to github?

My agent team does, easy to tell them so and give them access to suitable gh commands.

vendor lockin + slow network calls (+ GitHub is down sometimes). if you want to search over hundreds of issues, `gh search` isn’t bad but you can do a lot better with a filesystem or embedded database

that said for work I use GitHub and have CC make use of the gh CLI, works great. but I have wanted some sqlite/duckdb tracker you could just commit, maybe with back and forth between markdown files. also GH projects are pretty slow/clunky

It's a great question. I'm sure the answer varies a lot by who you ask.

For me, there's a ton of extra control and capability from having things local. Nothing wrong with github, and agents are great with the gh CLI, but it's really not quite the same.

Plus, having it based on directory structure rather than repo means I can locate tickets where the work actually happens. Not everything I work on is on github, and some of the things that are on github are in monorepos where each project really deserves its own set of tickets.

IMO Beads, Ticket, etc. give you optionality.

Not every project needs to have Github as a dependency. Its added overhead and coordination work that isn't needed for every job.

YMMV, and I get it if you're in a commercial/professional environment, but if you're a solo dev or a small team, then IMO Github doesn't need to be a part of your orchestration (setup project, issue CRUD, pr, etc), just state sync/distribution.

Agents can use local trackers as drop-ins to GH and have similar commands provided to do the same job.

Its fewer moving parts, and more forgiving as you can fix things locally, before pushing out to GH or your Git server of choice.

I agree with OP that beads has great primitives, but I think its become a bit unwieldy in trying to becoming something "everyone" including larger teams can use.

Going to try Ticket out, though personally I prefer JSONL to MD for this kind of tracking, since I find that Claude finds a good concise balance of detail on its own when writing to JSONL vs Markdown files where it tends to be verbose.

Yes, I get it. Personally dancing between commercial work (GH) and personal (no need for GH). Because of orchestration setup works for former end up using also for latter.

Maybe should try to give tickets a go. gh cli does add another HTTP layer and slows things down - feels silly to be paying for Cerebras if one is slowed down by other tooling.

This is my question, and why not go a step further and just self host foregjo?

Forgejo is a single go binary and very fast.

You can script it using an API, you have full access to the database which can be sqlite3 or postgres.

Then you get all the benefits of an integrated issue tracker which has a great GUI for humans to review.

I really don't understand the raison-de-etre for beads other than yak shaving, and would really like to.

Digging the idea and incredibly simple implementation - but do you have a model in mind for clean-up? I've been working with it for an hour and have ~30+ tickets across a series of tasks, which are all just named by ID so no obvious way to purge (I could be missing something obvious).

Also, no concept of tags/labels? Are dependencies your primary means of organization?

Ah I don't delete these or really look at the `.tickets/` directory. I have about 1900 tickets in one project and navigate them through VS Code. Ctrl+t does fuzzy finding across all markdown headers and I Crtl+Click in the terminal quite a lot to jump to ticket files.

But yes, dependencies are everything here. I use `tk dep tree` regularly to visualize the graph and click on the things I want details on. Typically I don't have too crazy of a list of open tickets so it's easy enough to find things by running `tk ready` and `tk blocked` and clicking what I'm looking for. For historical things, I just search in the `git log` pager.

If it'd be useful though, I can look at a `tk delete` command that deletes a given ticket and all of its dependencies to clean up a whole tree in one shot. Not sure I'd ever use it myself though.

I'd find it handy. I think there's some risk in agents tripping over stale tickets and consuming tokens - I see it with .md all the time.

Tickets by dependency would be nice (although my agent hasn't really used dependencies yet), and ideally something to just quickly wipe out closed tickets with a single command would be nice.

Or at least move them to a .tickets-done directory, so if the agent is searching under .tickets it won't see them, but you retain some history.

I started playing around with beads, but when I got to the phrase "landing the plane" I started looking for simpler alternatives. So far, this looks much closer to what I want (flat files, human readable, basic syntax). Looking forward to putting it through its paces over the next few weeks.

Vaguely related question, for people who run multiple agents in parallel: how do you do that? do they all work on the same files at the same time? won't that create a terrible mess? or do you like check out the codebase 8 times into separate directories and do a complicated PR flow type thing?

Some people use git worktrees so each agent is working in a separate directory.

Some people have multiple agents working in the same directory, and allow the agents to tell each other what they're doing and which files they're editing: https://github.com/Dicklesworthstone/mcp_agent_mail

you can use https://git-scm.com/docs/git-worktree to have many "views" of a single git repo.

For more complex environments, use multiple VMs (common to have large VMs running in AWS/GCP for development and only use your laptop or phone as a thin client)

I don't follow, so these people using 8 claude codes in parallel, they have 8 git worktrees? and 8 devservers listening on 8 ports?

or 8 VMs? won't syncing be super slow there? like i believe it, but it feels like a lot of setup and i don't understand why nobody seems to be talking about it.

> but it feels like a lot of setup

Ah, but you can have Claude Code set it up for you!

I am also curious about this, how people wrap their head around multiple changes in multiple features at the same time?

I personally, can handle only one feature at a time, prompt the AI, refine the changes, re-plan, review changes, rewrite parts when necessary, but my mind is still with one feature.

How do you folks manage multiple parallel feature development at the same time?

> how people wrap their head around multiple changes in multiple features at the same time?

Long before AI I routinely had 5 parallel development environments I would flip between. (I do distributed systems stuff, think HPC-adjacent clusters, when you're too big for Kubernetes and too small for supercomputing). One would be running long-running tests for my current changes, one being reset to a clean state, and 3 more on standby so I had 100% "duty cycle" (the reset took a while). You got used to multitasking.

Its different though, because your tasks were long-running and you are forced to have idle time between those runs.

In case of AI, it just delivers things in 2-3 minutes, this time is not enough (or worth) to switch the context (for me personally)

Git worktrees for parallel repo clones on different branches, a worktree setup script that runs when a worktree is created (npm install etc) and vibe-kanban [0] to visually create, monitor and approve parallel work

0 https://www.vibekanban.com/

For solo projects I just use `git notes`. It's all in the same place, you can push them, and Claude Code just needs to be told that they exist. It knows how to use them and it's totally fine. They don't have merge logic, though, so don't use them in collaborative projects.

Is there a way to do dependency tracking with `git notes`? That's really the core thing for me. I like to do a ton of up-front planning work, split it all out into a graph of tickets and then let agents chew threw them until done.

There aren't a whole lot of tools that have a clean interface for that workflow though.

The notes can have references. So I just have it name the other notes that are relevant. I don't do the toposort you're talking about but I do the referencing.

If you could describe it, what would the ideal interface for that be?

Oh my lord it's written in bash. That's incredible. Well done! It's good to feel like the new kid sometimes as I approach 30 and ossify technically -- I'm sure this will develop a healthy fanbase of senior engineers, if the one's I've known are anything to go off of.

More relevantly: I've spent way too long rolling my own issue tracking systems (plural!) over the years, and it's good to see someone else share my intuition that dependencies and tagging are by far the most important part of solo-ish issue trackers. You'd be shocked how many massive tech companies publish issue trackers where dependencies are an afterthought (or worse: a paid upgrade).

My only tiny, soft suggestion would be mention "Unix Philosophy" rather than just the MVP link, tho it is indeed cute. As I alluded to above, the former has a dedicated cult behind it already ;)

I feel like using Bash is a double-edged sword. Yes, it's available on every modern unix-like (notably absent from the base system in the *BSDs), but the language (being an sh descendant) is honestly horrible for anything more complex than 200-300 lines of plugging one command into another. Ticket isn't even pure Bash; it embeds several inline, 100+-line AWK scripts, and a giant jq query (an external tool!). All of which is horrible for syntax highlighting, mind you.

These days Python is almost as universally available, and I've seen few systems ship without Perl. Both provide excellent backward compatibility; I have many scripts that still run unchanged on Python 3.6 (2016).

Thanks! I agree completely. Dependency tracking is such a vital part of organizing work and it's hard to find good tooling for that. Beads started out as one and I wanted to maintain the simplicity it used to offer.

And I may just go make a README tweak re: unix philosophy... The MVP story floated up from the back of my mind when I went to go build this but you're totally right.

I'm curious, and in the spirit of a true MVP - does this need type, assignee, links or the parent relationship? Do you see the agent using them in practice? It seems like a minimal implementation could do without all of those, and I wonder if they're useful to the agent, or are just documentation for humans.

Since these seem more lightweight/ephemeral, it seems like it would be useful to search upwards for the nearest enclosing .tickets directory, so that subsystems could have separate issues.

Great call out. The agents will set those on `create` calls but don't typically reference them afterwards.

I have a fairly robust orchestration layer built on top of this tool that relies heavily on those fields though. But without that, they are a bit noisy.

Mixed feelings on upward search. One of my pain points with beads was that agents would sometimes create a bead outside of the correct directory and get dumped into a global `~/.beads/default.db` and make a mess. They've done that a couple times with ticket but run `tk ready` afterwards, see the new ticket is the only one, realize their mistake, and then relocate the ticket into the correct location. Still thinking on that one.

Anyone thinking of adding a feature or separate tool for exporting existing gitlab/github issues to this Ticket or Beads? Looks like in the Agentic Era having issues/tickets managed using this kind of tools and kept in folders side by side with code and documents is much more desirable than separating them to web based git servers

Wouldn’t it make perfect sense to wrap this in a Claude Skill instead of distributing as a separate package?

It really would. That's on my TODO list for next weekend.

I may actually make a slimmer one for that use case though. There are a number of commands here that are really only useful at the orchestration layer and would be mostly noise in a pure Skill context.

I've found Backlog.md quite nice

https://github.com/MrLesk/Backlog.md

has a nice tui/webui for me, and mcp for the agent.

Nice solution, I had some success with https://www.task-master.dev/ it's a bit more complex though

why should people use this as opposed to https://github.com/git-bug/git-bug?

or if that's not similar enough, how about https://github.com/dspinellis/git-issue?

I'm not familiar with enough to say concretely. What's the dependency management experience like with those? That's really the core of my needs.

On the surface though, those are both significantly heavier tools. At minimum, there's a learning or adaption curve. I had built workflows on top of Beads and making a drop-in replacement was easier than reworking all of them.

Just glancing at it:

1. That repo is based on 250+ .go files and stores stuff as git blobs, which is obviously a much more involved, collaboration-focused approach than this tool's 1 .sh file and human-readable markdown files.

2. `tk` seems to be built with agent usage in mind from the jump. I'm sure `git-bug` is perfectly usable, but it's clearly not a focus.

3. The two linux package managers listed for `git-bug` are for (drum-roll, please...) arch and nix. Of course the latter can be setup on every (?) distro, but speaking personally, I find that to be quite the red flag for a devtool! I'm sure it's a bright green ones for fans of those distros/mindsets, of course :)

hey, git-bug maintainer here!

just to address the package management situation on linux: i currently use nixos, and previously ran arch linux for over a decade. the AUR package is community maintained, as is the nixpkgs package (i maintain it though, so the community doesn't really need to here).

making installation simple on other, more commonly used distributions is a goal, but is less of a priority at the moment than feature work and bug fixes. we're very open to package maintainers on those distributions packaging git-bug, however :)

Is there a mini tutorial demonstrating best practices for people keen to try but who haven't used agents like this?

I've actually built up a set of Claude Skills for creating and using tickets. Currently overhauling them based on what I've found to be most effective. Will probably publish those in a week or two when I've nailed down what I want there.

I haven't seen any great content around this though. I've gone through a lot of trial and error with different approaches over the last few months.

Biggest thing I can say: plan up front. I frontload basically all of my involvement and have Claude do a ton of research to make a very detailed plan document and then the plan gets decomposed into a graph of tickets. I have some other tooling that orchestrates delegating the tickets to focused Claude Code sessions and they can work through them mostly autonomously for many hours until the work is done.

Good question though I expect it'll get buried amongst all the other comments. Maybe create an "Ask HN" post.

I asked Google/Gemini about a tutorial and it responded with several YouTube videos and also produced this subreddit: https://www.reddit.com/r/AI_Agents/

Found this too: https://nitter.net/bcherny/status/2007179832300581177#m

Thank you. It is always intimidating to see how people are using 5-10 agents for coding, but haven't seen practical examples of the process and how people do this specifically.

How is merge handled?