Skip to content

This page is the short path from a clone to a merged pull request. Where code lives is in Architecture; how each feature behaves is in docs/features/. Everyone taking part follows the code of conduct; report vulnerabilities as described in SECURITY.md, not in an issue.

You need Bun (version in package.json). The desktop app is Electron in apps/desktop; it downloads its own runtime.

Terminal window
bun install --frozen-lockfile
bun run build:cli # web UI + build/mob
./build/mob serve --demo # offline model, no keys needed
bun run dev # the web UI (@mob/app) in Vite, alongside a running service
bun run dev:web # the public site (apps/web): landing, demo, account and /app
bun run desktop # Electron window around the running service

just lists the same recipes (just build, just test, just desktop, just mob serve --demo).

./build/mob tui --demo starts the OpenTUI React terminal UI, which shares packages/client with Web; bun run tui:pilot -- --url http://127.0.0.1:8787 --token-file /path/to/data/token runs it from source against an already running service. OpenTUI uses a native library via FFI, which the build embeds. See its README for input controls and limitations.

The workspace packages export TypeScript source for Bun/Vite, not a published library or a separate release artifact. UI components, browser token storage and terminal rendering are intentionally not shared.

.agents/setup prepares a Debian orb with the toolchain versions above, just installs locked dependencies and builds the CLI. Stale snapshots rerun it without reinstalling unchanged tools. .agents/resume only checks that the tools are there. Both scripts must reach main before new orbs use them. The container sandbox runtime is not installed. To expose the offline app through an orb portal:

Terminal window
amp orb service start mob --command './build/mob serve --demo' --port 8787 --portal

just test runs the core and host typecheck and tests (bun run test:core), the npm install and publish scripts’ tests (bun run test:release), the shared client headless Node typecheck and tests (bun run test:client), the UI typecheck and Vitest suite (bun run test:web), the documentation sync, typecheck and link checks (bun run test:docs), the TUI typecheck and tests (bun run test:tui), the desktop typecheck and tests (bun run test:desktop), bun run test:dsh (the optional DSH bridge’s typecheck and runtime tests; the host’s MCP tests run the bridge when its dependencies are installed—see DSH plugin setup), bun run test:site (offline public site routing checks), bun run test:integration (apps/mob/scripts/check-chat.ts, which builds the binary, starts a temporary service and reads its stream with the real AI SDK UI parser and shared client), and bun run test:runner (remote access end to end: the Worker, pairing, and the encrypted relay against the built binary). Run bun run build and bun run build:web first so test:site, test:integration and test:runner have the built web UI and public site. Individual suites such as bun run test:client, bun run test:tui and bun run test:desktop can also be run directly when changing those clients. The integration script exercises both client types, concurrent readers, reconnection, detachment, scoped approvals, stale decisions and Stop. The scriptc workflow reports how much of the host scriptc can compile; it runs after host changes reach main, weekly and by hand, never on pull requests.

Tests use temporary data directories, local fixtures and fake providers, so they need no keys and send nothing to real models, mailboxes or chats.

Changing Mob’s prompts or tool descriptions? Capture a baseline before and a candidate after with bun apps/mob/scripts/prompt-eval.ts, and compare them as Prompt evaluations describes.

Edit the source and regenerate the affected artifact. Tests reject stale output.

Artifact Source Regenerate from the repository root
docs/environment-variables.md apps/mob/src/config.ts bun run generate:configdocs
apps/web/public/logo.png apps/web/public/logo.svg rsvg-convert -o apps/web/public/logo.png apps/web/public/logo.svg (librsvg)

apps/docs builds the site at https://usemob.app/docs with Starlight. It copies README.md, CONTRIBUTING.md and docs/ in at build time, so write the Markdown as usual; links between those files become site links and links to other repository files point at GitHub. A new page under docs/ needs an entry in apps/docs/pages.ts, which sets the sidebar; the build fails without one, and on broken links.

Terminal window
bun run --cwd apps/docs dev # live preview at http://localhost:4321/docs/
bun run build:web # landing page, web UI and documentation
bun run test:site # offline routing checks against the public build

Pages follow progressive disclosure: the README and each index are short and link deeper; a feature page opens with what the feature does and how to use it, and leaves internals (APIs, storage, code paths) for its later sections or a deeper page. Changes to the public site itself are in Public site.

For documentation writing or organization, the repository skill mob-docs points to the relevant sources.

The app, landing page, demo, account page and documentation share one look: a quiet rounded workspace, with pixel art kept for the calves. Colours, radii and fonts are tokens, and bun run test:web checks the rules; see UI style before changing a stylesheet, and Taking screenshots to show the change.

  • main changes only through pull requests, squash-merged: each pull request becomes one commit whose message is the pull request title. Keep branches linear and rebase onto main rather than merging it in.
  • Pull request titles follow type(scope): description, e.g. fix(models): close reload race; the PR title check enforces it. release-please builds the changelog and the next version from them (see Releases), so a breaking change needs ! in the title. Commits inside a pull request are not checked.
  • A pull request merges once CI passed and PR title are green. The repository’s rulesets are kept in .github/rulesets/; GitHub does not read them from there, so a change to one is applied by hand under Settings → Rules → Rulesets (import the JSON) in the same pull request.
  • A pull request describes the behaviour change, links related issues, lists the checks run, and includes screenshots for UI changes.
  • Design discussion happens in issues and pull requests. Mob does not keep architecture decision records; when a change alters how a feature behaves, update its page in docs/features/ in the same pull request.
  • Schema changes raise schemaVersion in packages/core/src/chat/schema.ts and add the upgrade from the previous version to upgrades (see Releases).
  • Formatting: .editorconfig and .prettierrc.
  • Never commit provider keys, tokens or databases.

AI Elements sources in packages/app/src/ai-elements/ keep their Apache-2.0 license and provenance.