Navigate a directory full of directories, identifying repos and worktrees
initial idea
+348
+39
.beads/.gitignore
+39
.beads/.gitignore
···
1
+
# SQLite databases
2
+
*.db
3
+
*.db?*
4
+
*.db-journal
5
+
*.db-wal
6
+
*.db-shm
7
+
8
+
# Daemon runtime files
9
+
daemon.lock
10
+
daemon.log
11
+
daemon.pid
12
+
bd.sock
13
+
sync-state.json
14
+
last-touched
15
+
16
+
# Local version tracking (prevents upgrade notification spam after git ops)
17
+
.local_version
18
+
19
+
# Legacy database files
20
+
db.sqlite
21
+
bd.db
22
+
23
+
# Worktree redirect file (contains relative path to main repo's .beads/)
24
+
# Must not be committed as paths would be wrong in other clones
25
+
redirect
26
+
27
+
# Merge artifacts (temporary files from 3-way merge)
28
+
beads.base.jsonl
29
+
beads.base.meta.json
30
+
beads.left.jsonl
31
+
beads.left.meta.json
32
+
beads.right.jsonl
33
+
beads.right.meta.json
34
+
35
+
# NOTE: Do NOT add negation patterns (e.g., !issues.jsonl) here.
36
+
# They would override fork protection in .git/info/exclude, allowing
37
+
# contributors to accidentally commit upstream issue databases.
38
+
# The JSONL files (issues.jsonl, interactions.jsonl) and config files
39
+
# are tracked by git by default since no pattern above ignores them.
+81
.beads/README.md
+81
.beads/README.md
···
1
+
# Beads - AI-Native Issue Tracking
2
+
3
+
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.
4
+
5
+
## What is Beads?
6
+
7
+
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.
8
+
9
+
**Learn more:** [github.com/steveyegge/beads](https://github.com/steveyegge/beads)
10
+
11
+
## Quick Start
12
+
13
+
### Essential Commands
14
+
15
+
```bash
16
+
# Create new issues
17
+
bd create "Add user authentication"
18
+
19
+
# View all issues
20
+
bd list
21
+
22
+
# View issue details
23
+
bd show <issue-id>
24
+
25
+
# Update issue status
26
+
bd update <issue-id> --status in_progress
27
+
bd update <issue-id> --status done
28
+
29
+
# Sync with git remote
30
+
bd sync
31
+
```
32
+
33
+
### Working with Issues
34
+
35
+
Issues in Beads are:
36
+
- **Git-native**: Stored in `.beads/issues.jsonl` and synced like code
37
+
- **AI-friendly**: CLI-first design works perfectly with AI coding agents
38
+
- **Branch-aware**: Issues can follow your branch workflow
39
+
- **Always in sync**: Auto-syncs with your commits
40
+
41
+
## Why Beads?
42
+
43
+
✨ **AI-Native Design**
44
+
- Built specifically for AI-assisted development workflows
45
+
- CLI-first interface works seamlessly with AI coding agents
46
+
- No context switching to web UIs
47
+
48
+
🚀 **Developer Focused**
49
+
- Issues live in your repo, right next to your code
50
+
- Works offline, syncs when you push
51
+
- Fast, lightweight, and stays out of your way
52
+
53
+
🔧 **Git Integration**
54
+
- Automatic sync with git commits
55
+
- Branch-aware issue tracking
56
+
- Intelligent JSONL merge resolution
57
+
58
+
## Get Started with Beads
59
+
60
+
Try Beads in your own projects:
61
+
62
+
```bash
63
+
# Install Beads
64
+
curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
65
+
66
+
# Initialize in your repo
67
+
bd init
68
+
69
+
# Create your first issue
70
+
bd create "Try out Beads"
71
+
```
72
+
73
+
## Learn More
74
+
75
+
- **Documentation**: [github.com/steveyegge/beads/docs](https://github.com/steveyegge/beads/tree/main/docs)
76
+
- **Quick Start Guide**: Run `bd quickstart`
77
+
- **Examples**: [github.com/steveyegge/beads/examples](https://github.com/steveyegge/beads/tree/main/examples)
78
+
79
+
---
80
+
81
+
*Beads: Issue tracking that moves at the speed of thought* ⚡
+62
.beads/config.yaml
+62
.beads/config.yaml
···
1
+
# Beads Configuration File
2
+
# This file configures default behavior for all bd commands in this repository
3
+
# All settings can also be set via environment variables (BD_* prefix)
4
+
# or overridden with command-line flags
5
+
6
+
# Issue prefix for this repository (used by bd init)
7
+
# If not set, bd init will auto-detect from directory name
8
+
# Example: issue-prefix: "myproject" creates issues like "myproject-1", "myproject-2", etc.
9
+
# issue-prefix: ""
10
+
11
+
# Use no-db mode: load from JSONL, no SQLite, write back after each command
12
+
# When true, bd will use .beads/issues.jsonl as the source of truth
13
+
# instead of SQLite database
14
+
# no-db: false
15
+
16
+
# Disable daemon for RPC communication (forces direct database access)
17
+
# no-daemon: false
18
+
19
+
# Disable auto-flush of database to JSONL after mutations
20
+
# no-auto-flush: false
21
+
22
+
# Disable auto-import from JSONL when it's newer than database
23
+
# no-auto-import: false
24
+
25
+
# Enable JSON output by default
26
+
# json: false
27
+
28
+
# Default actor for audit trails (overridden by BD_ACTOR or --actor)
29
+
# actor: ""
30
+
31
+
# Path to database (overridden by BEADS_DB or --db)
32
+
# db: ""
33
+
34
+
# Auto-start daemon if not running (can also use BEADS_AUTO_START_DAEMON)
35
+
# auto-start-daemon: true
36
+
37
+
# Debounce interval for auto-flush (can also use BEADS_FLUSH_DEBOUNCE)
38
+
# flush-debounce: "5s"
39
+
40
+
# Git branch for beads commits (bd sync will commit to this branch)
41
+
# IMPORTANT: Set this for team projects so all clones use the same sync branch.
42
+
# This setting persists across clones (unlike database config which is gitignored).
43
+
# Can also use BEADS_SYNC_BRANCH env var for local override.
44
+
# If not set, bd sync will require you to run 'bd config set sync.branch <branch>'.
45
+
# sync-branch: "beads-sync"
46
+
47
+
# Multi-repo configuration (experimental - bd-307)
48
+
# Allows hydrating from multiple repositories and routing writes to the correct JSONL
49
+
# repos:
50
+
# primary: "." # Primary repo (where this database lives)
51
+
# additional: # Additional repos to hydrate from (read-only)
52
+
# - ~/beads-planning # Personal planning repo
53
+
# - ~/work-planning # Work planning repo
54
+
55
+
# Integration settings (access with 'bd config get/set')
56
+
# These are stored in the database, not in this file:
57
+
# - jira.url
58
+
# - jira.project
59
+
# - linear.url
60
+
# - linear.api-key
61
+
# - github.org
62
+
# - github.repo
.beads/interactions.jsonl
.beads/interactions.jsonl
This is a binary file and will not be displayed.
+12
.beads/issues.jsonl
+12
.beads/issues.jsonl
···
1
+
{"id":"is-tree-00n","title":"Add --workparent flag and column","description":"Add workparent column showing the directory name of the workparent (without path) for worktrees.","status":"open","priority":3,"issue_type":"task","assignee":"opencode","created_at":"2026-01-08T20:41:40.245737161-05:00","created_by":"rektide","updated_at":"2026-01-08T20:44:48.135512658-05:00","dependencies":[{"issue_id":"is-tree-00n","depends_on_id":"is-tree-xxv","type":"parent-child","created_at":"2026-01-08T20:41:51.545126882-05:00","created_by":"rektide"}]}
2
+
{"id":"is-tree-070","title":"Add --date flag for date format specification","description":"Add -date flag for specifying date format string, default to ISO 8601.","status":"open","priority":3,"issue_type":"task","assignee":"opencode","created_at":"2026-01-08T20:41:34.7246953-05:00","created_by":"rektide","updated_at":"2026-01-08T20:44:46.808971954-05:00","dependencies":[{"issue_id":"is-tree-070","depends_on_id":"is-tree-xxv","type":"parent-child","created_at":"2026-01-08T20:41:50.416305393-05:00","created_by":"rektide"}]}
3
+
{"id":"is-tree-1hz","title":"Add --change-date flag and column","description":"Add change-date column showing the most recent file change date for each repository.","status":"open","priority":3,"issue_type":"task","assignee":"opencode","created_at":"2026-01-08T20:41:36.238982256-05:00","created_by":"rektide","updated_at":"2026-01-08T20:44:47.650039629-05:00","dependencies":[{"issue_id":"is-tree-1hz","depends_on_id":"is-tree-xxv","type":"parent-child","created_at":"2026-01-08T20:41:51.170223198-05:00","created_by":"rektide"}]}
4
+
{"id":"is-tree-3rl","title":"Add --reverse/-R flag for reversing sort order","description":"Add --reverse/-R flag to reverse the sort order of results.","status":"closed","priority":3,"issue_type":"task","assignee":"opencode","created_at":"2026-01-08T20:41:25.164452341-05:00","created_by":"rektide","updated_at":"2026-01-08T20:45:09.26853254-05:00","closed_at":"2026-01-08T20:45:09.26853254-05:00","close_reason":"Removed from spec - reverse functionality replaced with +/- suffixes on sort columns","dependencies":[{"issue_id":"is-tree-3rl","depends_on_id":"is-tree-xxv","type":"parent-child","created_at":"2026-01-08T20:41:49.671575997-05:00","created_by":"rektide"}]}
5
+
{"id":"is-tree-b47","title":"Add --all/-a flag for testing all directories","description":"Add -all/-a flag to test all directories in the current path.","status":"open","priority":3,"issue_type":"task","assignee":"opencode","created_at":"2026-01-08T20:41:13.284435802-05:00","created_by":"rektide","updated_at":"2026-01-08T20:44:39.979880568-05:00","dependencies":[{"issue_id":"is-tree-b47","depends_on_id":"is-tree-xxv","type":"parent-child","created_at":"2026-01-08T20:41:48.410347085-05:00","created_by":"rektide"}]}
6
+
{"id":"is-tree-bdv","title":"Add --sort flag for sorting results","description":"Add -sort flag for sorting results by any column, with comma-separated multiple sorts and +/- suffixes for direction.","status":"open","priority":3,"issue_type":"task","assignee":"opencode","created_at":"2026-01-08T20:41:24.45670004-05:00","created_by":"rektide","updated_at":"2026-01-08T20:44:41.012519597-05:00","dependencies":[{"issue_id":"is-tree-bdv","depends_on_id":"is-tree-xxv","type":"parent-child","created_at":"2026-01-08T20:41:49.294378668-05:00","created_by":"rektide"}]}
7
+
{"id":"is-tree-e8o","title":"Add --filter flag for type filtering","description":"Add -filter flag to filter results by type: git, jj, worktree, worktree-git, worktree-jj.","status":"open","priority":3,"issue_type":"task","assignee":"opencode","created_at":"2026-01-08T20:41:14.101564202-05:00","created_by":"rektide","updated_at":"2026-01-08T20:44:40.475782286-05:00","dependencies":[{"issue_id":"is-tree-e8o","depends_on_id":"is-tree-xxv","type":"parent-child","created_at":"2026-01-08T20:41:48.770131028-05:00","created_by":"rektide"}]}
8
+
{"id":"is-tree-sro","title":"Add --commit-date flag and column","description":"Add commit-date column showing the most recent commit date for each repository.","status":"open","priority":3,"issue_type":"task","assignee":"opencode","created_at":"2026-01-08T20:41:35.59115589-05:00","created_by":"rektide","updated_at":"2026-01-08T20:44:47.252980365-05:00","dependencies":[{"issue_id":"is-tree-sro","depends_on_id":"is-tree-xxv","type":"parent-child","created_at":"2026-01-08T20:41:50.789560287-05:00","created_by":"rektide"}]}
9
+
{"id":"is-tree-uh7","title":"Implement basic Git and Jujutsu detection","description":"Implement basic directory detection logic for Git and Jujutsu repositories and worktrees.","status":"open","priority":2,"issue_type":"task","assignee":"opencode","created_at":"2026-01-08T20:41:12.309327226-05:00","created_by":"rektide","updated_at":"2026-01-08T20:41:12.309327226-05:00","dependencies":[{"issue_id":"is-tree-uh7","depends_on_id":"is-tree-xxv","type":"parent-child","created_at":"2026-01-08T20:41:48.068150262-05:00","created_by":"rektide"}]}
10
+
{"id":"is-tree-vv0","title":"Add --json flag for JSON output","description":"Add -json flag to output results in JSON format as an array of objects with all columns as fields.","status":"open","priority":3,"issue_type":"task","assignee":"opencode","created_at":"2026-01-08T20:41:43.099902307-05:00","created_by":"rektide","updated_at":"2026-01-08T20:44:56.124813305-05:00","dependencies":[{"issue_id":"is-tree-vv0","depends_on_id":"is-tree-xxv","type":"parent-child","created_at":"2026-01-08T20:41:51.929114842-05:00","created_by":"rektide"}]}
11
+
{"id":"is-tree-wsl","title":"Add --format flag for custom output format","description":"Add -format flag for custom output format with interpolated columns: status, directory, commit-date, change-date, workparent.","status":"open","priority":3,"issue_type":"task","assignee":"opencode","created_at":"2026-01-08T20:41:27.778302538-05:00","created_by":"rektide","updated_at":"2026-01-08T20:44:46.289183418-05:00","dependencies":[{"issue_id":"is-tree-wsl","depends_on_id":"is-tree-xxv","type":"parent-child","created_at":"2026-01-08T20:41:50.040861907-05:00","created_by":"rektide"}]}
12
+
{"id":"is-tree-xxv","title":"Command Options Epic","description":"Implement all CLI command options for is-tree including sorting, filtering, formatting, and output options.","status":"open","priority":2,"issue_type":"epic","created_at":"2026-01-08T20:40:57.497406738-05:00","created_by":"rektide","updated_at":"2026-01-08T20:40:57.497406738-05:00"}
+4
.beads/metadata.json
+4
.beads/metadata.json
+3
.gitattributes
+3
.gitattributes
+40
AGENTS.md
+40
AGENTS.md
···
1
+
# Agent Instructions
2
+
3
+
This project uses **bd** (beads) for issue tracking. Run `bd onboard` to get started.
4
+
5
+
## Quick Reference
6
+
7
+
```bash
8
+
bd ready # Find available work
9
+
bd show <id> # View issue details
10
+
bd update <id> --status in_progress # Claim work
11
+
bd close <id> # Complete work
12
+
bd sync # Sync with git
13
+
```
14
+
15
+
## Landing the Plane (Session Completion)
16
+
17
+
**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
18
+
19
+
**MANDATORY WORKFLOW:**
20
+
21
+
1. **File issues for remaining work** - Create issues for anything that needs follow-up
22
+
2. **Run quality gates** (if code changed) - Tests, linters, builds
23
+
3. **Update issue status** - Close finished work, update in-progress items
24
+
4. **PUSH TO REMOTE** - This is MANDATORY:
25
+
```bash
26
+
git pull --rebase
27
+
bd sync
28
+
git push
29
+
git status # MUST show "up to date with origin"
30
+
```
31
+
5. **Clean up** - Clear stashes, prune remote branches
32
+
6. **Verify** - All changes committed AND pushed
33
+
7. **Hand off** - Provide context for next session
34
+
35
+
**CRITICAL RULES:**
36
+
- Work is NOT complete until `git push` succeeds
37
+
- NEVER stop before pushing - that leaves work stranded locally
38
+
- NEVER say "ready to push when you are" - YOU must push
39
+
- If push fails, resolve and retry until it succeeds
40
+
+107
README.md
+107
README.md
···
1
+
# is-tree
2
+
3
+
> CLI utility to detect and classify Git and Jujutsu repositories
4
+
5
+
## Usage
6
+
7
+
```bash
8
+
# Test a specific directory
9
+
is-tree ~/src/compfuzor
10
+
11
+
# Test all directories in current path with --all/-a
12
+
is-tree --all
13
+
14
+
# Filter for specific types
15
+
is-tree --all --filter git
16
+
is-tree --all --filter jj
17
+
is-tree --all --filter worktree
18
+
is-tree --all --filter worktree-git
19
+
is-tree --all --filter worktree-jj
20
+
21
+
# Test specific directories by positional arguments
22
+
is-tree ~/src/compfuzor ~/src/niri-mcp
23
+
24
+
# Sort by any column (use + for ascending, - for descending)
25
+
is-tree --all --sort change-date-
26
+
is-tree --all --sort commit-date+
27
+
is-tree --all --sort workparent,directory+
28
+
29
+
# Multiple sorts (comma-separated)
30
+
is-tree --all --sort status-,change-date+
31
+
32
+
# Custom output format with interpolated columns
33
+
is-tree --all --format "{status} {directory} {commit-date} {change-date} {workparent}"
34
+
35
+
# Output as JSON
36
+
is-tree --all --json
37
+
38
+
# Custom date format
39
+
is-tree --all --date "%Y-%m-%d %H:%M:%S"
40
+
```
41
+
42
+
## Options
43
+
44
+
- `--all`, `-a` - Test all directories in current path
45
+
- `--filter <type>` - Filter results by type: `git`, `jj`, `worktree`, `worktree-git`, `worktree-jj`
46
+
- `--sort <column>` - Sort by column(s). Multiple columns comma-separated. Suffix `+` for ascending, `-` for descending
47
+
- `--format <string>` - Custom output format with interpolated columns
48
+
- `--date <format>` - Date format string (default: ISO 8601)
49
+
- `--json` - Output results in JSON format
50
+
- Positional arguments - Test specific directories
51
+
52
+
## Output
53
+
54
+
Default format: `<status> <directory>`
55
+
56
+
### Columns
57
+
Available columns for custom format:
58
+
- `status` - Repository type (git, jj, worktree-git, worktree-jj, none)
59
+
- `directory` - Full directory path
60
+
- `workparent` - Directory name of the workparent (without path), for worktrees only
61
+
- `commit-date` - Most recent commit date
62
+
- `change-date` - Most recent file change date
63
+
64
+
### Status values
65
+
- `git` - Git repository (not Jujutsu, not a worktree)
66
+
- `jj` - Jujutsu repository (not a worktree)
67
+
- `worktree-git` - Git worktree
68
+
- `worktree-jj` - Jujutsu worktree
69
+
- `none` - Not a recognized repository
70
+
71
+
### JSON Output
72
+
When `--json` is specified, output is an array of objects with all available columns as fields.
73
+
74
+
## Detection
75
+
76
+
### Strategy Overview
77
+
78
+
The detection strategy uses a hierarchical approach to classify directories based on the presence and characteristics of version control metadata.
79
+
80
+
### Detection Logic
81
+
82
+
1. **Jujutsu Detection** (Primary Check)
83
+
- Check for `.jj` directory or `.jj` file (workspace)
84
+
- Jujutsu stores a `.jj` file in the workspace root that points to the actual `.jj` store location
85
+
- If `.jj` exists, this is a Jujutsu workspace
86
+
87
+
2. **Git Detection** (Secondary Check)
88
+
- Check for `.git` directory (regular repository)
89
+
- Check for `.git` file (worktree pointer)
90
+
- Git worktrees use a `.git` file containing `gitdir: <path>` pointing to the actual `.git` directory
91
+
92
+
3. **Worktree Classification**
93
+
- For Jujutsu: A directory is a worktree if it contains a `.jj` file (pointer) rather than a `.jj` directory (main workspace)
94
+
- For Git: A directory is a worktree if it contains a `.git` file (pointer) rather than a `.git` directory (main repository)
95
+
96
+
### Priority Rules
97
+
98
+
- Jujutsu takes precedence over Git when both indicators are present
99
+
- Worktree classification is determined by the pointer file vs directory distinction
100
+
- If neither `.git` nor `.jj` indicators are found, status is `none`
101
+
102
+
### Examples
103
+
104
+
- `~/src/compfuzor` → `git` (has `.git/` directory)
105
+
- `~/src/compfuzor-x` → `worktree-git` (has `.git` file with `gitdir:` pointer)
106
+
- `~/src/niri-mcp` → `jj` (has `.jj/` directory or `.jj` file in main workspace)
107
+
- `~/src/niri-mcp-x` → `worktree-jj` (has `.jj` file pointing to main workspace)