mosa

Mosa is a local developer shell for finding, opening, and operating the projects on your machine.

It is designed to be boring about trust boundaries: project registration stays local, command output is redacted where needed, and Mosa does not upload your repository source or AI prompts.

Install

curl -fsSL https://mosa.sh/install | sh

Requirements:

• macOS or Linux
• Node.js 24
• curl or wget

The installer places versioned Mosa files under your local data directory and symlinks mosa into ~/.local/bin by default.

Quick start

mosa help
mosa roots add ~/code --kind projects
mosa dev detect
mosa dev add . --as my-app
mosa

Running mosa with no arguments opens the interactive dashboard.

Common commands

mosa where
mosa roots list
mosa dev list
mosa open
mosa up
mosa logs
mosa sql
mosa ai tools
mosa shell doctor

Use --json for script-friendly output where supported.

What Mosa does

• discovers local projects from static files such as Git metadata, package manifests, and Compose files
• registers friendly names for local checkouts
• opens project links in your browser
• wraps Docker Compose workflows for registered projects
• opens database shells/clients for detected Compose services
• manages local shell PATH/hook blocks with digest-tracked undo
• starts installed AI coding tools in the selected project directory

Local state

Mosa stores its catalog on your machine:

• macOS: ~/Library/Application Support/Mosa/mosa.sqlite3
• Linux: ${XDG_DATA_HOME:-~/.local/share}/mosa/mosa.sqlite3

The catalog stores local registrations, links, remembered aliases, and shell receipts. It does not store command output, repository source, AI prompts, plaintext Git remotes, or credentials.

Layout

.
├── install.sh             # public installer script
├── distribution/          # executable wrapper and Node runtime resolver
├── src/                   # Mosa CLI source
└── tooling/               # release archive tooling

Generated directories such as dist/, artifacts/, and release archives are ignored.

Develop

yarn install
yarn check-types
yarn test
yarn build

Pack a release archive

yarn release:pack

Release archives are written to dist/releases/. Publish them separately under https://mosa.sh/releases/; do not commit them.

License

Apache-2.0. See LICENSE.