Segments

A performant, lightweight, single-binary task and project manager. Built as a faster, leaner alternative to Beads.

Status

Segments is a work in progress. The core is stable enough that I use it daily, but it has not had wide exposure yet, so builds and tagged releases are expected to ship with bugs. If you hit one, please open an issue -- the template will prompt for OS, architecture, sg version output, and repro steps. Fast feedback is the quickest way to sand down the rough edges.

Roadmap

Series	Focus	Status
0.1	Foundation -- LMDB storage, core CLI (add / done / close / list), initial MCP integrations, Pi extension, basic web UI	Released
0.2	TUI -- CLI ergonomics, bubbletea confirm/select widgets, sg init / view / remove, Windows daemon, multi-scope setup	Released
0.3	GUI -- three-theme web UI (Obsidian / Console / Dossier), Graph / Kanban / List views, command palette, keyboard-first navigation, sg next / stats / export	Released
0.4	MCP + session polish -- globally addressable task IDs, SessionStart hook, schema-deferral fix, stdio shim for multi-client MCP, recent-work tooling	In progress
0.5	Optimisation -- memory footprint, startup latency, binary size, LMDB env tuning	Planned
0.6	GUI polish -- sorting controls, filters, drag improvements, visual refinements, bug sweep	Planned
0.7+	Ongoing polish, security hardening	Planned

Why

Got fed up with Beads. It's slow, it's heavy, and it leans on a Dolt DB infrastructure that's miserable to live with. Segments is a leaner, faster alternative: same job, single binary, LMDB under the hood, no Dolt, no fuss. It's especially nice for solo power users, but nothing stops you from reverse-proxying the dashboard for a team, or orchestrating downstream actions off its state.

Features

• Projects and tasks with priorities, statuses, dependency chains, and rich-text bodies
• Three interchangeable web themes (Obsidian, Console, Dossier) with light and dark modes
• Three views: grouped List, drag-and-drop Kanban, and top-down dependency Graph
• Aggregated All tasks scope across every project, plus a ready-queue filter (tasks with no outstanding blockers)
• Command palette (Ctrl+K / Cmd+K) and full keyboard-first navigation with g-chord view switching, priority hotkeys, and status cycling
• Real-time updates over WebSocket: edits from one tab, the CLI, or an MCP agent show up live everywhere
• sg next to pick the best unblocked task, sg stats for a progress/agents/activity dashboard, sg export for JSONL state snapshots
• MCP server for Claude Code (auto-resolves the current project, bulk create / update / delete with #0..#N cross-references)
• Pi extension, embedded in the binary, for task-aware AI sessions
• OpenCode MCP integration
• Auto-start service (opt-in: launchd, systemd, or Windows Task Scheduler)
• Single binary, no external runtime dependencies, LMDB-backed storage

Preview

Three themes, three views, same live data.

Obsidian · List — dark cool-steel chrome, grouped by status, detail panel open.

Console · Graph — amber phosphor CRT, top-down dependency DAG with live agent tail. (click to expand)

Dossier · Kanban — editorial paper-and-ink, serif display, four-column board. (click to expand)

Install

macOS / Linux

curl -fsSL https://git.nocfa.net/NocFA/segments/raw/branch/main/scripts/install.sh | bash

Downloads a pre-built binary for your platform. Falls back to building from source if no binary is available.

Prerequisites (source build only): Go 1.24+ and a C compiler (CGO_ENABLED=1 is required for LMDB).

Windows

powershell -ExecutionPolicy Bypass -Command "irm https://git.nocfa.net/NocFA/segments/raw/branch/main/scripts/install.ps1 | iex"

Downloads a pre-built binary. Falls back to building from source if no binary is available. Installs to %USERPROFILE%\.local\bin and adds it to the user PATH.

Prerequisites (source build only): the script auto-installs missing dependencies via winget:

• Go 1.24+ via winget install GoLang.Go
• MinGW-w64 (GCC) via winget install BrechtSanders.WinLibs.POSIX.UCRT

Git and winget ship with Windows 10/11.

From source (any platform)

git clone https://git.nocfa.net/NocFA/segments.git
cd segments
make install

Requires Go 1.24+ and a C compiler (CGO_ENABLED=1 for LMDB).

Quick start

sg setup    # configure integrations (Pi, Claude Code, OpenCode)
sg start    # start the server

Open http://localhost:8765.

Usage

sg help

  Server
    start         start the server                                (serve)
    stop          stop the server

  Tasks
    list          list projects and tasks                         (status)
    next          pick the best next task to work on              (n)
    stats         dashboard: progress, agents, recent activity    (st)
    view          view full task details
    add           create a task
    done          mark a task as done
    close         close a task
    rm            delete a task                                   (delete)
    rename        rename a project

  Setup
    setup         configure integrations (required first)         (install)
    init          initialize a project in the current directory
    beads         import tasks from Beads
    export        dump task state as JSONL for git-workflow snapshots
    remove        remove a project
    uninstall     remove segments and all data

  Info
    help          show help
    version       print version

sg list auto-detects the current project from the working-directory name. Pass -a to include completed tasks. Passing a task-ID prefix to list falls through to view.

sg view <id> prints the task's title, status, priority, blockers, timestamps, and body.

sg next prints the single best unblocked task to pick up (highest priority, oldest wins), followed by the rest of the ready queue.

sg stats renders a compact progress / agents / recent-activity dashboard rendered in the current theme.

sg export streams task state as JSONL (one event per line) suitable for git-tracked snapshots or downstream pipelines. Configure a path in config.yaml to have every CLI / MCP mutation append automatically.

Web UI

Open http://localhost:8765 and pick a theme from the dropdown in the top bar.

Theme	Vibe
Obsidian	Refined near-black chrome with a cool-steel accent (default)
Console	Amber phosphor, monospace, ASCII framing, live agent tail
Dossier	Editorial paper-and-ink, serif display, rubber-stamp accents

All three themes support a light and a dark mode; toggle with the sun/moon button.

Views

• List: tasks grouped by status, from in-progress through blocker, todo, done, and closed. Inline priority bars, blocker chips, and an expandable detail panel.
• Kanban: a four-column board (todo / in-progress / blocker / done). Drag a card between columns to change its status; the update is applied optimistically and reconciled via WebSocket. Closed tasks are not shown on the board; flip back to List to reopen them.
• Graph: a top-down dependency DAG. Ready tasks (no outstanding blockers) get an accent ring; tasks that are currently blocking other work get a warning border.

Switch views with the tabs in the top bar.

Real-time updates

Every tab connects over WebSocket and receives live deltas for task and project changes, whether those come from another tab, the CLI (sg add, sg done, sg close), or the MCP server. New tasks slide in; edits pulse briefly.

Command palette

Press Ctrl+K (or Cmd+K on macOS) anywhere to open the command palette: fuzzy-jump between projects, views, and tasks in a single keystroke.

Keyboard shortcuts

• j / k (or arrow keys): navigate tasks
• g l / g k / g g: switch to List / Kanban / Graph view
• c: compose a new task
• e: edit the selected task's body
• t: cycle the selected task's status
• 1 / 2 / 3 / 4: set the selected task's priority (4 clears it)
• /: focus search
• Ctrl+K / Cmd+K: toggle the command palette
• Esc: close dialogs, combos, the detail panel, or blur inputs
• Enter: open the selected task's detail panel

Integrations

Tool	How	Status
Claude Code	MCP server + SessionStart hook	Working
Pi	Embedded TypeScript extension	Working
OpenCode	MCP server	Working

Run sg setup once to configure globally, or sg init inside a project directory for local config.

The Claude Code integration exposes MCP tools for creating, updating, listing, and deleting tasks, with bulk variants (segments_create_tasks, segments_update_tasks, segments_delete_tasks) to scaffold or sweep whole queues in one round-trip. segments_create_tasks understands #0..#N back-references so dependency chains can be wired up inline. A SessionStart hook injects the current project context into every new Claude session, and project_id auto-resolves from the CWD so most calls can omit it.

Claude Code: avoiding first-call friction

Claude Code defers MCP tool schemas behind its ToolSearch lazy-loader by default -- schemas aren't loaded until the model searches for them, which adds a round-trip on the first Segments call of every session. Because Segments is cross-session infrastructure, that round-trip is exactly where the model is most likely to fall back to TodoWrite and silently lose continuity.

Two orthogonal controls help:

• Schema loading is controlled by the ENABLE_TOOL_SEARCH env var. Set ENABLE_TOOL_SEARCH=false in Claude Code's environment to load all MCP tool schemas upfront (no deferral, no ToolSearch needed). This is the only knob that actually flips inline-vs-deferred loading. It applies to every MCP server on the host. Claude Code also reads it from settings.json under env.
• Permission prompts are controlled by permissions.allow. A "mcp__segments" entry there pre-authorizes every Segments tool so no "allow this tool?" prompt fires on first use. This does NOT affect schema loading -- the schemas can still be deferred.

sg setup writes three things into the settings.json for the chosen scope (~/.claude/settings.json global, or .claude/settings.json local):

1. The SessionStart hook (segments context) -- emits a compact segmentsContext banner plus the per-project ready queue so the agent can orient without any tool call. The MCP server's serverInstructions carries the stable "how to use Segments" prose (including a ToolSearch select:mcp__segments__* pre-load line for sessions where schemas are deferred).
2. A permissions.allow entry for mcp__segments -- preauthorizes every Segments tool, so no permission prompts on first use.
3. The MCP server registration (via claude mcp add for global, or .mcp.json for local).

If you prefer to wire it up by hand, the equivalent settings.json snippet is:

{
  "env": { "ENABLE_TOOL_SEARCH": "false" },
  "permissions": { "allow": ["mcp__segments"] },
  "hooks": {
    "SessionStart": [
      { "hooks": [{ "type": "command", "command": "segments context" }] }
    ]
  }
}

The env line is optional -- leaving it out means Segments schemas stay deferred until the ToolSearch pre-load line fires on first use.

Configuration

Config lives at ~/.segments/config.yaml (override the directory with $SEGMENTS_DATA_DIR):

port: "8765"
bind: "127.0.0.1"
data_dir: "~/.segments"

# session_start_inject: true   # append a segmentsContext banner to `sg context`
                               # output (CWD-resolved project, in-progress, recently
                               # closed). Set false to emit only the legacy listing.

# jsonl_export:
#   enabled: true
#   path: ".segments/tasks.jsonl"
#   scope: all            # all | project
#   project_id: ""        # required when scope=project; UUID or prefix
#   on_events: []         # subset of [created, updated, done, closed, deleted]; empty = all

Uncomment jsonl_export to have every CLI / MCP mutation append to a JSONL file (handy as a git-tracked audit log alongside the code). sg export performs the same dump on demand.

On Windows the default data directory is %USERPROFILE%\.segments.

Development

make build       # build the binary
make install     # build and install to ~/.local/bin (first-time)
make reinstall   # stop daemon, back up data, rebuild, reinstall, restart (iterative dev)
make stress      # build the bin/stress load generator

make install is the minimal first-install path. For iterative development use make reinstall (or scripts/dev-install.sh / scripts/dev-install.ps1): it stops the running daemon, snapshots data to ~/.segments-backup-<ts>.jsonl, overwrites every binary path the host shell might resolve (including the bare sg that Git Bash on Windows prefers over sg.exe), and can restart the daemon with --start / -Start.

Tests:

CGO_ENABLED=1 go test ./...

Cross-compile:

make cross-linux-amd64     # static linux amd64 (requires musl-gcc)
make cross-linux-arm64     # linux arm64 (requires aarch64-linux-musl-gcc)
make cross-windows-amd64   # windows amd64 (requires x86_64-w64-mingw32-gcc)

Version is injected via -ldflags "-X main.version=$(VERSION)" from git describe.

Platforms

OS	Arch	Status
macOS	arm64	CI tested
Linux	amd64	CI tested (musl-static)
Linux	arm64	Cross-compiles
Windows	amd64	CI tested (cross-compiled with MinGW-w64)

License

MIT