Core concepts

Local only

Mooj runs entirely on your machine. No account, no cloud, no telemetry. The only external connection is an update check against releases.mooj.dev.

The mobile companion connects directly to your desktop over your own network (Tailscale or LAN). Pairing data and live state never touch a third-party server.

Mooj’s own state lives under ~/mooj/. The one exception is per-repo configuration — mooj.json and any lifecycle scripts you add — which lives in your main repo.

Repo

A git repository Mooj knows about. Add a repo by pointing Mooj at an existing local checkout; the path is recorded in ~/mooj/repos.json. Mooj does not copy the repo — it creates git worktrees from the original folder.

Workspace

An isolated environment for one task, built around a dedicated git worktree, with terminal sessions and processes running inside it.

Git worktree

Each workspace is backed by a git worktree — a separate checkout on its own branch, located at ~/mooj/workspaces/<repo>/<codename>/. Because every workspace has its own files on disk, switching between them is instant — no git stash, no git checkout. Dev servers and agents keep running in the background.

Codename

A short dog-breed slug (shiba-inu, goldendoodle…) that names the workspace’s on-disk path. The codename stays fixed even when the branch is renamed, so shell history and bookmarked paths remain valid.

When a workspace is created from a prompt, the branch starts named after the codename and is renamed automatically once there is enough work to summarize. When created from a branch, the branch name and codename are the same.

Terminal sessions

Tabs in the workspace pane. Each session starts in the workspace directory and survives app restart. Agent CLIs (claude, codex, …) are ordinary commands run in a session.

Ports

Each workspace reserves a block of 10 consecutive ports starting at PORT_BASE (default 10010). The block is written to .moojenv as MOOJ_PORT and related variables. With direnv installed, the values are loaded automatically in any terminal session opened in the workspace.

Where things live

~/mooj/
├── repos.json                        Registry of repos
└── workspaces/
    └── <repo>/
        └── <codename>/               One workspace (a git worktree)
            ├── .moojenv              Allocated ports + metadata
            └── …

Deleting ~/mooj/ is a clean reset. This will also delete all of your workspaces.