renga：用 Markdown 文件管理 issue 的 CLI 工具

Renga — File-Based Issue Management

renga is a CLI tool for managing issues as files. Plain Markdown, so your editor, grep, git, and AI agents can all read and write them. renga create "title" creates an issue; renga done 1 closes it.

Japanese version: README.ja.md

Quick start

# 1. Install
bash <(curl -fsSL https://raw.githubusercontent.com/shishidosoichiro/renga/main/install.sh)

# 2. Initialize (anywhere — no git repo required)
renga init

# 3. Create your first issue
renga create "My first task"

That's it. Issue files appear in issues/.

Recommended workflow with AI agents

1. Create an issue for the task
   renga create "Add input validation" --area core

2. Agent runs renga list before starting work

3. Agent appends decisions and constraints to the issue body under ## Notes

4. After implementation, run renga validate

5. Close the issue alongside the fix commit
   renga done 1
   git add issues/ src/
   git commit -m "feat: add input validation (#1)"

Issue files and code changes land in the same commit — the git history tells the full story.

Claude Code integration

Claude can create issues as it works, close them when done, and keep the list current — all without interrupting the coding flow.

Install the skill to manage issues with /renga inside Claude Code:

# With Node.js
npx skills add shishidosoichiro/renga

# Without Node.js
mkdir -p ~/.claude/skills/renga
curl -fsSL https://raw.githubusercontent.com/shishidosoichiro/renga/main/skills/renga/SKILL.md \
  -o ~/.claude/skills/renga/SKILL.md

Then use it directly in any Claude Code session:

/renga create "Add input validation"
/renga list
/renga update 3 --add-label bug
/renga done 3

Before you reach for GitHub Issues

Renga is for solo developers and small teams who want to start tracking work immediately, without setting up an external service first.

• Using an AI coding tool (like Claude Code) and want issue management without leaving the terminal
• Starting a project before setting up GitHub Issues
• Working offline or on a private machine with no internet access
• Want issues to live in the same git history as the code that fixes them

If you need comments, assignments, notifications, or a web UI for non-engineers, reach for GitHub Issues or Linear instead. Renga is intentionally minimal.

How it's different

• AI-native: Issue files are plain Markdown, so LLMs can read and write them directly. An agent can open an issue, make a fix, and close it — all in one session.
• Works offline: No network connection, no account, no API token. renga init is all the setup there is.
• No config required: Drop it into any directory. No project configuration or external service needed to get started.
• Lives with your code: Issue files are just files — open them in any editor, search with grep, and commit them to git alongside the code that fixes them.
• Your data, your format: Nothing to export. The files are readable plain text whether you keep using renga or not.

Installation

Download and run the install script. It fetches the pre-built binary for your platform from GitHub Releases.

bash <(curl -fsSL https://raw.githubusercontent.com/shishidosoichiro/renga/main/install.sh)

Or install from crates.io:

cargo install renga

Commands

Pass an empty string to --milestone or --assignee to remove the field: renga update 1 --assignee ''.

Frontmatter status is authoritative. If an active issue is accidentally stored under done/, active-issue commands still operate on it, print a warning, and recommend renga validate <ID> --auto-correct. Normal status: done issues must be reopened before status-transition commands (done, pending, in-progress, reopen) can change them again — but update and edit can still edit a done issue's fields (labels, assignee, milestone, body, title) without reopening it first.

# JSON output can be piped to jq
renga list --json | jq '.[] | select(.area == "auth")'

# JSON input is useful for scripts and AI agents
printf '%s\n' '{"title":"Bug","area":"cli","labels":["bug"],"body":"details"}' | renga create --json
printf '%s\n' '{"priority":"high","add_labels":["urgent"]}' | renga update 1 --json

How renga finds your issues

When you run any renga command, it walks up from the current directory toward the filesystem root, stopping at the first directory that matches either of these conditions:

1. A .renga.yml file is present — the issues_dir value in that file is used as the issues directory (default: issues)
2. An issues/ subdirectory is present

This means you can run renga from any subdirectory of your project and it will find the right issues directory automatically. If nothing is found, renga falls back to issues/ relative to the current directory.

Shell completions

Enable tab completion for subcommands, flags, and issue IDs.

bash — add to ~/.bashrc:

eval "$(renga completions bash)"

zsh — add to ~/.zshrc:

source <(renga completions zsh)

fish — install once:

renga completions fish > ~/.config/fish/completions/renga.fish

Customization

Place .renga.yml in the project root.

issues_dir: issues    # default: issues

area_order:           # display order in the list (alphabetical if omitted)
  - backend
  - frontend
  - infra
  - misc

area_labels:          # display names for areas
  backend: "Backend"
  frontend: "Frontend"
  infra: "Infrastructure"
  misc: "Other"

group_by:             # nest issues under an area directory (issues/<area>/<status>/...)
  - area

defaults:             # default values applied to `create`
  dir: false          # default for `create --dir`
  labels: [inbox]     # labels added to every new issue (skip with --no-default-labels)

group_by: [area] adds an area directory level above status, so working in a single project's area doesn't mix files from other areas on disk. defaults.dir: true makes create produce directory-based issues by default (handy if you regularly attach files to issues). See spec.md for details, including how to migrate existing issues with renga migrate.

cargo test            # run tests
cargo test --doc      # run doctests
cargo clippy --all-targets -- -D warnings
cargo fmt --check
cargo doc --no-deps --open

spec.md is the authoritative specification for file format and naming rules.