capitaneria

capitaneria is a command-line roll call for a suite of nine tools (vedetta, dogana, paratia, varo, rada, faro, boa, plancia, agent-switch) that keep several coding agents from colliding on one machine. It exists because each of the nine was built in its own session over about two weeks, none of them aware of the others, so nothing on the machine could say in one place which are reachable, which have something running right now, what commit they are on, and which have uncommitted work.

What it does not do

• It does not install any of the nine tools. capitaneria menubar prints plain text when SwiftBar is not installed rather than installing it for you.
• It does not run a daemon and does not copy or persist anyone’s state.
• It does not ask a tool whether it is running. It asks the process table directly, because a tool that could misreport its own status is the one place that answer should not come from.
• It does not do any of the work the nine tools do. It only counts, limits and shows.

Install

git clone https://github.com/nerln/capitaneria.git
cd capitaneria
pip install .

That registers the capitaneria command through the package’s project.scripts entry point. The package has no runtime dependencies: everything it needs is in the Python standard library.

Use

capitaneria              # who is reachable, who is running, who is dirty
capitaneria apri faro    # opens the interface of whichever tool has one
capitaneria chiudi plancia
capitaneria json         # for another program to read
capitaneria menubar      # the line SwiftBar or xbar expect

For the menu bar, a symlink into SwiftBar’s plugin folder is enough:

ln -s ~/.local/bin/capitaneria ~/Library/Application\ Support/SwiftBar/capitaneria.30s.sh

How it works

Reachability is checked with shutil.which, against the process’s own PATH. The first run got this wrong: it looked only in ~/.local/bin, a folder capitaneria chose itself, and declared vedetta unreachable even though it was installed through pip inside miniforge and ran fine when typed by hand. An inventory that reports a tool missing when it is already there is worse than no inventory, because it sends you to reinstall something you have. Reachability now means what it means for you: whatever shutil.which finds on the real PATH.

Everything else it reports, whether a tool has something running, what commit it is on, whether it has uncommitted changes, is read the same way: from the process table and from git, not from a status the tool volunteers about itself.

capitaneria on GitHub, MIT licensed.