You don't want a git issue tracker. You want issues that live next to your code.

Every few months a developer works it out from first principles, usually in a thread on r/git or Hacker News. They don't actually want GitHub the product. They want a fast, local-feeling way to track the work, close to the code, without a heavy web app in the loop. So they reach for the obvious idea: keep issues as Markdown files in the repo, one file per issue, commit the .issues/ folder, done. Git is already the source of truth for the code. Why not the issues too?

The instinct is correct. Issues should live close to the code, move at the speed of the terminal, and never require a slow tab to update. What is wrong is the conclusion that you have to build it yourself. You end up maintaining a homegrown tracker: no search, no assignees that mean anything, no way for a teammate's agent to file a bug without a merge conflict. The idea is right; the DIY tax is the problem.

This is the case for a tracker that gives you the git-native feel without pretending your repo is a database.

#Why developers keep reinventing the git issue tracker

The pull toward git-native issue tracking comes from real frustrations, and they are worth naming because a good tool has to answer all of them:

• Context switching. Filing an issue means leaving the editor, waiting for a web app, typing into a form, and coming back. The Markdown-in-repo idea kills the round trip. You want that.
• Ownership. Your code is in git; leaving is a git clone away. A cloud tracker that holds your issues hostage is a switching-cost trap. You want an exit.
• Speed. A local file opens instantly. A tracker that takes two seconds to render a list is a tool you avoid, and a tool you avoid stops being the system of record.
• Agents. More and more, the thing filing and closing issues is a coding agent, not a person. Agents want one fast interface to read and write issue state, not a browser to click through.

The homegrown .issues/ folder scores well on the first three and badly on everything else. It has no real search, no shared status model, no notion of who is assigned, and it turns every parallel edit into a merge conflict. The moment a second person, or a second agent, touches it, the seams show.

#What actually solves it: the terminal, not the filesystem

The thing you were reaching for with a Markdown folder is not storage in the repo. It is a tracker you drive from where you already are: the terminal, your CI, your agent. Radial is built that way. Issues live in Radial, not in your .git directory, and we are honest about that, because pretending otherwise is how you end up with merge conflicts on your bug list. What you get instead is a first-class CLI, so the tracker feels as close as git:

# File an issue without leaving the terminal, and get its id back for scripting.
radial create "Flaky login test on CI" \
  --team ENG \
  --priority high \
  --label ci \
  --json | jq -r '.id'
# → ENG-142

That is the whole round trip the .issues/ folder was trying to buy you: no browser, no form, no waiting. And because every radial command takes --json, the tracker composes with the rest of your shell. Listing your open work is one line:

radial list --assignee me --status "in progress" --json

Search, close, import, export: same shape, same --json, all scriptable. You get the "issues at the speed of the terminal" feeling the Markdown idea promised, plus real search, real assignees, and a status model your whole team shares, without hand-rolling any of it. That composability is the point of a CLI-first design: a failing job can file its own issue from CI with the same radial create ... --json, and a cleanup script can search and close in the same shell.

#The part the repo can't give you: linking to git

Here is where storing issues as files in your repo actively works against you. The reason you want issues near the code is so the two stay connected: this branch fixes that bug, this PR closes that issue, this commit is where it landed. A folder of Markdown files can't do that automatically. It just sits next to the code, inert.

Radial connects to your repo instead of living inside it. Connect GitHub, GitLab, or Bitbucket (including self-hosted GitHub Enterprise, self-managed GitLab, and Bitbucket Data Center), and Radial links branches, pull requests, and commits to the matching issue, and transitions the issue's status as the PR moves. Open a branch named for ENG-142, and the issue knows. Merge the PR, and the issue closes. The loop between "where the work is tracked" and "where the code lands" closes without a human copying an id between two tabs, which is exactly the loop the in-repo Markdown file could never actually close.

You keep your repo. Radial is not trying to replace GitHub as your code host. It graduates the issue part into something fast and scriptable, and wires it back to the code you already have.

#Why this matters more once agents are filing the issues

The newest reason developers reach for a git-native tracker is that they are running coding agents, and they want the agent to read and write issue state without hammering a web API or clicking through a UI. Run more than one agent at once and the seams of a homegrown solution show immediately: two agents editing the same Markdown file is a merge conflict; two agents polling GitHub's API is a rate-limit problem.

A real tracker with a real API is the answer. Radial gives your agents one interface to the full issue lifecycle: the same CLI you use, plus a remote MCP server that lets Claude Code, Codex, or any MCP client create, search, comment on, and close issues directly. Point your agent at it and it files a bug the moment it notices a failing test, no browser and no shell script required. And every agent credential is a free client of the API. Agents ride free; the humans on the team are the seats, at one flat $50 per user, per year, billed annually. No per-agent charge, no AI credit meter anywhere in the product. That is the Plain Software Pledge in practice: the day Radial ships a copilot, meters your usage, or charges you for AI you didn't ask for, your subscription is free.

#FAQ

#Does GitHub have an issue tracker?

Yes. GitHub Issues is a solid, lightweight tracker built into every repository, and for a lot of projects it is genuinely enough. The pull toward something else usually starts when a flat list of issues stops scaling: you want a shared status model across teams, faster navigation, a real CLI to script it from, and one interface your coding agents can drive. That is the point where a dedicated tracker earns its place. Radial connects back to your GitHub repo, so you keep GitHub as your code host and graduate only the issue-tracking part.

#What is the best git issue tracker?

It depends on what "git" means to you. If you literally want issues stored as files inside your repository, git-native tools like git-bug embed a distributed bug tracker in git objects. If what you actually want is issues that feel close to the code, open instantly, script from the terminal, and link to your branches and PRs, then a fast tracker that integrates with git beats storing issues as files, because a folder of Markdown can't auto-link a PR to an issue or give a teammate's agent a conflict-free way to file a bug. Radial is built for that second definition.

#How do I create an issue from the command line?

With Radial, run radial create "Title of the issue" --team ENG --priority high. Add --json and the command returns the created issue as an object so your script can read the identifier back out, for example ENG-142. Install the CLI with npm i -g radial.build or brew install BrainGridAI/radial/radial. Every other command (list, search, show, close, import, export) takes --json too, so the whole tracker composes with your shell and CI.

#Can I keep my issues in my git repository?

Not in Radial, and that is deliberate. Issues in Radial live in Radial, not in your .git directory, because storing shared issue state as committed files turns every parallel edit and every agent action into a merge conflict. What you get instead is the thing you actually wanted from in-repo issues: terminal speed, a scriptable CLI, and tight git integration that links branches, PRs, and commits to issues automatically. Your data stays portable either way. One command exports the whole workspace to JSON or CSV, always available, so leaving is a radial export away.

#The short version

The developer who wants to commit a .issues/ folder to their repo has the right instinct and the wrong implementation. Issues should live close to the code, move at terminal speed, and stay connected to your branches and PRs. You do not have to hand-roll that. Radial is the fast, scriptable tracker that gives you the git-native feel, links to GitHub, GitLab, and Bitbucket, and lets your agents drive it for free.

See the full CLI, API, and MCP surface on the developers page, or read how to give your coding agent access to the tracker over MCP.