Perles is a terminal UI for beads issue tracking, powered by a custom BQL (Beads Query Language). Search with boolean logic, filter by dates, traverse dependency trees, and build custom kanban views without leaving your terminal. Each kanban swimlane column is defined by a BQL query, so you can slice your issues however you want.
Perles has its own Orchestration Control Plane that spawns a headless coordinator agent that can manage and recycle multiple headless worker agents for you with built-in multi-agent workflows or user defined workflows that can run in parallel.
- A beads-enabled project (
.beads/directory withbeads.db) - Minimum beads database version v0.41.0. run
bd migrateto upgrade after updating beads
curl -sSL https://raw.githubusercontent.com/zjrosen/perles/main/install.sh | bashbrew tap zjrosen/perles
brew install perlesRequires Go 1.21+
go install github.com/zjrosen/perles@latestgit clone https://github.com/zjrosen/perles.git
cd perles
make install
perlesPre-built binaries for Linux and macOS (both Intel and Apple Silicon) are available on the Releases page.
- Download the archive for your platform
- Extract:
tar -xzf perles_*.tar.gz - Move to PATH:
sudo mv perles /usr/local/bin/ - Verify:
perles --version
Run perles in any directory containing a .beads/ folder:
cd your-project
perlesDOLT WARNING Since beads version v0.50.1 SQLite is no longer supported in beads. Dolt is now the only backed for beads and recent beads versions are only using Dolt server mode, embedded mode has been deprecated in beads and will not work with perles.
There is experimental support for Dolt in perles after v0.56.1 but there are still open issues in beads so changes will still be made in perles for Dolt support as beads fixes are made. If you plan on using Dolt you will have to be running the latest version of beads built from the beads source until a new release is made in beads.
| Flag | Short | Description |
|---|---|---|
--beads-dir |
-b |
Path to beads database directory |
--config |
-c |
Path to config file |
--no-auto-refresh |
Disable automatic board refresh | |
--version |
-v |
Print version |
--help |
-h |
Print help |
--debug |
-d |
Enable developer/debug mode |
| Command | Description |
|---|---|
perles |
Launch the TUI application |
perles themes |
List available theme presets |
perles workflows |
List available workflow templates |
| Key | Action |
|---|---|
ctrl+space |
Switch between Kanban and Search modes |
? |
Toggle help overlay |
ctrl+c |
Quit |
Organize issues into customizable columns powered by BQL queries or dependency trees.
- Four-column default layout: Blocked, Ready, In Progress, Closed
- Fully customizable columns with BQL queries or dependency trees
- Multi-view support — create unlimited board views
- Real-time auto-refresh when database changes
- Column management: add, edit, reorder, delete
Use h and l to move left and right between columns, ctrl+h / ctrl+l to move column positions and ctrl+n / ctrl+p to switch between views. Use ctrl+v to open the view menu to create, rename or delete a view.
board.mov
Use a from kanban mode to add a new column.
add-column-from-existing.mov
| Key | Action |
|---|---|
h / ← |
Move to left column |
l / → |
Move to right column |
j / ↓ |
Move down in column |
k / ↑ |
Move up in column |
Enter |
View issue details |
| Key | Action |
|---|---|
ctrl+j / ctrl+n |
Next view |
ctrl+k / ctrl+p |
Previous view |
ctrl+v |
View menu (Create/Delete/Rename) |
w |
Toggle status bar |
| Key | Action |
|---|---|
a |
Add new column |
e |
Edit current column |
d |
Delete current column |
ctrl+h |
Move column left |
ctrl+l |
Move column right |
/ |
Open search with column's BQL query |
| Key | Action |
|---|---|
y |
Copy issue ID to clipboard |
r |
Refresh issues |
ctrl+e |
Edit issue |
ctrl+d |
Delete issue |
The default view includes these columns (all configurable via BQL):
| Column | BQL Query |
|---|---|
| Blocked | status = open and blocked = true |
| Ready | status = open and ready = true |
| In Progress | status = in_progress |
| Closed | status = closed |
Full-screen BQL-powered search interface with live results and issue details.
- Full-screen BQL-powered search interface
- Save searches as kanban columns
- Create new views from search results
- Sub-mode for viewing issue dependencies and hierarchies
Use ctrl+space to switch modes between Kanban and Search or while on a column use / to be dropped into search mode with the current columns BQL query.
search.mov
Use ctrl+s from search mode to save the BQL query to a new or existing view.
save-to-new-view.mov
| Key | Action |
|---|---|
/ |
Focus search input |
Enter |
Execute query / Edit field |
h |
Move to results list |
l |
Move to details panel |
j / k |
Navigate results |
y |
Copy issue ID |
s |
Change status |
p |
Change priority |
ctrl+s |
Save search as column |
Esc |
Exit to kanban mode |
Visualize and navigate issue relationships — blockers, dependencies, and parent/child hierarchies.
| Key | Action |
|---|---|
j / k |
Move cursor up/down |
l / Tab |
Focus details panel |
h |
Focus tree panel |
Enter |
Refocus tree on selected node |
u |
Go back to previous root |
U |
Go to original root |
d |
Toggle direction (up/down) |
m |
Toggle mode (deps/children) |
y |
Copy issue ID |
/ |
Switch to list mode |
Esc |
Exit to kanban mode |
Perles uses BQL (Beads Query Language) to filter and organize issues. BQL is used in column definitions and search mode.
field operator value [and|or field operator value ...]
| Field | Description | Example Values |
|---|---|---|
status |
Issue status | open, in_progress, closed |
type |
Issue type | bug, feature, task, epic, chore |
priority |
Priority level | P0, P1, P2, P3, P4 |
blocked |
Has blockers | true, false |
ready |
Ready to work | true, false |
pinned |
Is pinned | true, false |
is_template |
Is a template | true, false |
label |
Issue labels | any label string |
title |
Issue title | any text (use ~ for contains) |
description |
Issue description | any text (use ~ for contains) |
design |
Design notes | any text (use ~ for contains) |
notes |
Issue notes | any text (use ~ for contains) |
id |
Issue ID | e.g., bd-123 |
assignee |
Assigned user | username |
sender |
Issue sender | username |
created_by |
Issue creator | username |
hook_bead |
Agent's current work | bead ID |
role_bead |
Agent's role definition | bead ID |
agent_state |
Agent state | idle, running, stuck, stopped |
role_type |
Agent role type | polecat, crew, witness, etc. |
rig |
Agent's rig name | rig name (empty for town-level) |
mol_type |
Molecule type | string |
created |
Creation date | today, yesterday, -7d, -3m |
updated |
Last update | today, -24h |
last_activity |
Agent last activity | today, -24h |
| Operator | Description | Example |
|---|---|---|
= |
Equals | status = open |
!= |
Not equals | type != chore |
< |
Less than | priority < P2 |
> |
Greater than | priority > P3 |
<= |
Less or equal | priority <= P1 |
>= |
Greater or equal | created >= -7d |
~ |
Contains | title ~ auth |
!~ |
Not contains | title !~ test |
in |
In list | status in (open, in_progress) |
not in |
Not in list | label not in (backlog) |
# AND - both conditions must match
status = open and priority = P0
# OR - either condition matches
type = bug or type = feature
# NOT - negate a condition
not blocked = true
# Parentheses for grouping
(type = bug or type = feature) and priority <= P1
# Relative dates
created >= -7d # Last 7 days
updated >= -24h # Last 24 hours
created >= -3m # Last 3 months
# Named dates
created >= today
created >= yesterday
# Single field
status = open order by priority
# Multiple fields with direction
type = bug order by priority asc, created desc
The expand keyword includes related issues in your search results, allowing you to see complete issue hierarchies and dependency chains.
# Basic syntax
<filter> expand <direction> [depth <n>]
| Direction | Description |
|---|---|
up |
Issues you depend on (parents + blockers) |
down |
Issues that depend on you (children + blocked issues) |
all |
Both directions combined |
| Depth | Description |
|---|---|
depth 1 |
Direct relationships only (default) |
depth 2-10 |
Include relationships up to N levels deep |
depth * |
Unlimited depth (follows all relationships) |
# Get an epic and all its children
type = epic expand down
# Get an epic and all descendants (unlimited depth)
type = epic expand down depth *
# Get an issue and everything blocking it
id = bd-123 expand up
# Get an issue and all related issues (both directions)
id = bd-123 expand all depth *
# Get all epics with their full hierarchies
type = epic expand all depth *
# Critical bugs
type = bug and priority = P0
# Ready work, excluding backlog
status = open and ready = true and label not in (backlog)
# Recently updated high-priority items
priority <= P1 and updated >= -24h order by updated desc
# Search by title
title ~ authentication or title ~ login
# Epic with all its children
type = epic expand down depth *
Perles looks for configuration in these locations (in order):
--configflag.perles/config.yaml(current directory)~/.config/perles/config.yaml
| Option | Type | Default | Description |
|---|---|---|---|
beads_dir |
string | "" |
Path to beads database directory (default: current directory) |
auto_refresh |
bool | true |
Auto-refresh when database changes |
ui.show_counts |
bool | true |
Show issue counts in column headers |
ui.show_status_bar |
bool | true |
Show status bar at bottom |
ui.vim_mode |
bool | false |
Vim support for all textarea inputs |
theme.preset |
string | "" |
Theme preset name (see Theming section) |
theme.colors.* |
hex | varies | Individual color token overrides |
orchestration.coordinator_client |
string | "claude" |
AI client: claude, amp, codex or opencode |
orchestration.worker_client |
string | "claude" |
AI client: claude, amp, codex or opencode |
orchestration.session_storage.application_name |
string | auto | Override application name (default: derived from git remote) |
orchestration.templates.document_path |
string | "docs/proposals" |
Base path for generated workflow documents |
# Path to beads database directory (default: current directory)
# beads_dir: /path/to/project
# Auto-refresh when database changes
auto_refresh: true
# UI settings
ui:
show_counts: true
show_status_bar: true
vim_mode: false
# Theme (use a preset or customize colors)
theme:
# preset: catppuccin-mocha # Uncomment to use a theme preset
# colors: # Override specific colors
# text.primary: "#FFFFFF"
# status.error: "#FF0000"
# Board views
views:
- name: Default
columns:
- name: Blocked
type: bql
query: "status = open and blocked = true"
color: "#FF8787"
- name: Ready
query: "status = open and ready = true"
color: "#73F59F"
- name: In Progress
type: bql
query: "status = in_progress"
color: "#54A0FF"
- name: Closed
type: bql
query: "status = closed"
color: "#BBBBBB"
- name: Bugs Only
columns:
- name: Open Bugs
type: bql
query: "type = bug and status = open"
color: "#EF4444"
- name: In Progress
type: bql
query: "type = bug and status = in_progress"
color: "#F59E0B"
- name: Fixed
type: bql
query: "type = bug and status = closed"
color: "#10B981"
- name: Work
columns:
- name: Current
type: tree
issue_id: bd-123
tree_mode: child
color: "#EF4444"
# AI Orchestration settings
orchestration:
coordinator_client: claude # claude (default), amp, codex or opencode
worker_client: claude # claude (default), amp, or codex or opencode
session_storage:
# application_name: my-project # Optional: override auto-derived name
templates:
document_path: docs/proposals # Base path for generated workflow documentsPerles supports comprehensive theming with built-in presets and customizable color tokens.
Use a built-in theme preset by adding to your config:
theme:
preset: catppuccin-mochaRun perles themes to see all available presets:
| Preset | Description |
|---|---|
default |
Default perles theme |
catppuccin-mocha |
Warm, cozy dark theme |
catppuccin-latte |
Warm, cozy light theme |
dracula |
Dark theme with vibrant colors |
nord |
Arctic, north-bluish palette |
high-contrast |
High contrast for accessibility |
Override specific colors while using a preset:
theme:
preset: dracula
colors:
status.error: "#FF0000"
priority.critical: "#FF5555"Or create a fully custom theme:
theme:
colors:
text.primary: "#FFFFFF"
text.muted: "#888888"
status.success: "#00FF00"
status.error: "#FF0000"
border.default: "#444444"
border.focus: "#FFFFFF"Colors are organized by category:
| Category | Tokens |
|---|---|
| Text | text.primary, text.secondary, text.muted, text.description, text.placeholder |
| Border | border.default, border.focus, border.highlight |
| Status | status.success, status.warning, status.error |
| Buttons | button.text, button.primary.bg, button.primary.focus, button.danger.bg |
| Selection | selection.indicator, selection.background |
| Toasts | toast.success, toast.error, toast.info, toast.warn |
| Issue Priority | priority.critical, priority.high, priority.medium, priority.low, priority.backlog |
| Issue Status | issue.status.open, issue.status.in_progress, issue.status.closed |
| Issue Type | type.task, type.bug, type.feature, type.epic, type.chore |
| BQL Syntax | bql.keyword, bql.operator, bql.field, bql.string, bql.literal |
See internal/ui/styles/tokens.go for the complete list of color tokens.
Developer mode provides logging and debugging tools for troubleshooting and development.
# Via flag
perles --debug
# Via environment variable
PERLES_DEBUG=1 perles
# With custom log path
PERLES_LOG=/tmp/perles.log perles --debug- Log file: All log output is written to
debug.log(or custom path viaPERLES_LOG) - Log overlay: Press
ctrl+xto view logs in-app without leaving the TUI - Lifecycle logging: Application startup and shutdown events are logged
When reporting bugs, please include the debug.log file to help with diagnosis:
- Run perles with
--debugflag - Reproduce the issue
- Attach
debug.logto your bug report
Run tests:
make test # Run all tests
make test-v # Run with verbose outputSome tests use teatest for snapshot testing of TUI output. These tests compare rendered output against golden files stored in testdata/ directories.
When you intentionally change UI output, update the golden files:
make test-updateThis regenerates golden files in packages with teatest tests (currently internal/ui/help). Review the changes before committing to ensure they're expected.
MIT
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}
