···11+# Beads - AI-Native Issue Tracking
22+33+Welcome to Beads! This repository uses **Beads** for issue tracking - a modern, AI-native tool designed to live directly in your codebase alongside your code.
44+55+## What is Beads?
66+77+Beads is issue tracking that lives in your repo, making it perfect for AI coding agents and developers who want their issues close to their code. No web UI required - everything works through the CLI and integrates seamlessly with git.
88+99+**Learn more:** [github.com/steveyegge/beads](https://github.com/steveyegge/beads)
1010+1111+## Quick Start
1212+1313+### Essential Commands
1414+1515+```bash
1616+# Create new issues
1717+bd create "Add user authentication"
1818+1919+# View all issues
2020+bd list
2121+2222+# View issue details
2323+bd show <issue-id>
2424+2525+# Update issue status
2626+bd update <issue-id> --status in_progress
2727+bd update <issue-id> --status done
2828+2929+# Sync with git remote
3030+bd sync
3131+```
3232+3333+### Working with Issues
3434+3535+Issues in Beads are:
3636+- **Git-native**: Stored in `.beads/issues.jsonl` and synced like code
3737+- **AI-friendly**: CLI-first design works perfectly with AI coding agents
3838+- **Branch-aware**: Issues can follow your branch workflow
3939+- **Always in sync**: Auto-syncs with your commits
4040+4141+## Why Beads?
4242+4343+✨ **AI-Native Design**
4444+- Built specifically for AI-assisted development workflows
4545+- CLI-first interface works seamlessly with AI coding agents
4646+- No context switching to web UIs
4747+4848+🚀 **Developer Focused**
4949+- Issues live in your repo, right next to your code
5050+- Works offline, syncs when you push
5151+- Fast, lightweight, and stays out of your way
5252+5353+🔧 **Git Integration**
5454+- Automatic sync with git commits
5555+- Branch-aware issue tracking
5656+- Intelligent JSONL merge resolution
5757+5858+## Get Started with Beads
5959+6060+Try Beads in your own projects:
6161+6262+```bash
6363+# Install Beads
6464+curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
6565+6666+# Initialize in your repo
6767+bd init
6868+6969+# Create your first issue
7070+bd create "Try out Beads"
7171+```
7272+7373+## Learn More
7474+7575+- **Documentation**: [github.com/steveyegge/beads/docs](https://github.com/steveyegge/beads/tree/main/docs)
7676+- **Quick Start Guide**: Run `bd quickstart`
7777+- **Examples**: [github.com/steveyegge/beads/examples](https://github.com/steveyegge/beads/tree/main/examples)
7878+7979+---
8080+8181+*Beads: Issue tracking that moves at the speed of thought* ⚡
+62
.beads/config.yaml
···11+# Beads Configuration File
22+# This file configures default behavior for all bd commands in this repository
33+# All settings can also be set via environment variables (BD_* prefix)
44+# or overridden with command-line flags
55+66+# Issue prefix for this repository (used by bd init)
77+# If not set, bd init will auto-detect from directory name
88+# Example: issue-prefix: "myproject" creates issues like "myproject-1", "myproject-2", etc.
99+# issue-prefix: ""
1010+1111+# Use no-db mode: load from JSONL, no SQLite, write back after each command
1212+# When true, bd will use .beads/issues.jsonl as the source of truth
1313+# instead of SQLite database
1414+# no-db: false
1515+1616+# Disable daemon for RPC communication (forces direct database access)
1717+# no-daemon: false
1818+1919+# Disable auto-flush of database to JSONL after mutations
2020+# no-auto-flush: false
2121+2222+# Disable auto-import from JSONL when it's newer than database
2323+# no-auto-import: false
2424+2525+# Enable JSON output by default
2626+# json: false
2727+2828+# Default actor for audit trails (overridden by BD_ACTOR or --actor)
2929+# actor: ""
3030+3131+# Path to database (overridden by BEADS_DB or --db)
3232+# db: ""
3333+3434+# Auto-start daemon if not running (can also use BEADS_AUTO_START_DAEMON)
3535+# auto-start-daemon: true
3636+3737+# Debounce interval for auto-flush (can also use BEADS_FLUSH_DEBOUNCE)
3838+# flush-debounce: "5s"
3939+4040+# Git branch for beads commits (bd sync will commit to this branch)
4141+# IMPORTANT: Set this for team projects so all clones use the same sync branch.
4242+# This setting persists across clones (unlike database config which is gitignored).
4343+# Can also use BEADS_SYNC_BRANCH env var for local override.
4444+# If not set, bd sync will require you to run 'bd config set sync.branch <branch>'.
4545+# sync-branch: "beads-sync"
4646+4747+# Multi-repo configuration (experimental - bd-307)
4848+# Allows hydrating from multiple repositories and routing writes to the correct JSONL
4949+# repos:
5050+# primary: "." # Primary repo (where this database lives)
5151+# additional: # Additional repos to hydrate from (read-only)
5252+# - ~/beads-planning # Personal planning repo
5353+# - ~/work-planning # Work planning repo
5454+5555+# Integration settings (access with 'bd config get/set')
5656+# These are stored in the database, not in this file:
5757+# - jira.url
5858+# - jira.project
5959+# - linear.url
6060+# - linear.api-key
6161+# - github.org
6262+# - github.repo
···11+---
22+description: Use Bun instead of Node.js, npm, pnpm, or vite.
33+globs: "*.ts, *.tsx, *.html, *.css, *.js, *.jsx, package.json"
44+alwaysApply: false
55+---
66+77+## Issue Tracking with bd (beads)
88+99+**IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.
1010+1111+### Why bd?
1212+1313+- Dependency-aware: Track blockers and relationships between issues
1414+- Git-friendly: Auto-syncs to JSONL for version control
1515+- Agent-optimized: JSON output, ready work detection, discovered-from links
1616+- Prevents duplicate tracking systems and confusion
1717+1818+### Quick Start
1919+2020+**Check for ready work:**
2121+```bash
2222+bd ready --json
2323+```
2424+2525+**Create new issues:**
2626+```bash
2727+bd create "Issue title" -t bug|feature|task -p 0-4 --json
2828+bd create "Issue title" -p 1 --deps discovered-from:bd-123 --json
2929+bd create "Subtask" --parent <epic-id> --json # Hierarchical subtask (gets ID like epic-id.1)
3030+```
3131+3232+**Claim and update:**
3333+```bash
3434+bd update bd-42 --status in_progress --json
3535+bd update bd-42 --priority 1 --json
3636+```
3737+3838+**Complete work:**
3939+```bash
4040+bd close bd-42 --reason "Completed" --json
4141+```
4242+4343+### Issue Types
4444+4545+- `bug` - Something broken
4646+- `feature` - New functionality
4747+- `task` - Work item (tests, docs, refactoring)
4848+- `epic` - Large feature with subtasks
4949+- `chore` - Maintenance (dependencies, tooling)
5050+5151+### Priorities
5252+5353+- `0` - Critical (security, data loss, broken builds)
5454+- `1` - High (major features, important bugs)
5555+- `2` - Medium (default, nice-to-have)
5656+- `3` - Low (polish, optimization)
5757+- `4` - Backlog (future ideas)
5858+5959+### Workflow for AI Agents
6060+6161+1. **Check ready work**: `bd ready` shows unblocked issues
6262+2. **Claim your task**: `bd update <id> --status in_progress`
6363+3. **Work on it**: Implement, test, document
6464+4. **Discover new work?** Create linked issue:
6565+ - `bd create "Found bug" -p 1 --deps discovered-from:<parent-id>`
6666+5. **Complete**: `bd close <id> --reason "Done"`
6767+6. **Commit together**: Always commit the `.beads/issues.jsonl` file together with the code changes so issue state stays in sync with code state
6868+6969+### Auto-Sync
7070+7171+bd automatically syncs with git:
7272+- Exports to `.beads/issues.jsonl` after changes (5s debounce)
7373+- Imports from JSONL when newer (e.g., after `git pull`)
7474+- No manual export/import needed!
7575+7676+### Managing AI-Generated Planning Documents
7777+7878+AI assistants often create planning and design documents during development:
7979+- PLAN.md, IMPLEMENTATION.md, ARCHITECTURE.md
8080+- DESIGN.md, CODEBASE_SUMMARY.md, INTEGRATION_PLAN.md
8181+- TESTING_GUIDE.md, TECHNICAL_DESIGN.md, and similar files
8282+8383+**Best Practice: Use a dedicated directory for these ephemeral files**
8484+8585+**Recommended approach:**
8686+- Create a `history/` directory in the project root
8787+- Store ALL AI-generated planning/design docs in `history/`
8888+- Keep the repository root clean and focused on permanent project files
8989+- Only access `history/` when explicitly asked to review past planning
9090+9191+### CLI Help
9292+9393+Run `bd <command> --help` to see all available flags for any command.
9494+For example: `bd create --help` shows `--parent`, `--deps`, `--assignee`, etc.
9595+9696+### Important Rules
9797+9898+- Use bd for ALL task tracking
9999+- Always use `--json` flag for programmatic use
100100+- Link discovered work with `discovered-from` dependencies
101101+- Check `bd ready` before asking "what should I work on?"
102102+- Store AI planning docs in `history/` directory
103103+- Run `bd <cmd> --help` to discover available flags
104104+- Do NOT create markdown TODO lists
105105+- Do NOT use external issue trackers
106106+- Do NOT duplicate tracking systems
107107+- Do NOT clutter repo root with planning documents
108108+109109+---
110110+111111+## Bun Runtime
112112+113113+Default to using Bun instead of Node.js.
114114+115115+- Use `bun <file>` instead of `node <file>` or `ts-node <file>`
116116+- Use `bun test` instead of `jest` or `vitest`
117117+- Use `bun build <file.html|file.ts|file.css>` instead of `webpack` or `esbuild`
118118+- Use `bun install` instead of `npm install` or `yarn install` or `pnpm install`
119119+- Use `bun run <script>` instead of `npm run <script>` or `yarn run <script>` or `pnpm run <script>`
120120+- Use `bunx <package> <command>` instead of `npx <package> <command>`
121121+- Bun automatically loads .env, so don't use dotenv.
122122+123123+## APIs
124124+125125+- `Bun.serve()` supports WebSockets, HTTPS, and routes. Don't use `express`.
126126+- `bun:sqlite` for SQLite. Don't use `better-sqlite3`.
127127+- `Bun.redis` for Redis. Don't use `ioredis`.
128128+- `Bun.sql` for Postgres. Don't use `pg` or `postgres.js`.
129129+- `WebSocket` is built-in. Don't use `ws`.
130130+- Prefer `Bun.file` over `node:fs`'s readFile/writeFile
131131+- Bun.$`ls` instead of execa.
132132+133133+## Testing
134134+135135+Use `bun test` to run tests.
136136+137137+```ts#index.test.ts
138138+import { test, expect } from "bun:test";
139139+140140+test("hello world", () => {
141141+ expect(1).toBe(1);
142142+});
143143+```
144144+145145+## Frontend
146146+147147+Use HTML imports with `Bun.serve()`. Don't use `vite`. HTML imports fully support React, CSS, Tailwind.
148148+149149+Server:
150150+151151+```ts#index.ts
152152+import index from "./index.html"
153153+154154+Bun.serve({
155155+ routes: {
156156+ "/": index,
157157+ "/api/users/:id": {
158158+ GET: (req) => {
159159+ return new Response(JSON.stringify({ id: req.params.id }));
160160+ },
161161+ },
162162+ },
163163+ // optional websocket support
164164+ websocket: {
165165+ open: (ws) => {
166166+ ws.send("Hello, world!");
167167+ },
168168+ message: (ws, message) => {
169169+ ws.send(message);
170170+ },
171171+ close: (ws) => {
172172+ // handle close
173173+ }
174174+ },
175175+ development: {
176176+ hmr: true,
177177+ console: true,
178178+ }
179179+})
180180+```
181181+182182+HTML files can import .tsx, .jsx or .js files directly and Bun's bundler will transpile & bundle automatically. `<link>` tags can point to stylesheets and Bun's CSS bundler will bundle.
183183+184184+```html#index.html
185185+<html>
186186+ <body>
187187+ <h1>Hello, world!</h1>
188188+ <script type="module" src="./frontend.tsx"></script>
189189+ </body>
190190+</html>
191191+```
192192+193193+With the following `frontend.tsx`:
194194+195195+```tsx#frontend.tsx
196196+import React from "react";
197197+import { createRoot } from "react-dom/client";
198198+199199+// import .css files directly and it works
200200+import './index.css';
201201+202202+const root = createRoot(document.body);
203203+204204+export default function Frontend() {
205205+ return <h1>Hello, world!</h1>;
206206+}
207207+208208+root.render(<Frontend />);
209209+```
210210+211211+Then, run index.ts
212212+213213+```sh
214214+bun --hot ./index.ts
215215+```
216216+217217+For more information, read the Bun API docs in `node_modules/bun-types/docs/**.mdx`.
+15
README.md
···11+# assistant
22+33+To install dependencies:
44+55+```bash
66+bun install
77+```
88+99+To run:
1010+1111+```bash
1212+bun run index.ts
1313+```
1414+1515+This project was created using `bun init` in bun v1.3.4. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.