Crate balls 

Ball: git-native task tracker for parallel agent workflows.

Tasks are JSON files committed to your repo. Worktrees provide isolation. Git provides sync, history, and collaboration. There is no database, no daemon, no external service.

Library usage

use balls::{Store, Task};
use std::env;

let store = Store::discover(&env::current_dir().unwrap()).unwrap();
let tasks = store.all_tasks().unwrap();
for t in balls::ready::ready_queue(&tasks) {
    println!("[P{}] {} {}", t.priority, t.id, t.title);
}

Re-exports

pub use config::Config;

pub use error::BallError;

pub use error::Result;

pub use store::Store;

pub use task::validate_id;

pub use task::ArchivedChild;

pub use task::Link;

pub use task::LinkType;

pub use task::NewTaskOpts;

pub use task::Note;

pub use task::Status;

pub use task::Task;

pub use task::TaskType;

Modules

archive_recovery

Recover closed/archived tasks from the state branch’s git history.

archived_child

ArchivedChild — the snapshot a parent task carries for each closed descendant. Lives in its own module to keep task.rs under the 300-line cap and to localize the forward-compat catch-all.

bare_squash

Squash-merge a work branch into main even when store.root is a bare gitdir. Non-bare roots run the squash directly. Bare roots cannot host working-tree-required commands (git merge --squash refuses with “this operation must be run in a work tree”), so we provision an ephemeral detached worktree at <root>/.balls/local/ squash-<pid>, do the squash there, and update refs/heads/<main> from the bare gitdir afterward. See bl-56f4: bare repos with linked .balls-worktrees/ checkouts are a designed-for layout, but the direct-squash code path silently broke them.

claim_push

State-branch push: remote resolution and outcome classification.

claim_sync

Git-remote Protocol impl for state-branch lifecycle pushes.

commit_msg

Format a review-time commit message in the standard git 50/72 shape: a single title line with the delivery tag appended, a blank line, then the optional body. Keeps git log --oneline readable.

commit_policy

Apply-time composition for CommitPolicy outcomes. SPEC §10.

config

delivery

Delivery-link resolution (SPEC §6).

display

CLI display primitives: colors, glyphs, badges, tree prefixes.

doctor

bl doctor: read-only drift diagnostics.

error

git

git_merge

Merge and conflict helpers split out of git.rs. These are the git operations that classify a merge’s outcome (clean / up-to-date / conflict) and inspect in-progress conflict state — a cohesive slice of the otherwise-flat git wrapper surface. Re-exported from git so call sites keep using git::git_merge etc.

git_state

Git plumbing for the state branch topology: orphan branch creation, remote-tracking setup, and worktree attachment for an existing branch. Separate from git.rs so that module stays under the 300-line cap.

human_gate

Human-gate participant: stages negotiation outcomes for operator review instead of applying them immediately. SPEC §9 gating policy materialized for the sync event (bl-a46d).

link

Typed relationships between tasks: Link and LinkType.

min_version

Advisory min_bl_version check (SPEC §5 / §10).

negotiation

Lifecycle-sync negotiation primitive.

participant

Lifecycle-sync participants. SPEC §3, §5–§7.

participant_config

SPEC §11 — per-event participant policy with layered config resolution.

plugin

policy

Effective claim-policy resolution. Layers, lowest precedence first:

progress

Epic completion bar: 10-cell block with closed/total and percent.

ready

remaster

bl remaster reconcile/detach core (bl-2057).

render_list

Grouped/nested/glyphed rendering for bl list.

render_ready

Single-status (always open) ready-queue rendering.

render_show

Rich rendering for bl show.

render_show_relations

The relations block of bl show: deps (with inline statuses), gates, other links, parent, children + completion, delivered, branch, repo, and external-remote rows.

render_show_text

Text helpers for render_show: relative timestamps and paragraph word-wrap. Split out so render_show.rs stays under the 300-line cap while keeping the helpers testable in isolation.

resolve

review

Review, close, and archive — the submit side of the task lifecycle. Lives alongside worktree.rs (claim/drop/orphans) but kept separate so neither file hits the 300-line cap.

review_deferred

Deferred-mode bl review (SPEC §7.2).

review_safety

Safety rails around bl review’s integration-branch mutation.

sanitize

Neutralize terminal control sequences in externally-influenced text.

status

store

sync_resolve

Shared post-merge auto-resolution. Both bl sync and the claim-time push-retry loop need to take a state-worktree mid-merge and resolve .balls/tasks/*.json conflicts via the field-level merge in resolve.rs. Notes sidecars are handled by git’s union merge driver everywhere except delete/modify, which surfaces here.

task

task_id

Unique task-id minting. SHA1(title + timestamp) truncated to the repo’s configured id length, retried with a stepped timestamp on collision. The single home for id generation: both bl create and deferred-mode bl review’s auto-gate child mint ids through here, so there is no second copy of the retry loop to drift.

task_io

Task file I/O. Separated from task.rs to keep that file under the 300-line cap and to localize the on-disk format in one place.

task_type

TaskType — a free-form, identifier-safe label attached to each task. Types are pure labels: nothing in balls branches on the value except “is this epic?” (which drives progress/display). Widening the vocabulary therefore lives here, not in call sites.

task_validate

Task ID and priority validation. Split out of task.rs for the same reason task_io.rs is — that file stays focused on type definitions while behavior lives in its own module — and to keep both under the 300-line cap. Re-exported from task so call sites keep importing crate::task::{validate_id, ...} unchanged.

tree

Parent-edge tree rendering for bl dep tree.

worktree

Worktree scaffolding: claim, drop, and orphan cleanup. The submit side (review, close, archive) lives in review.rs to keep both files under the 300-line cap.

worktree_teardown

Teardown paths split out of worktree.rs: releasing a claim (drop_no_worktree / drop_worktree) and sweeping stale claim files + dangling worktrees (cleanup_orphans). The claim/create side stays in worktree.rs; both share only the lock and path helpers, re-exported here from worktree.