Singularity
One control plane for your whole fleet of coding agents for spec-driven development.
Run
pnpm bootstrap # run on first setup to generate .env (CLAUDE_BIN is detected) + wire usage-report + install + start
pnpm install # installs dependencies, runs postinstall hook
pnpm postinstall # mac: run if agents fail with "posix_spawnp failed"
pnpm start # build web + serve on http://127.0.0.1:4317
pnpm build # build web only (vite build → web/dist); serve separately with `pnpm server`
pnpm test # node --test-force-exit "server/*.test.mjs"
pnpm clean # reap orphan esbuild/vite procs (fixes build hangs before a fresh build)
Dev (with live-reload web):
pnpm dev # daemon (127.0.0.1:4317) + Vite (127.0.0.1:5317) → browse UI at 127.0.0.1:5317
Vite proxies /ws and all REST requests to daemon. Run components separately with pnpm server / pnpm web.
Backend modules → routes in server/index.mjs. Add a concern = new module + route + co-located test. New server route → also add its prefix to the Vite dev proxy (web/vite.config.mjs), or dev falls through to the SPA shell.
License
MIT
Features
- Sessions — manage and interact with live agent PTY sessions.
- Tasks — kanban board over git-worktree task sessions (worktree + branch + session per card).
- Automation — Scheduled jobs with cron expression (UTC) and Background job which picks up task by various criteria from defined tasks.
- Usage — displays 5h/7d usage meters and usage report.
- Config — view and edit
settings.json and settings.local.json.
- Hooks — view and edit hooks.
- Skills — view skills (grouped or ungrouped).
- Rules — view and edit rules.
- Memory — view and edit project memory.
- Explorer — file-tree panel: browse and edit files with tabs, create/rename/delete.
- Transcripts — view transcripts.
- History — core-sample view of daily work, drilled down per session (live WS push).
- Wiki — view wiki with linked pages.
- Appearance — theme skin + light/dark mode.
- Status — live availability of upstream provider status pages (polled).
- Settings — view and customize keyboard shortcut bindings.
- Processes — task manager for Claude processes.
Responsive layout
The shell adapts across four bands — phone (<600px), tablet (600–899px),
compact desktop (900–1199px), and desktop (>=1200px). Phone gets a mobile
header + temporary navigation drawer (no persistent rail) and a collapsible
terminal dock beneath the page; tablet and up keep a persistent icon rail
(collapsed on tablet, collapse-capable and user-preference-driven from 900px
up). Both skins (ZAPAC, Phosphor Console) ship the same structure with their
own chrome and breakpoint pixels.
Run the responsive Playwright projects (mock mode) with:
pnpm test:e2e-mock -- --project=responsive-narrowest # 320x667
pnpm test:e2e-mock -- --project=responsive-phone # 375x667
pnpm test:e2e-mock -- --project=responsive-tablet # 768x1024
pnpm test:e2e-mock -- --project=responsive-compact-desktop # 1024x768
pnpm test:e2e-mock -- --project=responsive-desktop # 1440x900
Each runs the full 15-route x 2-skin baseline contract (e2e-mock/responsive.spec.mjs);
per-feature responsive specs (e2e-mock/*-responsive.spec.mjs, shell-mobile-nav.spec.mjs,
shell-dock-responsive.spec.mjs) set their own viewports per test and run in
the default chromium project instead, since they exercise live crossings.
Security
Daemon binds loopback only. It spawns agent with full file system access. Never bind 0.0.0.0.
Optional token (defense-in-depth): set SING_TOKEN=<secret> — data endpoints + WS + the shell itself
then require it (x-sing-token header / ?token= / sing_token HttpOnly cookie). Opening the shell
with ?token= mints the cookie and 302s the token out of the URL; the daemon then injects it into the
served shell so the UI works transparently.
Notes
CLAUDE_BIN must be an absolute path in .env — the daemon does no PATH resolution and Windows node-pty needs a real exe path. pnpm bootstrap detects it for you; otherwise set it by hand.- App data (registry, tasks, cron jobs, picker roots) lives under
SINGULARITY_HOME (set in .env; pnpm bootstrap defaults it to ~/.singularity). Git worktrees + ticket requirements/plans (.worktrees/, .tickets/<id>/) live at the repo root, or SING_TRUSTED_ROOT if set (trusted, gitignored) so Claude honors the repo's permission rules.
- Per-session cost is shown as turns + total tokens +
$ — the dollar figure comes from the global statusline (harness-usage-report skill), the single source of truth for every session; a pricing-table estimate is the fallback when no statusline cost exists. pnpm bootstrap wires this skill (SessionEnd hook + statusline into ~/.claude/settings.json) and fills SING_USAGE_SKILL / SING_USAGE_REPORTS in .env; it skips a statusline you already have and never fails bootstrap if the wiring can't be written.
- The UI theme (
@zapac/mui-theme) is vendored as a tgz in vendor/, so pnpm install works anywhere — no external path dependency.
spawn failed: posix_spawnp failed on macOS/Linux means node-pty's spawn-helper prebuilt lost its execute bit (pnpm's store sometimes extracts it 0644), so every agent spawn fails. The postinstall hook (scripts/fix-pty-helper.mjs) restores +x automatically after each install; run pnpm run postinstall by hand if it recurs. This is not related to CLAUDE_BIN.
