beads-for-laravel maintained by codeberry
beads is a git-friendly issue tracker that lives in your repository and that AI coding agents use to plan and track their work. Beads for Laravel gives you and your team a proper interface on top of it: browse, triage and edit the same issues your agents work on, and watch their changes arrive live.
- bd stays the source of truth. The package only talks to the
bdCLI. It stores no tickets of its own and never touches your app's code or database. - Local only. Routes, UI and commands exist only in the
localenvironment. - Made for working alongside agents. Changes made from the CLI show up within seconds, authors outside your team get an agent badge, and when an agent edits a text you are editing, you get a conflict bar instead of a silent overwrite.
Features
- Issue list grouped by status, priority, type or assignee, with filters, sorting and search
(
p0–p4included) that live in the URL, so every view can be shared. - Board with a column per bd status, custom statuses included, and drag and drop.
- Epics with progress bars and their sub-issues.
- Ready and Blocked views that match
bd readyandbd blockedexactly, and show what each issue waits on. - Side-peek and full-page detail with property pickers, relations (blocked by, blocking, related, sub-issues), comments, and close, reopen or force close.
- Markdown editor (Tiptap) that autosaves, only writes when you really changed something, and opens content it cannot keep losslessly (raw HTML, footnotes, tables) as markdown source.
- Keyboard first:
⌘Kcommand menu,Cto create,J/Kto move,/to search. - Light and dark themes, following your system or your choice.
- Health screens that tell you exactly what to run when bd is missing, too old, not initialised or needs a migration.
Screenshots
Requirements
- PHP 8.4 or newer
- Laravel 12 or 13
- bd 1.3.0 or newer, with a workspace (
bd init) in your project
Installation
Install the package as a dev dependency:
composer require --dev codeberry/beads-for-laravel
Then run the installer:
php artisan beads:install
It publishes config/beads.php and the compiled UI to public/vendor/beads, and offers to add a
hook to the post-update-cmd scripts in your composer.json. With that hook the UI assets stay in
sync after every composer update:
"post-update-cmd": [
"@php artisan vendor:publish --tag=beads-assets --force"
]
Pass --hook or --no-hook to answer without a prompt.
Open /beads in your app, for example http://my-app.test/beads.
Updating
After updating the package, publish the new assets (the hook above does this for you):
php artisan beads:publish
If you forget, the UI shows a banner with this command.
Laravel Herd and other PHP-FPM setups
Herd's PHP-FPM clears the environment, so web requests have no PATH, HOME or USER. The
package never relies on them:
bdis called with an absolute path. WithoutBEADS_BINARYit looks in/opt/homebrew/bin/bd,/usr/local/bin/bd,~/go/bin/bdand~/.local/bin/bd, in that order. SetBEADS_BINARYwhen your bd lives elsewhere, or when an older bd comes first.HOMEcomes from the system user database, andPATHis the binary's directory plus/usr/bin:/bin.
Usage
Keyboard shortcuts
| Key | Action |
|---|---|
⌘K / Ctrl+K |
Command menu: search issues, navigate, create |
C |
Create an issue (prefilled from where you are) |
/ |
Search the current list or board |
J / K (or ↓ / ↑) |
Next / previous issue, also while the side-peek is open |
Enter |
Open the issue in the side-peek |
Esc |
Close the side-peek or dialog |
⌘Enter |
Save the text you are editing, post a comment or create the issue |
Shortcuts never fire while you type in a field.
Working with agents
Run your agents as usual. Everything they do with bd appears in the UI within a few seconds. To
tell people and agents apart, list the humans in the config: every other author gets an agent
badge.
// config/beads.php
'humans' => ['Jurrid', 'Alex'],
Changes made from the UI are recorded in bd as the actor: BEADS_ACTOR, or else
git config user.name of the workspace.
Configuration
Every option can be set from .env or in config/beads.php.
| Option | Env | Default | Meaning |
|---|---|---|---|
enabled |
BEADS_ENABLED |
true |
Set to false to switch the UI off, also locally. |
path |
BEADS_PATH |
base_path() |
The directory that contains .beads. |
binary |
BEADS_BINARY |
auto-detect | Absolute path to bd. A configured path always wins. |
actor |
BEADS_ACTOR |
git config user.name |
The actor bd records for changes from the UI. |
humans |
– | [actor] |
Authors not listed here get an agent badge. |
route.prefix |
BEADS_ROUTE_PREFIX |
beads |
The URL prefix. |
route.domain |
BEADS_DOMAIN |
null |
Serve the UI on its own domain. |
route.middleware |
– | ['web'] |
Sessions and CSRF protection come from web. |
poll_interval |
– | 3 |
Seconds between live-update polls. |
closed_window_days |
– | 30 |
Closed issues newer than this load by default. |
lock_timeout |
– | 10 |
Seconds to wait for the workspace lock before a retry. |
process_timeout |
– | 30 |
Seconds a single bd call may take. |
Access
The UI only exists when app()->isLocal() and beads.enabled is not false. Every request also
passes the viewBeads gate. The package defines it (allowing everyone, guests included) only when
your app has not, so you can restrict it:
// app/Providers/AppServiceProvider.php
use Illuminate\Support\Facades\Gate;
Gate::define('viewBeads', fn (User $user) => $user->is_admin);
Health screens
When something is wrong, the UI shows a full screen with the commands to fix it:
| State | Cause | Fix |
|---|---|---|
binary_missing |
No bd found, or BEADS_BINARY points nowhere. |
brew install beads, or set BEADS_BINARY. |
version_too_old |
bd is older than 1.3.0. | brew upgrade beads |
workspace_missing |
No .beads directory in the workspace. |
Run bd init there, or set BEADS_PATH. |
schema_migration_required |
The bd database is behind the binary. | Run bd migrate schema in the workspace. |
How it works
- No shell, one call at a time. Every bd call is an argument array (values always as
--flag=value, free text after--), runs with--json --sandbox(and--readonlyfor reads), and goes through a per-workspace file lock. bd's embedded Dolt store does not survive concurrent calls, and even reads write to it. - Cheap live updates. The browser polls a snapshot every few seconds. The server compares a
fingerprint of the files in
.beadswith the one it recorded after its own last call; only a change triggers a newbd export. An unchanged workspace answers304 Not Modifiedwithout calling bd at all. - Ready and blocked in PHP. Both are derived from one export and verified against
bd readyandbd blocked, including blocking that passes down from a parent to its children. - Safe editing. Pickers save directly and optimistically, and roll back with bd's own message when bd refuses. Text fields send the value they started from, so an edit made elsewhere in the meantime becomes a conflict you resolve instead of a lost change.
The snapshot is cached in storage/framework/beads, independent of your cache driver.
Not (yet) included
Deleting issues, bulk actions, a dependency graph, manual ordering, more than one workspace per
app, and bd init, sync, push or pull from the UI. The UI is in English and ready for
translation. Ideas are welcome in the discussions.
Contributing
Contributions are welcome. CONTRIBUTING.md explains how to set up the workbench, run the tests and send a pull request.
Security
Found a security issue? Please report it privately; see SECURITY.md.
Credits
- Jurrid at Codeberry
- All contributors
- Built on beads, Vue, Tiptap, reka-ui and shadcn-vue.
License
The MIT License (MIT). See LICENSE.md.