# Renga — File-Based Issue Management

[![CI](https://github.com/shishidosoichiro/renga/actions/workflows/ci.yml/badge.svg)](https://github.com/shishidosoichiro/renga/actions/workflows/ci.yml)
[![Coverage](https://codecov.io/gh/shishidosoichiro/renga/branch/main/graph/badge.svg)](https://codecov.io/gh/shishidosoichiro/renga)
[![Crates.io](https://img.shields.io/crates/v/renga.svg)](https://crates.io/crates/renga)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

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](README.ja.md)

## Quick start

```sh
# 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

```text
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:

```sh
# 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
```

| Command | Description |
|---|---|
| `/renga [create] <title>` | Create an issue |
| `/renga done <ID>...` | Mark as done |
| `/renga pending <ID>...` | Put on hold |
| `/renga in-progress <ID>...` | Mark as in-progress |
| `/renga reopen <ID>...` | Reopen |
| `/renga update <ID> ...` | Update issue fields |
| `/renga list` | List open and pending issues |
| `/renga show <ID>` | Show details |

## 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.

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

Or install from [crates.io](https://crates.io/crates/renga):

```sh
cargo install renga
```

## Commands

| Command | Description |
|---|---|
| `renga init` | Initialize the issues directory |
| `renga create <title> [--id <N>] [--slug <slug>] [--priority high\|medium\|low] [--area <area>] [--body <text\|-\>] [--milestone <milestone>] [--assignee <assignee>] [--label <label>]... [--dir=true\|false]` | Create an issue (`--body -` reads from stdin; `--dir=true` uses directory layout) |
| `renga create --json` | Create an issue from a JSON object on stdin |
| `renga done <ID>...` | Mark an issue as done |
| `renga pending <ID>...` | Put an issue on hold |
| `renga in-progress <ID>...` | Mark an issue as in-progress |
| `renga reopen <ID>...` | Reopen a closed issue |
| `renga list [--status open\|pending\|in-progress\|done\|unknown] [--area <area>] [--label <label>] [--milestone <milestone>] [--assignee <assignee>] [--json]` | List issues |
| `renga show <ID> [--json]` | Show issue details |
| `renga edit <ID>` | Open issue in `$EDITOR` (human) |
| `renga update <ID> [<title>] [--priority ...] [--area ...] [--status ...] [--milestone ...] [--assignee ...] [--label ...]... [--add-label ...]... [--remove-label ...]... [--body <text\|->]` | Update issue fields (AI/scripts) |
| `renga update <ID> --dir=true\|false` | Convert issue between flat-file and directory layout |
| `renga update <ID> --json` | Update issue fields from a JSON object on stdin |
| `renga info` | Show project root, issues directory, config location, and current settings |

Pass an empty string to `--milestone` or `--assignee` to remove the field: `renga update 1 --assignee ''`.
| `renga migrate` | Move issues from flat layout to per-status directories |
| `renga validate [ID]... [--auto-correct]` | Check issues for schema/status errors, duplicate IDs, and status directory mismatches |
| `renga completions bash\|zsh\|fish` | Print shell completion script |
| `renga help [command]` | Show help |

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.

```sh
# 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`:

```sh
eval "$(renga completions bash)"
```

**zsh** — add to `~/.zshrc`:

```sh
source <(renga completions zsh)
```

**fish** — install once:

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

## Customization

Place `.renga.yml` in the project root.

```yaml
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"
```

## Development

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

[spec.md](spec.md) is the authoritative specification for file format and naming rules.
