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.
bun install --frozen-lockfilebun run build:cli # web UI + build/mob./build/mob serve --demo # offline model, no keys neededbun run dev # the web UI (@mob/app) in Vite, alongside a running servicebun run dev:web # the public site (apps/web): landing, demo, account and /appbun run desktop # Electron window around the running servicejust lists the same recipes (just build, just test, just desktop,
just mob serve --demo).
Terminal UI
Section titled “Terminal UI”./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.
Amp orbs
Section titled “Amp orbs”.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:
amp orb service start mob --command './build/mob serve --demo' --port 8787 --portaljust 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.
Prompt evaluations
Section titled “Prompt evaluations”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.
Generated references
Section titled “Generated references”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) |
Documentation site
Section titled “Documentation site”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.
bun run --cwd apps/docs dev # live preview at http://localhost:4321/docs/bun run build:web # landing page, web UI and documentationbun run test:site # offline routing checks against the public buildPages 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.
UI style
Section titled “UI style”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.
Changes
Section titled “Changes”mainchanges only through pull requests, squash-merged: each pull request becomes one commit whose message is the pull request title. Keep branches linear and rebase ontomainrather than merging it in.- Pull request titles follow
type(scope): description, e.g.fix(models): close reload race; thePR titlecheck 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 passedandPR titleare 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
schemaVersioninpackages/core/src/chat/schema.tsand add the upgrade from the previous version toupgrades(see Releases). - Formatting:
.editorconfigand.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.