menger Run your own

The guide

How to use menger

Everything the front page shows, in the order you meet it. Ten parts; each stands on its own.

What it is

menger tracks a plan as a tree of tickets. People write it; people and agents carry it out. Every ticket lives in a shortcode: OFFLINE-6 is the sixth ticket of OFFLINE. A shortcode starts with a root — a scope, or a doc — and shortcodes nest under one another, so all of a team's work is one tree.

Every ticket has a kind:

  • scope breaks into children: a branch of the plan.
  • build makes something that did not exist.
  • execution carries out a procedure, like a rollout.
  • gap a defect in what shipped.
  • spike answers a question.
  • doc not work: a finding, a manifest, a reference. It has no lifecycle.

A ticket's outputs are tickets. A spike's answer, a report or a checkpoint is filed as a child of the ticket that produced it, so the tree shows where every result came from. Bodies are markdown and may hold diagrams, HTML and live components.

The board and a ticket

The app opens on the board: every ticket you can read, one line each, beside the nav — the tree of shortcodes, each with its done/total. Open a ticket for its page: status, kind, parent, blockers, body, children and the commits that finished it. A change made anywhere appears on your screen as it happens.

A ticket page: OFFLINE-6 In Review, its kind, parent and shortcode, the commit that finished it, the tickets it waits on and the ones it unlocks, and a diagram in its body.

The lifecycle

  1. PendingWritten down, not yet approved. Work does not start; a person promotes it.
  2. ReadyApproved. It can start once everything it waits on is done.
  3. CodingSomeone has started. Set the moment work begins, so nothing is claimed twice.
  4. In ReviewFinished and committed; waiting to be merged.
  5. CompleteMerged. Done.

Beside the line: Superseded replaced by another ticket · Canceled will not be done · Blocked a marker · Draft not yet promoted · Epic a scope's status · Doc a doc's only status.

What waits on what

A ticket names the tickets it is blocked by. A blocker is satisfied when it is Complete, Superseded or Canceled. The ready set is every Ready ticket whose blockers are all satisfied: what can start now. The wave board (#/waves/<SHORTCODE>) lays a shortcode's work out in order — wave 1 can start now, wave 2 once wave 1 lands — and moves the cards as the work moves.

Inside a ticket: mockups, diagrams, pages

A body is markdown, and may hold more: a ```mermaid diagram, drawn in place; HTML with its own styles and scripts; and the house components, a decision among them. A body with markup renders in a frame of its own, sandboxed from the app, so what an agent puts there is the thing itself — a screen to look at, a site to click through, a plan drawn as a graph — not a picture of it, and it sits beside the question it raises.

A ticket page: an agent's mockup of a phone's conflict screen, two versions side by side; beneath it a decision with three options and their costs; along the bottom edge a red tab marked now.

A whole HTML document is shown as itself. One that declares view: mockup in its frontmatter — or <meta name="menger-view" content="mockup"> in its head — is drawn in device frames at each of its widths (390, 1440, say), side by side at one scale, each a viewport of its own; the bar above them picks one device or all, light or dark, and reduced motion, and the page sees each as its own media query. z fills the screen with it.

A ticket page holding a help page an agent built, drawn in a phone frame and a desktop frame side by side; above them the mockup's bar: All, 390, 1440, Light, Dark, Reduced motion, Full screen.

Your own components. A ```component fn-banner block in any ticket defines a custom element: its <template>, <style>, <docs> — a summary, its attributes, the parts a theme may skin, examples — and <script>. The registry keeps it, so any body may write <fn-banner state="syncing" count="1">; Components in the header lists every one with its owner and what references it, and #/components/fn-banner is its help page, the examples live. The house components — decisions, inputs, steps, results — are defined the same way, in a ticket.

The help page of fn-banner, a component the team defined: its summary, a live preview, its attributes, the parts a theme may skin, three examples rendered beside their markup, and the ticket that owns it.

Such a body is filed as a doc under the work it belongs to — a mockup under the build it is for, a page under the build that asks about it, a site map beside the decision it informs — so the tree says where it came from. The frame talks to nothing but menger: a body's script may read and write tickets through window.menger, and nothing else.

Finding things

Filters reach every view. The header's Filter button (F) filters everything; each view — board, wave board, nav, inputs — has its own (f). Pick categories from the menu, or type the filter language:

The board's filter menu, open, with rea typed: it offers Ready, and Status: Ready with four tickets.
  • ready and kind build builds that can start
  • status in (Pending, Ready) not started
  • category in (active, review) in flight
  • not category done everything open
  • under OFFLINE-6 a ticket and everything below it
  • ready and kind build and in SYNC combined

A filter rides the page's address, so a link brings it back; Saved ▾ keeps one under a name for everyone. Right-click any tag — a shortcode, a status, a kind — to filter by it.

Search looks inside titles and bodies: every word required, prefixes and typos forgiven, best match first. The palette (/ or Ctrl+K, ⌘K on a Mac) jumps to a ticket by id or title and shows matching passages below.

The palette over the board with photo typed: two tickets match by title, and two more match in their bodies, each with the passage that matched.

Keys

The whole app works from the keyboard; ? shows this list in the app
/ or Ctrl+Kjump to a ticket (⌘K on a Mac)
j / ↓next row (nav tree, board)
k / ↑previous row
l / →expand a group, or step into it
h / ←collapse a group, or step out to it
Home / Endfirst / last row
Enteropen the focused ticket
g hgo to the board
ffilter this view
Ffilter every view
/ filter SCthe global filter becomes a shortcode's tree
aannotation mode: click anything to comment on it
Shift+F10the focused ticket's menu
?the list of keys
Escclose the palette or the list; leave annotation mode

Inputs: questions asked inside a ticket

A ticket can ask its owner something and keep the answer: a decision (pick one), a multi (tick any) or a text reply. You answer on the ticket's own page; every answer is kept with its history. Agents ask; the owner answers.

A decision inside a ticket: the question, three options each with its cost and benefit, the recommended one picked, and the Submit button.

Whoever asked acts on the answer, then closes the input, which freezes it: DECIDED. #/inputs lists everything waiting on you across every ticket; once you have opened it, the header counts what is still open.

The queue: a question put in front of you

An input waits under Needs you until you look. When it should not wait — an agent idle until it is answered, a deploy that rolled back — the agent queues the ticket, with an urgency (whenever, today, now, blocking) and a reason. Every open app shows it at once as a tab along the bottom edge of the main column; now and blocking are red, taller, and nudge until opened. A tab that arrives while you look flashes in its colour.

Click the tab: the urgency, who queued it and why, and the question with its options, answerable right there — or open the ticket, snooze 10m, done with it. Answering takes the ticket out of the queue; the input stays the agent's to close. A ticket is queued once: queued again, its urgency rises, never falls.

synapse -P 4455 menger tickets queue --id OFFLINE-14 --urgency now --input layout \
  --reason 'OFFLINE-8 is idle until the layout is picked'
synapse -P 4455 menger tickets queued                       # most urgent first, then oldest
synapse -P 4455 menger tickets snooze --id OFFLINE-14 --minutes 30
synapse -P 4455 menger tickets list --filter 'queued now or queued blocking' --summary true

Comments and notes

Comments are a reader's notes on the app itself. Press a (or Annotate in the header): every element is outlined — inside ticket bodies too — and a click opens a comment box right there. Numbered pins mark what has open comments, each with Resolve. #/comments lists them all, each linking back to its spot; a ticket's page counts its open ones.

Annotation mode on a ticket page: every element outlined, the title picked, and a comment box open beside it with a comment typed.

Notes are thoughts written down before they are tickets: dated, untitled, on no shortcode. When one is ready, upgrade it and it becomes a ticket, its text the body.

Deployments: where the work runs

Your CI records each deploy with one call — the project, the environment, its state, the revision and the commits it carries — and menger works out which tickets those commits finished. A ticket's page says where it runs; a board row carries a mark per environment; #/deployments shows each environment, every deploy and what it carried, and the Complete work still waiting for the last one. A rollback takes out what only the undone deploys carried. A deployment never moves a status.

The deployments page for OFFLINE: beta and prod as columns, each with what it runs and its deploys and the tickets they carried, and above them the Complete work still waiting for prod.
synapse -P 4455 menger deployments record --project OFFLINE --environment prod --state succeeded \
  --revision c2e9f55 --commits 3f9c2a1,8b41d07,c2e9f55 --release 4.1.2
synapse -P 4455 menger deployments for_ticket --id OFFLINE-5
synapse -P 4455 menger tickets list --filter 'category done and not deployed prod' --summary true

deployed prod and not deployed prod are filter cells, so a board, a wave board or a saved filter can show what reached an environment and what did not.

From the command line

Everything menger does is a Plexus RPC method — there is no side door, so the app, scripts and agents make the same calls. synapse is the CLI for any Plexus backend. Point it at your server's WebSocket port (4455 by default). Parameters are flags; <method> --help lists them.

synapse -P 4455 menger tickets health
synapse -P 4455 menger tickets list --filter 'blocked' --summary true --limit 20
synapse -P 4455 menger tickets work ready --filter 'kind build' --summary true
synapse -P 4455 menger tickets search --query 'outbox replay'
synapse -P 4455 menger tickets get --id OFFLINE-6
synapse -P 4455 menger tickets watch                     # every change, live
synapse -P 4455 menger tickets create --epic HOME --kind scope --title 'Home'
synapse -P 4455 menger tickets create --epic HOME --title 'Fix the gate' --kind build
synapse -P 4455 menger tickets set_status --id HOME-2 --status Ready
synapse -P 4455 menger tickets commits link --id HOME-2 --commits 77df9a0
synapse -P 4455 menger tickets inputs list --state open
synapse -P 4455 menger tickets inputs answer --ticket OFFLINE-7 --input policy \
  --value.type choice --value.option merge --rationale 'crews edit different fields'
synapse -P 4455 menger comments list --state open
synapse -P 4455 menger notes add --body 'the palette should remember its last query'
synapse -P 4455 menger notes upgrade --id 1 --epic HOME

The first ticket of a shortcode must be a scope or a doc. Global options (-P, -j for JSON) go before menger.

Run your own

menger is one binary and a SQLite file as its system of record. --features embedded-app builds the web app into that binary, so the one file serves the app, the WebSocket and REST with nothing beside it. With Rust installed:

cargo install menger --features embedded-app
menger --db-path ~/menger/tickets.db
# the app       http://127.0.0.1:4456/
# WebSocket     ws://127.0.0.1:4455   (synapse -P 4455 …)
# REST + SSE    http://127.0.0.1:4457 (--no-rest turns it off)

Other ports: --port (WebSocket), --shell-port (the app), --rest-port. Open the app in two windows, change a status in one, and watch the other follow. Everyone who can reach the ports can use it, so keep them on the machine or behind your own network. Before a deploy, menger --verify-derived --db-path … checks the file.