@ugudlado1/backlog-darwin-arm64 2.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +325 -0
- package/backlog +0 -0
- package/package.json +8 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Backlog.md
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,325 @@
|
|
|
1
|
+
<h1 align="center">Backlog.md</h1>
|
|
2
|
+
<p align="center">Markdown‑native Task Manager & Kanban visualizer for any Git repository</p>
|
|
3
|
+
|
|
4
|
+
<p align="center">
|
|
5
|
+
<code>npm i -g backlog.md</code> or <code>bun add -g backlog.md</code> or <code>nix run github:ugudlado/Backlog.md</code>
|
|
6
|
+
</p>
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
> **Backlog.md** turns any folder with a Git repo into a **self‑contained project board**
|
|
14
|
+
> powered by plain Markdown files and a zero‑config CLI.
|
|
15
|
+
> Built for **spec‑driven AI development** — structure your tasks so AI agents deliver predictable results.
|
|
16
|
+
|
|
17
|
+
## Features
|
|
18
|
+
|
|
19
|
+
* 📝 **Markdown-native tasks** -- manage every issue as a plain `.md` file
|
|
20
|
+
|
|
21
|
+
* 🤖 **AI-Ready** -- Works with Claude Code, Gemini CLI, Codex, Kiro & any other MCP or CLI compatible AI assistants
|
|
22
|
+
|
|
23
|
+
* 📊 **Instant terminal Kanban** -- `backlog board` paints a live board in your shell
|
|
24
|
+
|
|
25
|
+
* 🌐 **Modern web interface** -- `backlog server` launches a sleek web UI for visual task management; `backlog service` runs it as a launchd service on macOS
|
|
26
|
+
|
|
27
|
+
* 🔍 **Powerful search** -- fuzzy search across tasks, docs & decisions with `backlog search`
|
|
28
|
+
|
|
29
|
+
* 📋 **Rich query commands** -- view, list, filter, or archive tasks with ease
|
|
30
|
+
* ✅ **Definition of Done defaults** -- add a reusable checklist to every new task
|
|
31
|
+
|
|
32
|
+
* 📤 **Board export** -- `backlog board export` creates shareable markdown reports
|
|
33
|
+
|
|
34
|
+
* 🔒 **100 % private & offline** -- backlog lives entirely inside your repo and you can manage everything locally
|
|
35
|
+
|
|
36
|
+
* 💻 **Cross-platform** -- runs on macOS, Linux, and Windows
|
|
37
|
+
|
|
38
|
+
* 🆓 **MIT-licensed & open-source** -- free for personal or commercial use
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
## <img src="./.github/5-minute-tour-256.png" alt="Getting started" width="28" height="28" align="center"> Getting started
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
# Install
|
|
47
|
+
bun i -g backlog.md
|
|
48
|
+
# or: npm i -g backlog.md
|
|
49
|
+
|
|
50
|
+
# Configure the global store once (where all projects live)
|
|
51
|
+
mkdir -p ~/.config/backlog
|
|
52
|
+
echo 'globalStore: ~/.config/backlog/projects' > ~/.config/backlog/config.yml
|
|
53
|
+
|
|
54
|
+
# Create a project (you can run this from anywhere)
|
|
55
|
+
backlog init "My Awesome Project"
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
The init wizard will ask how you want to connect AI tools:
|
|
59
|
+
- **MCP connector** (recommended) — auto-configures Claude Code, Codex, Gemini CLI, Kiro or Cursor and adds workflow instructions for your agents.
|
|
60
|
+
- **CLI commands** — creates instruction files (CLAUDE.md, AGENTS.md, etc.) so agents use Backlog via CLI.
|
|
61
|
+
- **Skip** — no AI setup; use Backlog.md purely as a task manager.
|
|
62
|
+
|
|
63
|
+
Every project is stored as a slot in the configured **global store** (`globalStore` in `~/.config/backlog/config.yml`) — one directory per project, keyed by name, not tied to any repo. Tasks remain human-readable Markdown files (e.g. `task-10 - Add core search functionality.md`). List and switch projects with `backlog project list` / `backlog project switch <name>`, or target one per command with `--project <name>`.
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
### Working with AI agents
|
|
68
|
+
|
|
69
|
+
This is the recommended flow for Claude Code, Codex, Gemini CLI, Kiro and similar tools — following the **spec‑driven AI development** approach.
|
|
70
|
+
After running `backlog init` and choosing the MCP or CLI integration, work in this loop:
|
|
71
|
+
|
|
72
|
+
**Step 1 — Describe your idea.** Tell the agent what you want to build and ask it to split the work into small tasks with clear descriptions and acceptance criteria.
|
|
73
|
+
|
|
74
|
+
**🤖 Ask your AI Agent:**
|
|
75
|
+
> I want to add a search feature to the web view that searches tasks, docs, and decisions. Please decompose this into small Backlog.md tasks.
|
|
76
|
+
|
|
77
|
+
> [!NOTE]
|
|
78
|
+
> **Review checkpoint #1** — read the task descriptions and acceptance criteria.
|
|
79
|
+
|
|
80
|
+
**Step 2 — One task at a time.** Work on a single task per agent session, one PR per task. Good task splitting means each session can work independently without conflicts. Make sure each task is small enough to complete in a single conversation. You want to avoid running out of context window.
|
|
81
|
+
|
|
82
|
+
**Step 3 — Plan before coding.** Ask the agent to research and write an implementation plan in the task. Do this right before implementation so the plan reflects the current state of the codebase.
|
|
83
|
+
|
|
84
|
+
**🤖 Ask your AI Agent:**
|
|
85
|
+
> Work on BACK-10 only. Research the codebase and write an implementation plan in the task. Wait for my approval before coding.
|
|
86
|
+
|
|
87
|
+
> [!NOTE]
|
|
88
|
+
> **Review checkpoint #2** — read the plan. Does the approach make sense? Approve it or ask the agent to revise.
|
|
89
|
+
|
|
90
|
+
**Step 4 — Implement and verify.** Let the agent implement the task.
|
|
91
|
+
|
|
92
|
+
> [!NOTE]
|
|
93
|
+
> **Review checkpoint #3** — review the code, run tests, check linting, and verify the results match your expectations.
|
|
94
|
+
|
|
95
|
+
If the output is not good enough: clear the plan/notes/final summary, refine the task description and acceptance criteria, and run the task again in a fresh session.
|
|
96
|
+
|
|
97
|
+
---
|
|
98
|
+
|
|
99
|
+
### Working without AI agents
|
|
100
|
+
|
|
101
|
+
Use Backlog.md as a standalone task manager from the terminal or browser.
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
# Create and refine tasks
|
|
105
|
+
backlog task create "Render markdown as kanban"
|
|
106
|
+
backlog task edit BACK-1 -d "Detailed context" --ac "Clear acceptance criteria"
|
|
107
|
+
|
|
108
|
+
# Track work
|
|
109
|
+
backlog task list -s "To Do"
|
|
110
|
+
backlog search "kanban"
|
|
111
|
+
backlog board
|
|
112
|
+
|
|
113
|
+
# Work visually in the browser
|
|
114
|
+
backlog server --open
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
You can switch between AI-assisted and manual workflows at any time — both operate on the same Markdown task files. It is recommended to modify tasks via Backlog.md commands (CLI/MCP/Web) rather than editing task files manually, so field types and metadata stay consistent. Tasks can record project-root-relative modified files and later be found with `backlog search --modified-file src/path.ts --plain`.
|
|
118
|
+
|
|
119
|
+
**Learn more:** [CLI reference](CLI-INSTRUCTIONS.md) | [Advanced configuration](ADVANCED-CONFIG.md)
|
|
120
|
+
|
|
121
|
+
---
|
|
122
|
+
|
|
123
|
+
## <img src="./.github/web-interface-256.png" alt="Web Interface" width="28" height="28" align="center"> Web Interface
|
|
124
|
+
|
|
125
|
+
Launch a modern, responsive web interface for visual task management:
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
# Start the web server (foreground; Ctrl+C to stop)
|
|
129
|
+
backlog server
|
|
130
|
+
|
|
131
|
+
# Open the UI in a browser after start
|
|
132
|
+
backlog server --open
|
|
133
|
+
|
|
134
|
+
# Custom port
|
|
135
|
+
backlog server --port 8080
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
### Run as a service (macOS)
|
|
139
|
+
|
|
140
|
+
`backlog service` runs the Web UI under launchd so it starts on login and restarts on crash.
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
backlog service start # install plist + start on port 6420
|
|
144
|
+
backlog service status # check state, pid, program
|
|
145
|
+
backlog service logs # tail stdout/stderr logs
|
|
146
|
+
backlog service stop # stop, leave plist on disk
|
|
147
|
+
backlog service uninstall # stop and remove plist
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
The service serves the current project (recorded in `~/.config/backlog/projects.yml`). Switch projects from the project switcher in the web UI; the selection survives restarts.
|
|
151
|
+
|
|
152
|
+
Linux (systemd) and Windows (Task Scheduler / NSSM) recipes live in [Running Backlog.md as a Service](SERVICE.md).
|
|
153
|
+
|
|
154
|
+
**Features:**
|
|
155
|
+
- Interactive Kanban board with drag-and-drop
|
|
156
|
+
- Task creation and editing with rich forms
|
|
157
|
+
- Interactive acceptance criteria editor with checklists
|
|
158
|
+
- Real-time updates across all views
|
|
159
|
+
- Responsive design for desktop and mobile
|
|
160
|
+
- Task archiving with confirmation dialogs
|
|
161
|
+
- Seamless CLI integration - all changes sync with markdown files
|
|
162
|
+
|
|
163
|
+
|
|
164
|
+
|
|
165
|
+
---
|
|
166
|
+
|
|
167
|
+
## 🔧 MCP Integration (Model Context Protocol)
|
|
168
|
+
|
|
169
|
+
The easiest way to connect Backlog.md to AI coding assistants like Claude Code, Codex, Gemini CLI and Kiro is via the MCP protocol.
|
|
170
|
+
You can run `backlog init` (even if you already initialized Backlog.md) to set up MCP integration automatically, or follow the manual steps below.
|
|
171
|
+
|
|
172
|
+
### Client guides
|
|
173
|
+
|
|
174
|
+
<details>
|
|
175
|
+
<summary><strong>Claude Code</strong></summary>
|
|
176
|
+
|
|
177
|
+
```bash
|
|
178
|
+
claude mcp add backlog --scope user -- backlog mcp start
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
</details>
|
|
182
|
+
|
|
183
|
+
<details>
|
|
184
|
+
<summary><strong>Codex</strong></summary>
|
|
185
|
+
|
|
186
|
+
```bash
|
|
187
|
+
codex mcp add backlog backlog mcp start
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
</details>
|
|
191
|
+
|
|
192
|
+
<details>
|
|
193
|
+
<summary><strong>Gemini CLI</strong></summary>
|
|
194
|
+
|
|
195
|
+
```bash
|
|
196
|
+
gemini mcp add backlog -s user backlog mcp start
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
</details>
|
|
200
|
+
|
|
201
|
+
<details>
|
|
202
|
+
<summary><strong>Kiro</strong></summary>
|
|
203
|
+
|
|
204
|
+
```bash
|
|
205
|
+
kiro-cli mcp add --scope global --name backlog --command backlog --args mcp,start
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
</details>
|
|
209
|
+
|
|
210
|
+
Use the shared `backlog` server name everywhere – the MCP server auto-detects whether the current directory is initialized and falls back to `backlog://init-required` when needed.
|
|
211
|
+
|
|
212
|
+
### Manual config
|
|
213
|
+
|
|
214
|
+
```json
|
|
215
|
+
{
|
|
216
|
+
"mcpServers": {
|
|
217
|
+
"backlog": {
|
|
218
|
+
"command": "backlog",
|
|
219
|
+
"args": ["mcp", "start"],
|
|
220
|
+
"env": {
|
|
221
|
+
"BACKLOG_CWD": "/absolute/path/to/your/project"
|
|
222
|
+
}
|
|
223
|
+
}
|
|
224
|
+
}
|
|
225
|
+
}
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
If your IDE can't set the process working directory for MCP servers, set `BACKLOG_CWD` as shown above.
|
|
229
|
+
If your IDE supports custom args but not env vars, you can also use `["mcp", "start", "--cwd", "/absolute/path/to/your/project"]`.
|
|
230
|
+
|
|
231
|
+
> [!IMPORTANT]
|
|
232
|
+
> When adding the MCP server manually, you should add some extra instructions in your CLAUDE.md/AGENTS.md files to inform the agent about Backlog.md.
|
|
233
|
+
> This step is not required when using `backlog init` as it adds these instructions automatically.
|
|
234
|
+
> Backlog.md's instructions for agents are available at [`/src/guidelines/mcp/agent-nudge.md`](/src/guidelines/mcp/agent-nudge.md).
|
|
235
|
+
|
|
236
|
+
|
|
237
|
+
Once connected, agents can read the Backlog.md workflow instructions via the resource `backlog://docs/task-workflow`.
|
|
238
|
+
Use `/mcp` command in your AI tool (Claude Code, Codex, Kiro) to verify if the connection is working.
|
|
239
|
+
|
|
240
|
+
---
|
|
241
|
+
|
|
242
|
+
## <img src="./.github/cli-reference-256.png" alt="CLI Reference" width="28" height="28" align="center"> CLI reference
|
|
243
|
+
|
|
244
|
+
Full command reference — task management, search, board, docs, decisions, and more: **[CLI-INSTRUCTIONS.md](CLI-INSTRUCTIONS.md)**
|
|
245
|
+
|
|
246
|
+
Quick examples: `backlog task create`, `backlog task list`, `backlog task edit`, `backlog search`, `backlog board`, `backlog server`, `backlog service start`.
|
|
247
|
+
|
|
248
|
+
Full help: `backlog --help`
|
|
249
|
+
|
|
250
|
+
---
|
|
251
|
+
|
|
252
|
+
## <img src="./.github/configuration-256.png" alt="Configuration" width="28" height="28" align="center"> Configuration
|
|
253
|
+
|
|
254
|
+
Backlog.md merges the following layers (highest → lowest):
|
|
255
|
+
|
|
256
|
+
1. CLI flags
|
|
257
|
+
2. Project config file (`config.yml` inside the project's global-store slot)
|
|
258
|
+
3. Built‑ins
|
|
259
|
+
|
|
260
|
+
### Interactive wizard (`backlog init` advanced settings)
|
|
261
|
+
|
|
262
|
+
When you run `backlog init` and answer "Yes" at the advanced settings prompt, an interactive wizard walks through the project configuration surface:
|
|
263
|
+
- Definition of Done defaults: interactively add/remove/reorder/clear project-level `definition_of_done` checklist items.
|
|
264
|
+
- Web UI defaults: choose `defaultPort` and whether `autoOpenBrowser` should run.
|
|
265
|
+
|
|
266
|
+
Answering "No" applies the safe defaults that ship with Backlog.md (`defaultPort=6420`, `autoOpenBrowser=true`). When you revisit `backlog init`, the wizard pre-populates prompts with your current values so you can adjust only what changed.
|
|
267
|
+
|
|
268
|
+
Projects live in the global store, not in a Git repo. CLI, Web, and MCP workflows never depend on a Git repository.
|
|
269
|
+
|
|
270
|
+
To change project config later, use the Web UI Settings page or edit the project config file directly (see below).
|
|
271
|
+
|
|
272
|
+
### Machine-level config (`~/.config/backlog.md/config.yml`)
|
|
273
|
+
|
|
274
|
+
Some settings live outside any project and apply across all repositories on the machine. Create or edit `~/.config/backlog.md/config.yml` directly — the CLI does not write to this file.
|
|
275
|
+
|
|
276
|
+
**`globalStore`** — redirect all backlog storage to a single external directory instead of creating a `backlog/` folder inside each code repo:
|
|
277
|
+
|
|
278
|
+
```yaml
|
|
279
|
+
# ~/.config/backlog.md/config.yml
|
|
280
|
+
globalStore: /path/to/my/backlog-store
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
When `globalStore` is set:
|
|
284
|
+
- `backlog init` creates `<globalStore>/<repo-basename>/` instead of `<repo>/backlog/`.
|
|
285
|
+
- All task reads and writes go to the external slot — the code repo is never touched.
|
|
286
|
+
- `git log` in your code repo stays clean.
|
|
287
|
+
- The `globalStore` directory must exist before running `backlog init`. Backlog.md will not create it.
|
|
288
|
+
- If a local `backlog/` or `.backlog/` folder already exists in the repo, it wins and the global store is ignored for that project.
|
|
289
|
+
|
|
290
|
+
The current `globalStore` value (or `(not set)`) is whatever you have written in `~/.config/backlog.md/config.yml`.
|
|
291
|
+
|
|
292
|
+
To override the config directory path (useful in tests or CI), set the `BACKLOG_MACHINE_CONFIG_DIR` environment variable.
|
|
293
|
+
|
|
294
|
+
### Definition of Done defaults
|
|
295
|
+
|
|
296
|
+
Set project-wide DoD items during `backlog init` advanced setup, in the Web UI (Settings → Definition of Done Defaults), or by editing the project config file directly:
|
|
297
|
+
|
|
298
|
+
```yaml
|
|
299
|
+
definition_of_done:
|
|
300
|
+
- Tests pass
|
|
301
|
+
- Documentation updated
|
|
302
|
+
- No regressions introduced
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
When a project uses root config discovery, edit `backlog.config.yml` instead of `backlog/config.yml`.
|
|
306
|
+
|
|
307
|
+
These items are added to every new task by default. You can add more on create with `--dod`, or disable defaults per task with `--no-dod-defaults`.
|
|
308
|
+
|
|
309
|
+
For the full configuration reference (all options and detailed notes), see **[ADVANCED-CONFIG.md](ADVANCED-CONFIG.md)**.
|
|
310
|
+
|
|
311
|
+
---
|
|
312
|
+
|
|
313
|
+
## 🌐 Community Tools
|
|
314
|
+
|
|
315
|
+
- **[vscode-backlog-md](https://marketplace.visualstudio.com/items?itemName=ysamlan.vscode-backlog-md)** - VS Code extension with issues panel, kanban view, and editing. ([ysamlan/vscode-backlog-md](https://github.com/ysamlan/vscode-backlog-md))
|
|
316
|
+
|
|
317
|
+
---
|
|
318
|
+
|
|
319
|
+
### Acknowledgments
|
|
320
|
+
|
|
321
|
+
Forked from [MrLesk/Backlog.md](https://github.com/MrLesk/Backlog.md) by Alex Gavrilescu — thanks for the original work.
|
|
322
|
+
|
|
323
|
+
### License
|
|
324
|
+
|
|
325
|
+
Backlog.md is released under the **MIT License** – do anything, just give credit. See [LICENSE](LICENSE).
|
package/backlog
ADDED
|
Binary file
|
package/package.json
ADDED