Skip to content
Back to search

maestro

Local-first coordination for human and agent work: durable work, decisions, dispatches, evidence, and prompt-first methods, powered by TypeScript and Bun.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/reinamaccredy--maestro/badge.svg)](/listings/reinamaccredy--maestro)

HTML

<a href="/listings/reinamaccredy--maestro"><img src="/api/listings/reinamaccredy--maestro/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Maestro is distributed from source. Install with one command (needs `git` and [Bun](https://bun.sh)):

curl -fsSL https://raw.githubusercontent.com/ReinaMacCredy/maestro/main/scripts/install.sh | sh

The script clones the repository into `~/.maestro/source` (override with `MAESTRO_SOURCE_DIR`; `MAESTRO_REF` picks the branch, default `main`) and runs the installer from that checkout, which `maestro update` then follows. From your own checkout, run the installer directly:

bun bin/maestro.ts install
maestro version

Install copies the runtime to `~/.maestro/runtime`, writes the shim at `~/.local/bin/maestro`, records the source checkout in `~/.maestro/source.json`, and wires the current repository. When replacing an older executable, it preserves that executable as `maestro-legacy` if no rollback executable already exists.

Install also scaffolds `~/maestro`, the Supervisor room, and registers the current repository there, and writes the shared method to `~/maestro/WORKFLOW.md`. It materializes ten managed skills under `~/maestro/skills`: `maestro-bundle`, `maestro-design`, `maestro-work`, `maestro-verify`, `maestro-improve`, `maestro-council`, and the read-only `maestro-explore`, `maestro-diagnose`, `maestro-coach`, and `maestro-questionnaire`. The installer links those skills for Claude without overwriting unmanaged skills.

Use `maestro update` to fetch the recorded source checkout, accept only a fast-forward, and resync the runtime. It refuses dirty, diverged, missing, or unreachable sources without partially updating the runtime. Use `maestro install` from the source checkout for an offline resync.

Use `maestro uninstall` to remove Maestro-managed hooks, settings keys, and mirror blocks from the current repository. It is idempotent and does not delete repository data, the machine runtime, the shim, or the Supervisor room.

`maestro doctor` inspects the shim, runtime stamp, recorded source, repository wiring, permissions, and store access without repairing them. A healthy report exits zero; a reported problem names the next command when the repair is mechanical.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 320 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # maestro
  2. Maestro is a local-first coordination system for human and agent work. It keeps
  3. durable work, decisions, sessions, evidence, dispatches, and handbacks in each
  4. repository's shared Git root. It is written in TypeScript, runs on Bun, and does
  5. not require a background service.
  6. Documentation: [maestro.maccredyreina.me](https://maestro.maccredyreina.me/)
  7. Version 0.108.0 is the first TypeScript release. It continues the version line
  8. after 0.107.x, the final Rust release.
  9. ## Three layers
  10. - **Mechanism kernel** owns the SQLite store, event log, sessions, CLI dispatch,
  11. plugin loading, and readiness projection. It does not impose workflow policy.
  12. - **Plugins** provide verbs and optional policy gates. Repositories enable or
  13. disable policies such as proof and breakdown in `.maestro/config`.
  14. - **Recipes and skills** provide prompt-first working methods as Markdown. Use
  15. `maestro recipe list` to browse recipes and `maestro recipe show <name>` to
  16. read one without copying it into a repository.
  17. ## Install, update, and remove
  18. Maestro is distributed from source. Install with one command (needs `git`
  19. and [Bun](https://bun.sh)):
  20. ```sh
  21. curl -fsSL https://raw.githubusercontent.com/ReinaMacCredy/maestro/main/scripts/install.sh | sh
  22. ```
  23. The script clones the repository into `~/.maestro/source` (override with
  24. `MAESTRO_SOURCE_DIR`; `MAESTRO_REF` picks the branch, default `main`) and runs
  25. the installer from that checkout, which `maestro update` then follows. From
  26. your own checkout, run the installer directly:
  27. ```sh
  28. bun bin/maestro.ts install
  29. maestro version
  30. ```
  31. Install copies the runtime to `~/.maestro/runtime`, writes the shim at
  32. `~/.local/bin/maestro`, records the source checkout in
  33. `~/.maestro/source.json`, and wires the current repository. When replacing an
  34. older executable, it preserves that executable as `maestro-legacy` if no
  35. rollback executable already exists.
  36. Install also scaffolds `~/maestro`, the Supervisor room, and registers the
  37. current repository there, and writes the shared method to
  38. `~/maestro/WORKFLOW.md`, which routes each kind of task to a playbook
  39. (`maestro recipe list`). It materializes nine managed skills under
  40. `~/maestro/skills`: `maestro-bundle`, `maestro-design`, `maestro-work`,
  41. `maestro-verify`, `maestro-improve`, `maestro-council`, `maestro-graph`, and
  42. the read-only `maestro-coach` and `maestro-questionnaire`. The
  43. installer links those skills for Claude without overwriting unmanaged skills.
  44. Use `maestro update` to fetch the recorded source checkout, accept only a
  45. fast-forward, and resync the runtime. It refuses dirty, diverged, missing, or
  46. unreachable sources without partially updating the runtime. Use
  47. `maestro install` from the source checkout for an offline resync.
  48. Use `maestro uninstall` to remove Maestro-managed hooks, settings keys, and
  49. mirror blocks from the current repository. It is idempotent and does not delete
  50. repository data, the machine runtime, the shim, or the Supervisor room.
  51. `maestro doctor` inspects the shim, runtime stamp, recorded source, repository
  52. wiring, permissions, and store access without repairing them. A healthy report
  53. exits zero; a reported problem names the next command when the repair is
  54. mechanical.
  55. ## SLP supervised teams
  56. SLP v2 uses one direct Herdr workspace per running team generation:
  57. ```mermaid
  58. flowchart TB
  59. Hub["Hub Supervisor"] <--> Team["Team Supervisor"]
  60. Team <--> Lead
  61. Team <--> PeerA["Peer A"]
  62. Team <--> PeerB["Peer B"]
  63. Lead <--> PeerA
  64. Lead <--> PeerB
  65. PeerA <--> PeerB
  66. ```
  67. In the supported SLP flow, the Hub Supervisor reaches the team only through
  68. its Team Supervisor. Inside the team, the Team Supervisor, Lead, and Peers
  69. communicate directly. Every seat launches as a native harness profile
  70. (`claude --agent maestro-<seat>` or `codex --profile maestro-<seat>`) rendered
  71. by `maestro install` from a maestro-owned profile file, so its mandate is its
  72. system prompt and survives `/clear`. Attention is the seat's own
  73. `work note --blocked`, pushed one seat up; there is no Observer, Advisor,
  74. scheduler, or background agent role.
  75. SLP is a cooperative-agent protocol, not a shell security sandbox. Maestro
  76. checks the nine SLP operations at their supported boundaries: Hub operations
  77. must run from the Hub room, while project role operations require the current
  78. generation's stored Herdr pane binding. It does not block native commands,
  79. administrative Maestro commands, or direct Herdr calls; topology and
  80. external-effect limits remain obligations enforced by the Human and host
  81. policy.
  82. The canonical Workspace Pack lives at `~/maestro/SLP.md`. Starting a team
  83. copies its exact bytes to `<project>/.maestro/SLP.md`, pins its version and
  84. digest for that generation, creates exactly one Team Supervisor and one Lead,
  85. and creates initial `OPEN` work for the Lead. Peers are opened lazily by
  86. assigned work. `maestro team start --lead-only` opens the other shape, one Lead
  87. plus the runtime pane and no Team Supervisor; the shape is pinned for the
  88. generation and the Hub Supervisor is that Lead's reviewer.
  89. `--lead-model`, `--peer-model` and `--supervisor-model` pick a seat's model
  90. for the generation on its launch line, leaving the profile, its digest and the
  91. pack untouched; `maestro work add --to <peer> --model <model>` does the same
  92. for one Peer. Install seeds the
  93. Hub pack only when it is absent; later installs and updates preserve owner
  94. edits.
  95. SLP roles use exactly nine operations:
  96. ```text
  97. maestro team start
  98. maestro team stop
  99. maestro status [work-id]
  100. maestro work add
  101. maestro work take
  102. maestro work note
  103. maestro work return
  104. maestro work accept
  105. maestro decide
  106. ```
  107. Work moves only through `OPEN -> ACTIVE -> RETURNED -> DONE`. Lead accepts
  108. Peer returns; Team Supervisor accepts Lead returns. Settled choices use one
  109. immutable `maestro decide` record and explicit replacement.
  110. `team start` opens one runtime pane per generation through Maestro's Herdr
  111. plugin (`maestro install` links it). The runtime pane is not an agent: it
  112. holds the generation's Herdr event subscription, renders the team's pane
  113. output, and records a `blocked` pane or an idle pane that still holds ACTIVE
  114. work as a `stall:dialog` or `stall:silence` entry by the actor `runtime`,
  115. nudging the stuck seat once per item and kind until the store changes. A seat
  116. that needs a fact from above records `work note --blocked`; Maestro pushes
  117. the `BLOCKED` line one seat up without changing the work state.
  118. When the owner types directly into a seat's pane, the seat records the walk-in
  119. first with `maestro work note <id> "owner asked: <what>" --owner`: provenance
  120. only, exclusive with `--blocked` and `--rework`, it sets no blocked flag and
  121. pushes an `OWNER` line one seat up. Inside the item's objective the seat acts
  122. at once; outside it the item is not widened and new work is opened instead.
  123. The Hub room holds the owner's declared presence. `maestro owner here` and
  124. `maestro owner away` record it on her own words, `maestro owner` prints it, and
  125. the Hub prompt line and the room's `maestro status` carry `owner: here|away`.
  126. While she is away, an owner-scope blocker that has reached the Hub is ruled at
  127. once with `maestro decide "<choice>" --why "<reason>" --work <id>
  128. --provisional` so the team continues; that `maestro status` lists every
  129. provisional ruling until she confirms it with `maestro decision confirm <id>`
  130. or supersedes it with a decision that `--replaces` it. An away presence never
  131. grants commit, push, tag, release, install mid-generation, or any destructive
  132. change. Like `decision`, `owner` and `decision confirm` are Hub-room verbs, not
  133. SLP operations: the nine above stay the whole role surface.
  134. Normal stop uses one transient foreground non-agent helper pane in the Hub so
  135. the Team Supervisor can close itself safely. This is internal, not another SLP
  136. operation: `STOPPED` is recorded only after the team workspace is absent, and
  137. a partial close remains `RUNNING` for retry.
  138. Read the compact operating guide with `maestro recipe show slp` and the full
  139. setup at [SLP setup and storage](https://maestro.maccredyreina.me/getting-started/slp-setup/).
  140. ## Work, decisions, and evidence
  141. - `maestro status` shows session identity, held work, and live peers;
  142. `maestro ready` shows work that can start and the gates blocking other work.
  143. - `maestro work` manages work trees, dependencies, leases, notes, cancellation,
  144. claims, and proof.
  145. - Method rules live in [WORKFLOW.md](src/plugins/resources/WORKFLOW.md), installed
  146. to `~/maestro/WORKFLOW.md`. Inspect the task before choosing **quickfix**,
  147. **Light**, or **Full** by risk and coordination needs. Session changes use
  148. checkpoints, not automatic bundles. Verification is required; new tests
  149. need a concrete gap in existing checks. Completion and delivery are separate.
  150. - `maestro decision` records draft, locked, and superseded choices with their
  151. rationale and work links. Supersession takes effect when the replacement is
  152. locked, not while it is still a draft.
  153. - Cross-role decisions are drafted in the store before a Herdr prompt names the
  154. sender role and decision id. The answer is the locked or superseding record;
  155. non-decision questions and answers are work notes.
  156. - `maestro dispatch` stores lane contracts and council state;
  157. `maestro handback` stores shape-checked return packets, including explicit
  158. dependency, council, challenge, reopen, unknown, and failure outcomes.
  159. - `maestro search` searches native work, decisions, notes, terms, memory facts,
  160. events, bundles, and imported Rust records, in this store and in the Hub room
  161. at `~/maestro`; `--local` stays in this store.
  162. - `maestro term` keeps the glossary in the store so a term answers the same
  163. search as the work and decisions that use it.
  164. - `maestro memory` runs in the Hub room: `ingest` promotes facts from the Claude
  165. auto-memory and Codex ad-hoc buffers through supersession, dedup and evidence
  166. gates, `retract` retires one for good, and `render` writes the injected global
  167. index from the store and refuses to overwrite a hand edit.
  168. Proof is layered as `source`, `artifact`, `installed`, `live`, and `journey`.
  169. Claims stop at the last proven layer and name untested links rather than
  170. rounding them up to completion. Repeated failures route by holder: Peer-held
  171. work reaches the Lead through the repository brief; Lead-held work reaches the
  172. Supervisor through the room brief.
  173. Failed commands emit a JSON error envelope on stderr and exit nonzero. Empty or
  174. whitespace-only required arguments are rejected rather than interpreted as
  175. missing identities or targets.
  176. ## Verb tour
  177. - `maestro status` shows sessions and leases; `maestro ready` shows startable
  178. and gated work.
  179. - `maestro work add|start|note|done|show|list` manages the work lifecycle.
  180. - `maestro decision draft|lock|confirm|show|list` manages durable choices;
  181. `confirm` clears a provisional Hub ruling.
  182. - `maestro owner` reads the Hub room's declared owner presence, or records it
  183. as here or away.
  184. - `maestro dispatch open|accept|show|list` stores lane contracts, while
  185. `maestro handback file|show` stores and reads return packets.
  186. - `maestro attention` scans the current repository and `maestro brief`
  187. summarizes every registered repository.
  188. - `maestro term add|list|show` keeps the glossary; `maestro memory
  189. ingest|list|show|retract|render` runs the Hub memory.
  190. - `maestro bundle open|close|pause|resume|list|show|save|import` runs design
  191. bundles; `import` brings a `.waymark/` tree in with an item-by-item report
  192. and a dry run.
  193. - `maestro recipe list|show` serves methods; `maestro plugin list|enable|disable`
  194. manages the configured extension set.
  195. - `maestro graph run|next|result|show|list|trust` drives a pre-known
  196. multi-agent path from one graph markdown file; maestro executes the
  197. deterministic nodes and hands the agent nodes back to whichever harness
  198. is driving.
  199. - `maestro import rust` imports preserved Rust data; `maestro legacy show`
  200. reads imported cards and files.
  201. - `maestro install`, `maestro update`, `maestro uninstall`, and
  202. `maestro doctor` manage and diagnose the source-installed runtime.
  203. - `maestro version` reports the package version and installed commit.
  204. ## Attention and brief
  205. `maestro attention` computes current attention packets at read time. It detects
  206. stalled leases, repeated failures, stale decisions, scope collisions,
  207. unreturned dispatches, and returned handbacks that have not been reviewed. It
  208. records no mailbox message and runs no daemon.
  209. `maestro brief` reads the registry in `~/maestro/registry`, opens each project
  210. in observer mode, and reports only what needs attention. Missing repositories
  211. are named and skipped. When every registered project is running normally, the
  212. brief says so in one line. The `hm` shell function focuses the Supervisor room
  213. and prints this brief; it does not start an agent.
  214. ## Observer mode
  215. This is the read-only store mode for administrative inspection. It is not an
  216. SLP seat and does not create a background process.
  217. Set `MAESTRO_READ_ONLY=1` to run Maestro as an observer. Pure commands such as
  218. status, search, recipes, and read-only list/show operations remain available.
  219. Mutating commands fail with `READ_ONLY`; external plugins are not loaded; and
  220. session, lease, and liveness state is not persisted. Search fails closed if its
  221. index cannot be refreshed rather than returning stale results as current.
  222. ## Harness integration
  223. `maestro install` writes managed adapters for Claude and Codex and merges only
  224. the managed hook entries. `SessionStart` and `UserPromptSubmit` record the
  225. session and print its current brief. Small managed blocks in `CLAUDE.md` and
  226. `AGENTS.md` point agents to status, ready work, and recipes. No hook sends
  227. mail, pushes a dispatch into another session, or delivers PostToolUse packets.
  228. ## Recipes, skills, and plugins
  229. `maestro recipe list` and `maestro recipe show <name>` serve the shipped
  230. Markdown methods. The installed skills drive bundle, design, work, and
  231. verification lifecycles, plus read-only explore, diagnose, coach, and
  232. questionnaire engagements. `maestro plugin` lists and manages built-in, global,
  233. and repository plugins; policy plugins remain removable instead of being
  234. baked into the kernel.
  235. Use `maestro help` for the complete verb list and `maestro <verb> --help` for
  236. the current syntax and flags.
  237. ## Rust-era data
  238. The last Rust stores are preserved under `legacy/rust/`. Import the card store
  239. read-only with:
  240. ```sh
  241. maestro import rust --path legacy/rust/store.sqlite
  242. ```
  243. Add `--promote` to create native work, decisions, and provenance notes:
  244. ```sh
  245. maestro import rust --path legacy/rust/store.sqlite --promote
  246. ```
  247. Promotion preserves card kinds, terminal outcomes, decision links,
  248. supersession chronology, and receipt provenance. Orphan receipts are skipped
  249. and counted. The `legacy_map` table makes repeated promotion idempotent.
  250. Archived Rust snapshots can also be imported for search:
  251. ```sh
  252. maestro import rust --path legacy/rust/archive-cards.sqlite
  253. ```
  254. Bun decodes zstd snapshot payloads when possible and falls back to stored
  255. search text when it cannot. Imported records remain available through
  256. `maestro search` and `maestro legacy show <id>`. See
  257. [`legacy/rust/README.md`](legacy/rust/README.md) for the preserved datasets and
  258. their exact counts.
  259. ## Contributing, security, and license
  260. Contributions follow the toolchain, layout, and pre-pull-request checks in
  261. [`CONTRIBUTING.md`](CONTRIBUTING.md). Report a suspected vulnerability through
  262. the private channel in [`SECURITY.md`](SECURITY.md), never a public issue.
  263. Maestro is released under the MIT license; see [`LICENSE`](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.