Maintain many repositories from one place.
If you keep dozens of small projects, the work is not hard, it is scattered. Each repository has a TODO.md, failing CI, outdated dependencies and a dirty working tree, and finding out means opening all of them. pma reads them all in one pass, ranks every task across every project in one list, and can hand a task to a coding agent in your clone, or in a throwaway worktree. You read the diff, and pma commits it and opens a pull request or pushes.
A full scan of 112 repositories took 35 to 61 seconds here, nearly all of it GitHub. After the first, you rarely need one.
Nothing is published without you. An agent runs with no push credentials in its environment, pma runs the project's tests itself rather than trusting the agent's report, and every change waits unstaged until you approve it.
pma root add ~/projects # git repos directly under it are projects
pma project tier 1 myproject # 1 is most important, 5 least
pma scan # TODO.md, git state, CI
pma # next: tasks for agents, and what waits on you
pma run review myproject # a review, confirmed, findings printed
pma run fix-ci myproject # fix failing CI in the clone; the edit waits for review
pma dispatch myproject:31 # hand line 31 to an agent
pma review 1 # the diff, the test result, the cost
pma stage 1 # into your clone's index; `git diff --cached`
pma push 1 # commit and push it; or `pma pr 1` after --approveOne view of everything
-
pma next, orpmaalone: one list of tasks for agents, in the orderpma dispatch --autotakes them, and one of what waits on you: runs to review, publish or merge, then critical or urgent tasks no agent may take. -
Every task in every project in one Eisenhower matrix, ranked by project importance and item priority.
-
Failing CI, outdated dependencies, idle repositories and dirty working trees appear as tasks beside the written ones.
-
Two front ends with the same views and actions:
pma tuiin a terminal, over SSH too, andpma webin a local browser, on 127.0.0.1 behind a one-time token. Both act on what is selected: dispatch a task, approve or reject a run, approve a plan, stop a job. Space marks tasks, andddispatches the marked ones, one run per project. On the projects tab, Space marks projects,zruns one name over them,esets their tier or tag together,xforgets a deleted project, anddorIdispatches each one's next task, orproject:cifrom theFailing CIlist.Pin a project view dispatches a prompt you type.Oopens a project by a few letters of its name or a tag,/filters any list the same way and*marks what it keeps,#scopes every view and portfolio act to a tag,vreads a run's diff in your pager,Eopens the project in$EDITORandSa shell in it, in herdr when integrated, for a fix by hand. -
A view of each project: its state and why, CI, dependencies, local changes, open tasks and every run, with how old the scan behind it is.
pma project show <name>, oroon any row. -
Projects worst first by what needs attention (
pma status), and an oldest-first list to prune (pma stale). -
Each scan says what changed since the one before: items opened and closed, CI failing or fixed, a fault found or mended, projects new.
pma historykeeps the last 100 scans, andpma status --htmlwrites the view as one page. -
Portfolio notes that belong to no single project.
Tasks in plain Markdown
-
A root
TODO.mdper repository is the only task file. Nothing to keep in step, and no lock-in: removepmaand the files still read. -
pma lintchecks the format;pma lint --fix --applyrewrites the mechanical errors.pma pruneremoves what is finished. -
pma syncmirrorsCriticalitems to GitHub Issues and ticks items whose issue was closed.
Agents, with the brakes on
-
claude,opencodeandompcome as templates. Any coding agent with a headless mode is a record you edit, not a code change. -
sandukis the same agent in a disposable container: the key stays on the host, the worktree is mounted at its own path, and the box is the bound. Needs sanduk (cargo install sanduk) and a container engine;pma agent show sandukprints what it runs. -
By default an agent edits your clone, from the working tree as it is, and its change waits there unstaged:
git diffshows it,pma reviewapproves it, and a rejection reverts it. Your own files are left alone: a rejection reverses only what the agent changed, and refuses once the clone has moved past the run.pma close <id>, orX, ends a run and touches nothing; it counts neither for nor against the agent. One run per project at a time.pma config workspace worktree, or--worktreeon one command, gives each run a worktree of the remote default branch instead, so your checkout is never touched and runs can share a project. -
The agent's environment holds no push credentials: tokens, the SSH agent, askpass helpers and the control sockets of terminal multiplexers (herdr, herdr-core, tmux, screen, zellij, kitty, WezTerm, Neovim) are removed, and git's pushes are redirected. Credentials on disk, such as
~/.sshkeys or~/.git-credentials, stay readable, and a terminal scripted through AppleScript (Ghostty, iTerm2, Terminal.app) has no variable to remove; this stops an accidental push, not a determined one.pmaruns the project's test command itself, before and after, and reports both ends. -
clauderuns with--permission-mode auto: a classifier reviews each action, and nothing stops to ask. A model or organization without auto mode starts in Manual, where-pdenies what needs approval.pma agent set claude argschanges it. A refused action does not stop a run, sopma reviewlists what the agent was denied, and such a run is not clean:band--pushleave it for you to read. -
With
pma config projects.<name>.sandbox on, that test command runs able to write only to the worktree, the temp directories and the toolchain caches: Landlock on Linux 6.2 and later, Seatbelt on macOS. Reads and the network stay open. Off by default: a suite that writes elsewhere fails under it for no fault of the agent's. -
A hook or git setting added to the repository during a run fails the run, and
pmaruns no git in that repository until it is restored, or untilpma review <id> --reject --keep-git-changesaccepts it as yours. -
Every run records the diff, the test result, the cost, the duration and the paths it touched. A run that changed a file its task had no business changing is flagged.
-
Limits you set: agents at once, dollars per batch, minutes per run. The per-run dollar figure admits runs into a batch and flags a run that cost more; no shipped worker stops at it.
-
pma reportsays what dispatching has produced: first-attempt passes, reworks, merges, cost, review time. Review time runs from a run's first reading to the decision on it, at most 30 minutes a reading. A figure given withtor--minutesreplaces it. -
An agent drafts a changelog entry per change in
.pma/changelog.md, not inCHANGELOG.md, so changes running together do not conflict;pma reviewshows the draft, or says there is none.
Running in herdr or Herdr.app
-
pma integrate herdrruns every agent in a herdr pane you can watch: a tab per run, in apma: <project>workspace. Cost, verdict and review stay as they are. With no server, a run goes on without a pane and warns.pma integrate noneturns it off. -
pma integrate herdr-appdoes the same in Herdr.app: a tab per run in apma: <project>space, opened behind the tab you are on. With the window closed, a headless run goes to herdr-core unseen, andHgives it a tab later; an interactive run needs the window. Herdr.app alerts on a blocked agent itself.pma integratenames whichever of the two is running. -
Hopens a run's pane, andTopens an interactive agent on its directory: the run's own, or the default one if the run's agent has no interactive form.I, orpma dispatch --interactive, gives you a live agent to drive for the whole run; the run ends when you exit it, and reports no cost or summary. -
An agent runs interactively from its
interactive_argsinsettings.toml, with the same placeholders asargs. An agent without them cannot. Onlyclaudeships with them:[agents.codex] command = "codex" args = ["exec", "-C", "{dir}", "-m", "{model}", "{extra}", "{prompt}"] interactive_args = ["-C", "{dir}", "-s", "workspace-write", "-a", "on-request", "-m", "{model}", "{extra}", "{prompt}"]
Talking to a run in minos
-
pma integrate minosgives each run a minos room, where you read the agent and correct it between turns. It works besideherdrorherdr-app: steer a run in its room, then take it over withT.pma integrate minos --offturns it off;pma integrateshows what is on. -
pmareads two passwords from its environment and stores neither:MINOS_PASSWORDfor the run's account (minos.user, defaultworker) andMINOS_ADMIN_PASSWORDfor the administrator who founds rooms (minos.admin, defaultdemo). An unset one is the account name, as in minosd's development accounts;pma config minos.dev_passwords offmakes it mean no room. Agents get neither. -
A worker with a
relayruns underminosb, which writes the task and each correction to its stdin;claudeships with one. Any other worker runs beside a broker and is told to read the room withminosa messages. -
minos.roomsistask(default), one room a task's runs share, orrun, one room per run. minos seats one run per room, so a second run of a task in progress goes without one. With no server, a run goes on without a room and warns.
Running unattended
-
--detachonpma dispatchandpma workflow runqueues the work and returns at once; a runner takes it and outlives the terminal.pma joblists jobs,pma watchshows what each running agent is doing, andpma config notify '<command>'runs when a job ends. -
pma workflow run --local --unattendedapproves each plan as it comes and leaves every edit that passed the project's tests as unstaged changes in your clone; one that failed is discarded. Nothing is committed or pushed.
Which model, where
-
A preset names a worker, a model and the arguments that configure it:
pma preset set omp-luna-high omp gpt-5.6-luna --thinking high. -
pmaruns agents and is not an API client. Provider keys stay the agent's, reached through its own configuration, andpmastores none of them. -
A routing policy decides the worker, the model and how much autonomy per kind of task. It is a document you propose, activate, and can replay over past runs to see what it would have changed.
Repeating work
-
A campaign applies one task definition across many repositories, each verified on its own.
-
A workflow is a graph of agents over a project: review, then validate the review, then fix what it confirmed. Written as JSON or as a script, and costed before it runs.
pma workflow libraryprints nine ready-made ones: reviews, issue triage, specification, aTODO.mdaudit and a documentation check. -
pma workflow runprints a plan: each agent node it would run, over which units, with the worker, the model and a ceiling. Nothing is spent until you approve that plan by its id, and an approval runs that plan and nothing else. Its target isdispatch's: a project, aTODO.mdline, a heading or a signal, whichever type the workflow reads. -
One run of a workflow is an instance. It is frozen at the revision it started under, so activating a new one does not change work already under way, and
--instance <id>resumes it where the last pass stopped. A node runs once every node before it has finished, so a join sees every branch. A node that edits a repository leaves a run inpma reviewlike any other. -
Each node can run on its own worker and model: a route that names the node, such as
{"match": {"node": "*/review"}, "model": "haiku", "approval": "each"}, picks them.
cargo install pmaFrom a clone: make install, which builds the release binary and copies it to ~/.local/bin; set PREFIX to install elsewhere: make install PREFIX=/usr/local. Or cargo install --path crates/pma. --no-default-features builds without pma web and its HTTP server.
Requirements:
-
macOS or Linux. Rust 1.89 or later, and a C compiler: SQLite is compiled in.
-
gitonPATH. -
A coding agent for
pma dispatch:claude,opencodeoromp, logged in or holding its own provider key. -
gh, authenticated, for CI status, for opening pull requests and forpma sync. Without it CI reads as unknown, andpma scan --offlineskips GitHub on purpose.
What is supported:
-
Forge: GitHub. CI status,
pma prandpma syncneed a GitHub remote. A repository elsewhere is still scanned, and dispatched to withstage,commitorpush; its CI reads as unknown. -
Dependencies: Cargo, uv and Go modules.
pma scan --depsand therefreshworker readCargo.lock,uv.lockandgo.mod. Other projects show no deps state. -
Test command detection: a
test:target in the Makefile, thencargo test,go test ./...,npm testwhenpackage.jsonhas atestscript, thenuv run pytestwith auv.lockorpython3 -m pytestwithout one. For anything else, or a Python project that needs an environment, setpma config projects.<name>.verify "<command>"and check it withpma verify <name>.
# TODO
## Critical
- [ ] segfault on empty input #bug gh:42
## High
- [ ] support ggml 0.9 due:2026-10-01
## Medium
### parser
- [ ] accept a trailing comma
the fixture in tests/bad.json covers it
## Low
- [x] drop python 3.9The rules, which pma lint checks:
-
The first non-blank line is
# TODO, and there is no second#heading. -
Priority comes from the enclosing
##section:Critical,High,MediumorLow, spelled exactly, at most one of each. Other##sections are allowed and ignored. -
An item is one line,
- [ ] textor- [x] text. No other spelling of the checkbox. -
Indented lines under an item are its description, carried to the agent verbatim.
-
A
###heading groups the items below it, until the next heading. -
Trailing tokens, read from the end of the line:
#tag,due:YYYY-MM-DD,gh:Nfor a linked issue, and an optional id,^k3f9q: five characters of0-9anda-zwithouti,l,ooru. A token-shaped word earlier in the line is text, and so is a caret word that is not an id, such as^1.2. -
#urgentmakes an item urgent whatever its date.#agentmarks one an agent may take.#manualkeeps agents off it entirely. -
A finished item is ticked where it stands.
pma pruneremoves it.
Two open items with the same text, or two items with the same gh:N or id, are errors. An item is identified by its id, else its issue number, else its text. Ids are optional and pma writes them: pma lint --ids --apply gives one to every open item, and an item a workflow adds gets one. With an id, rewording an item keeps its age and any run it has.
Projects and tasks:
pma lint # ./TODO.md; a directory means its TODO.md
pma lint ~/projects/*/ # every project
pma prune ~/projects/*/ # what would be removed; --apply to do it
pma root add ~/projects/ # also `pma root` and `pma root rm`
pma project # every project: tier, tags, last scanned
pma project tier 1 alpha beta # or `none`; untiered projects rank at default_tier, 5
pma project export tiers.csv # every project's tier and tags, to edit
pma project import tiers.csv --apply # read them back
pma project tag add rust myproject # private groups; --tag <t> elsewhere
pma project forget gone # a deleted project's record; `x` on the projects tab
pma project clone --tag work # check out absent projects again; --apply to do it
pma scan # TODO.md, git state, CI via gh
pma scan --offline myproject # one project, without GitHub
pma scan --deps # also measure how far each cargo, uv and go lock can move
pma next # for agents and for you; --all for every row
pma matrix # the ranked 2x2; -q q1 for one quadrant
pma status --explain # projects worst first, with what placed each
pma status --all # untiered projects too, when default_tier is never
pma status --all --html s.html # the same, with the last scan's changes, as one HTML page
pma history # past scans; `pma history last` for what the latest changed
pma stale # open items by age, oldest first
pma task myproject:12 # one task in full; Enter on it in the TUI and web
pma tui # every view and action; 1-6 switch tabs, / filters, O jumps, # scopes, ? lists keys
pma web # the same in a browser, on 127.0.0.1 behind a one-time token
pma web --app # as an app window, in Chrome or Chromium
pma project show myproject # one project: state, open tasks, runs and jobs; `o` in the TUI and web
pma web --no-open --port 9000 # for `ssh -L 9000:127.0.0.1:9000 host` from another machine
pma note add "move CI to a reusable workflow"
pma shell myproject # a shell in its clone, in herdr or Herdr.app if integrated; re-read on exitAfter the first scan you rarely need to scan again. next, matrix, status, task and dispatch re-read a project whose TODO.md or git state changed, and the TUI and web do so every 5 seconds, plus a full scan with CI every scan.every minutes (30; 0 turns it off). An unstaged edit shows at the next full scan. See docs/dev/refresh.md.
Agents, models and presets:
pma agent # the workers; `pma agent show claude` for one
pma preset set claude-haiku claude haiku
pma preset set omp-luna-high omp gpt-5.6-luna --thinking high
pma preset # every named combination; * is the default
pma preset use omp-luna-high
pma config # every setting; `pma config <key> <value>` sets one
pma verify myproject # run its check where a dispatch would, before one doesHighest wins: the -a and -m flags, then -p <preset>, then an applied route, then the default preset.
Dispatch, review, publish:
pma dispatch myproject:31 # a TODO.md line from the last scan
pma dispatch myproject:ci # failing CI; or :deps for dependencies
pma dispatch myproject:critical # every open item under that heading, as one run
pma dispatch myproject:31 myproject:40 # one run over both; --separate for one each
pma dispatch myproject # pick from a list
pma dispatch myproject --prompt "audit error handling" # your own prompt, no item
pma dispatch --auto -n 3 # the top 3 dispatchable tasks
pma dispatch -p claude-haiku myproject:31
pma review # runs not yet published or rejected
pma review 4 # task, test result, cost, summary, diff
pma review 4 --approve # or --reject, or --rework "feedback"
pma review 4 --approve --drop 3 # a bundle: leave its item 3 open
pma review 4 --reject --infra # the check or machine failed, not the agent
pma close 4 # end it and leave your files, as when it already landed
pma review 4 5 6 --approve # a batch; every run is checked before any is approved
pma stage 4 # into your clone's index, item ticked; no approval needed
pma commit 4 # stage if not yet staged, then commit in your clone; --subject=<text>
pma push 4 # commit if not yet committed, then push the commit
pma pr 4 # or commit in the worktree and open a pull request
pma push 4 --approve # approve a ready run, then push it
pma push --all-approved # every approved run; also on stage, commit and pr
pma report --by project # also class or agentA target naming one task fails if that task cannot run. A target naming many passes over each with its reason, and dispatches the rest.
The TODO.md items named in one project are one run, a bundle; --separate gives each its own. Its rules: docs/dev/bundled-dispatch.md.
A run edits the clone, or with pma config workspace worktree a worktree of the remote default branch under ~/.local/state/pma/worktrees, on a pma/ branch; in a worktree, the item must be open in the remote TODO.md, so commit and push before dispatching. Set the test command with pma config projects.myproject.verify "make check", or let it be detected. pma config projects.myproject.sandbox on confines what the check may write. docs/dev/clone-runs.md has the clone run's rules.
In a project with a CHANGELOG.md, the agent leaves that file alone and drafts one entry per separable change. pma review <id> shows the entries, or says none was drafted.
stage, commit and push work in your clone, and each runs the steps before it that the run has not done. The clone must be at the run's base, the commit its check ran on; one that has moved is refused, and pma pr remains. stage refuses a clone with staged changes. commit and push need --approve for a run not yet staged: pma review 4 --approve, or pma push 4 --approve --drop 3 as one command. In the TUI and web, u approves and pushes a ready run, asking first which items a bundle finished, and U pushes every approved run in the list. D dispatches and pushes each run whose gates are clean, as --push does. Approving, rejecting, reworking, retrying or publishing a run from its detail opens the next ready run; stage and commit stay on it, since it has a next step. push pushes the run's commit only. Design: docs/dev/stage-commit-push.md.
A run opened with pma pr is pr-open until the pull request is merged or closed; pma review settles it and shows review activity meanwhile. pma merge <id> merges it, or M in the TUI and web. If it conflicts, pma merge <id> --fix or F has an agent resolve the conflicts and returns the run to review; pma pr then updates the same pull request, and stage, commit and push refuse it. Rejecting the fix returns the run to pr-open.
Stale dependencies:
pma scan --deps # measure every lock; at least once per deps.days
pma status --explain # stale deps 153 to move, lock 51d old, ...
pma dispatch a:deps b:deps -a refresh # move each lock in a worktree; no agent
pma review 4 # the lock diff and the check's verdict
pma stage 4 # then `pma push 4`, or `pma pr 4`
pma review 5 --reject # a refresh the check refused
pma dispatch b:deps -a claude # the agent gets the check's outputA project's deps are stale when a --deps measurement no older than deps.days (30) found that a lock can move within its declared constraints, and that lock has not changed for deps.days. An older measurement places the project in no deps state, so run pma scan --deps at least that often.
The refresh worker runs pma deps refresh: cargo update, uv lock --upgrade, or go get -u ./... with go mod tidy. Under >= constraints, uv lock --upgrade takes new major versions; the project's check decides whether the result is kept. Reject a refused refresh before another worker takes the task. The next agent's prompt then carries the check's output. A refresh uses none of the agent's two attempts and none of batch_budget. The worker runs the pma on your PATH, so install the build that has pma deps refresh.
For pma dispatch --auto to send deps to refresh and everything else to your default, propose and activate a policy:
{"route": [
{"name": "locks", "match": {"class": "A"}, "agent": "refresh", "approval": "each"},
{"name": "rest", "approval": "each"}
]}Class A is mechanical work, which is the deps task alone. An applied policy refuses any workflow node that no route names, so add a node route for each workflow you run. pma workflow run warns of each node it would refuse, and pma route replay <file> shows what the policy changes over the runs already recorded. Design and rationale: docs/dev/deps-refresh.md.
Repeating work:
pma campaign add ci-workflow "add a CI workflow" --projects a --projects b
pma campaign run ci-workflow # one worktree per repository, verified apart
pma route propose routing.json # worker, model and autonomy per kind of task
pma route activate 2 # --shadow records the decision without applying it
pma route replay routing.json # what a candidate would have done differently
pma workflow library | pma workflow propose - # the shipped library, as a draft
pma workflow run todo-audit myproject # open items the code already does, as notes
pma workflow check lib.rhai # read a document and print its worst case
pma workflow propose lib.rhai # store it as a draft revision
pma workflow activate 1 # refused if its worst case is over budget
pma workflow run review myproject --dry-run # plan and price, starting nothing
pma workflow run review myproject -p claude-haiku
pma workflow run triage myproject:critical --set severity=high
pma workflow run triage --instance 3 --approve 3fa2c1e09b7d # the plan it printed
pma workflow run review-fix myproject --local --unattended # no approvals; verified fixes left unstaged
pma workflow run review-fix myproject --local --unattended --detach # returns at once
pma job # queued, running and finished jobs; `job log <id>`, `job stop <id>`
pma job approve 3 # run the plan a detached job stopped at
pma watch # each running agent's tool calls and last words
pma config notify 'notify-send pma "$PMA_JOB_SUMMARY"' # told when a job ends
# design and known gaps: docs/dev/async_dispatch.md
pma workflow run triage --instance 3 --cap max_units=80 # resume a capped instance
pma workflow stop 3 # no further node; its runs stand
pma workflow # revisions, and every instance with its stateA pass runs every node a rule decides, then stops and prints a plan for the agent nodes that are ready: as many runs as batch_budget admits at agent_budget each. --approve <plan> runs exactly that plan, max_parallel agents at a time, then stops at the next plan. A plan that changed since it was printed has another id and is refused. A unit a node could not handle is named on stderr and goes no further than a default edge; a check waiting on a pull request keeps its unit until the next pass.
GitHub Issues:
pma sync # what would change
pma sync --apply myproject # carry it outEach ## Critical item gets an issue labelled pma:critical, and gh:N is written into its line. An item whose issue is closed is ticked. Edits to TODO.md are left uncommitted, for you to read first.
-
The database is
~/.config/pma/projects.db, or$PMA_HOME/projects.db. It serves one machine: two copies cannot be merged. -
Worktrees, logs and artifacts sit under
~/.local/state/pma($XDG_STATE_HOME/pma), or$PMA_HOME/statewhenPMA_HOMEis set;PMA_STATEoverrides both. Worktrees are removed when a run is published or rejected. A workflow's agent nodes read the code in a worktree of their own and leave nothing behind; what they read and wrote stays inartifacts/<instance>/<node>/<n>/, numbered per run. -
Settings live in
~/.config/pma/settings.toml, beside the database:configkeys, roots, workers, presets, and each project's tier and tags. Edit it by hand, or withpma config <key> <value>,pma root,pma project,pma agentandpma preset, which keep its comments.pma configlists the settings and--resetclears one. An invalid file stops every command and names the key. Workflow and route revisions stay in the database, because activating one checks its cost and records who did.
One command that runs agents or edits worktrees runs at a time. dispatch, stage, commit, push, pr, workflow run and review --reject take a lock and name the process holding it. Reading commands run alongside.
make test # cargo test, then pytest on scripts/
make check # format check, clippy with warnings as errors, then testThe code is a cargo workspace. crates/pma-core holds the store, scanning, dispatch, workflows and the api module every front end uses; it prints nothing. crates/pma-tui is the terminal UI, and crates/pma the binary with the CLI. Design: docs/dev/frontends.md.
MIT.