Key Files — Map Of Responsibility

A curated atlas. Not exhaustive — but every file here matters.

If you read these in order, you'll build the right mental model. Each entry has a one-line purpose. Path is from the repo root.

1. Roadmap & Conventions (read first)

Path	Why it matters
`README.md`	The product positioning + supported agents matrix
`AGENTS.md`	Project-wide rules (Bun, Biome, plan placement, MCP, slash commands, structure)
`apps/desktop/AGENTS.md`	Electron-specific: subscriptions must be observables, not async generators
`apps/desktop/HOST_SERVICE_ARCHITECTURE.md`	Why host-service exists, what it owns, the deployable-process bet
`apps/desktop/HOST_SERVICE_BOUNDARIES.md`	What is not in host-service — the negative space
`apps/desktop/HOST_SERVICE_LIFECYCLE.md`	Spawn / adopt / release / stop — manifest-based process management
`apps/desktop/V2_WORKSPACE_CREATION.md`	The fork/checkout/adopt model + branch picker design
`apps/desktop/V2_WORKSPACE_DIFF_VIEWS.md`	Fork-point vs latest comparisons + why hardcoded `origin/main` was wrong
`apps/desktop/V2_WORKSPACE_SETUP_SCRIPTS.md`	OSC 133 shell readiness + queued initial commands
`apps/api/MCP_TOOLS.md`	The 15 MCP procedures the cloud exposes

2. Entry Points

Path	Role
`apps/desktop/src/main/index.ts`	Electron main — window, tray, host coordinator
`apps/desktop/src/preload/index.ts`	contextBridge between main and renderer
`apps/desktop/src/renderer/index.tsx`	Renderer bootstrap — TanStack Router + tRPC clients
`apps/desktop/src/renderer/routes/__root.tsx`	Route root
`apps/desktop/src/renderer/routes/_authenticated/layout.tsx`	Authenticated dashboard layout
`packages/host-service/src/app.ts`	`createApp({ config, providers })` factory
`packages/host-service/src/serve.ts`	Standalone host-service entry point
`packages/pty-daemon/src/main.ts`	PTY daemon entry point (Node-only)
`apps/api/src/app/api/trpc/[trpc]/route.ts`	Cloud tRPC handler
`apps/api/src/app/api/auth/[...all]/route.ts`	Better Auth catch-all
`apps/api/src/app/api/agent/[transport]/route.ts`	MCP transport (sse/ws/stdio)
`apps/relay/src/index.ts`	Relay tunnel WS server
`apps/electric-proxy/src/index.ts`	Electric SQL proxy (Cloudflare Worker)
`packages/sdk/src/index.ts`	Public SDK

3. Architecture — Core Routing & IPC

Path	Role
`apps/desktop/src/lib/trpc/routers/index.ts`	Full IPC router tree (~35 groups)
`apps/desktop/src/lib/trpc/routers/workspaces/procedures/create.ts`	"New workspace" entry — dispatches to host-service
`apps/desktop/src/lib/trpc/routers/workspaces/utils/git.ts`	Worktree helpers (`createWorktreeFromPr`, `worktreeExists`)
`apps/desktop/src/lib/trpc/routers/terminal/terminal.ts`	`createOrAttach` — terminal launch into a worktree
`apps/desktop/src/main/lib/host-service-coordinator.ts`	Spawn / adopt / release / stop host-services per org
`packages/host-service/src/trpc/router/workspace-creation/`	Host-side `create`/`checkout`/`adopt`/`searchBranches`/`getProgress`
`packages/host-service/src/terminal/terminal.ts`	Host-side terminal session WS routes
`packages/host-service/src/runtime/`	Workspace init progress tracking

4. Renderer / UI

Path	Role
`apps/desktop/src/renderer/stores/tabs/store.ts`	Pane/tab tree per workspace (Zustand)
`apps/desktop/src/renderer/stores/workspace-init.ts`	Workspace creation progress + pending terminal setups
`apps/desktop/src/renderer/stores/new-workspace-modal.ts`	Modal draft + pending workspace state
`apps/desktop/src/renderer/routes/_authenticated/_dashboard/v2-workspace/[id]`	Active workspace page (terminals + diffs)
`apps/desktop/src/renderer/routes/_authenticated/_dashboard/pending/[id]`	Workspace creation progress page
`apps/desktop/src/renderer/providers/CollectionsProvider/`	Cloud-synced collections via Electric
`packages/panes/src/core/store/store.ts`	Pane/tab/split layout store
`packages/panes/src/react/components/Workspace/`	Workspace + Tab + TabBar + Pane components
`packages/ui/src/`	shadcn/ui shared primitives

5. Agent Orchestration & LLM

Path	Role
`packages/shared/src/agent-prompt-template.ts`	Read this. Default task + context templates
`packages/shared/src/agent-prompt-launch.ts`	`buildPromptCommandString` — heredoc with random delimiter
`apps/desktop/src/renderer/lib/agent-session-orchestrator/agent-session-orchestrator.ts`	Dispatches chat vs terminal launches, idempotency
`apps/desktop/src/renderer/lib/agent-session-orchestrator/adapters/terminal-adapter.ts`	Terminal launch — attachment limits, prompt assembly
`apps/desktop/src/renderer/lib/agent-session-orchestrator/adapters/chat-adapter.ts`	Chat launch — Mastracode handoff
`apps/desktop/src/main/lib/agent-setup/desktop-agent-setup.ts`	21 setup actions for agent wrappers + hook scripts
`apps/desktop/src/main/lib/agent-setup/agent-wrappers-claude-codex-opencode.ts`	Hook injection into `~/.claude/settings.json` etc.
`packages/host-service/src/trpc/router/settings/agent-presets.ts`	The 9+ agent matrix (claude/codex/cursor/gemini/mastra/...)
`packages/chat/src/server/trpc/service.ts`	Chat runtime initialization (`createMastraCode`)
`packages/chat/src/server/trpc/utils/runtime/runtime.ts`	Lifecycle hooks (`UserPromptSubmit`, `Stop`, etc.)
`packages/chat/src/server/trpc/utils/runtime/superset-mcp.ts`	MCP client → Mastra tool injection
`packages/chat/src/server/shared/small-model/get-small-model.ts`	Small-model resolver (Haiku / 4o-mini, OAuth auth chain)
`packages/chat/src/server/desktop/title-generation/title-generation.ts`	Title-generation Mastra Agent (system: "You generate concise titles.")
`packages/mcp/src/tools/index.ts`	MCP v1 — 17 tools
`packages/mcp-v2/src/tools/register.ts`	MCP v2 — adds automations, including `set_prompt`/`get_prompt`
`packages/mcp-v2/src/tools/automations/create.ts`	Example tool definition (Zod schema → caller)
`packages/host-service/src/runtime/chat/chat.ts`	Host-side chat runtime (mirrors chat package server)

6. Cloud / Data

Path	Role
`packages/db/src/schema/schema.ts`	Main cloud schema (lines: 56 task statuses, 94 tasks, 174 integrations, 262 device_presence, 299 agent_commands, 429 v2_hosts, 565 v2_workspaces, 661 chat_sessions, 709 automations)
`packages/db/src/schema/auth.ts`	Auth schema (users/sessions/orgs/members/accounts)
`packages/local-db/src/schema/schema.ts`	Local SQLite (projects 26, worktrees 68, workspaces 103)
`packages/auth/src/server.ts`	Better Auth config + plugins + user-creation hook
`packages/auth/src/stripe.ts`	Stripe integration
`packages/trpc/src/root.ts`	`appRouter` — aggregates 17 routers
`packages/trpc/src/trpc.ts`	`createTRPCRouter`, `protectedProcedure`
`packages/trpc/src/router/task/task.ts`	Task router with external-sync fields
`packages/trpc/src/router/automation/automation.ts`	Automation CRUD + dispatch
`apps/api/src/trpc/context.ts`	tRPC context builder
`apps/api/src/app/api/chat/[sessionId]/stream/route.ts`	SSE proxy to Durable Streams
`apps/api/src/app/api/chat/lib.ts`	`appendToStream`, `streamUrl`, protocol headers
`apps/api/src/app/api/integrations/slack/events/utils/run-agent/index.ts`	Slack mention → agent dispatch

7. Tooling

Path	Role
`package.json` (root)	Bun workspaces, scripts, turbo
`turbo.jsonc`	Task graph + globalEnv
`biome.jsonc`	Lint/format config
`bunfig.toml`	Bun config
`Caddyfile.example`	Local TLS reverse proxy for *.localhost
`scripts/lint.sh`	Biome check
`scripts/check-desktop-git-env.sh`	Validate git env for desktop devs
`scripts/check-git-ref-strings.sh`	Bans `.startsWith("origin/")` outside `refs.ts`
`scripts/postinstall.sh`	Post-bun-install hooks
`scripts/release-canary.sh`	Canary release path
`apps/desktop/electron-builder.ts`	Production build config
`apps/desktop/electron-builder.canary.ts`	Canary channel build config

8. Slash Commands & Skills (`.agents/commands/`)

(Each is a markdown skill referenced by /skill-name.)

Command	Purpose
`ci-check`	lint:fix + typecheck + test + sherif
`clean-neon-branches`	Delete old Neon DB branches (preserves prod)
`task-run`	Create task + workspace + start AI agent
`deslop`	Clean code philosophy — remove gratuitous comments
`respond-to-pr-comments`	Fetch + prioritize + address PR review comments
`create-pr` / `pr:create-pr`	Persona/goal-driven PR creation
`task`	Create task via Superset MCP
`create-plan`	Superset Execution Plans
`refresh-compare-pages`	Regenerate marketing /compare pages
`init`	Initialize CLAUDE.md
`review` / `security-review` / `ultrareview`	Multi-agent reviews

.claude/commands and .cursor/commands are symlinks to ../.agents/commands so all CLI agents see the same set.

9. Notable Plans (`plans/`)

Plan	What it does
`plans/v2-chat-greenfield-architecture.md`	Event-sourced chat (worth reading top to bottom)
`plans/done/v2-workspace-context-composition.md`	Structured agent launch spec — shipped
`plans/done/20260417-v2-project-create-import-impl.md`	Fork/checkout/adopt branches — shipped
`plans/20260501-linear-team-entity.md`	Linear teams + OAuth refresh (urgent + invasive)
`plans/20260502-bun-dev-server-cleanup.md`	Orphan dev process leaks
`plans/20260430-pane-store-registry-pr3.md`	Pane state architecture
`plans/20260430-v2-delete-workspace-audit.md`	Workspace deletion correctness
`plans/20260427-posthog-v1-v2-dashboard.md`	Analytics for v1 vs v2 paths
`plans/20260425-host-attachments-pr2.md`	File attachment lifecycle
`plans/20260422-v2-notification-hooks-client-side.md`	Notifications move to renderer
`plans/20260422-v2-remote-ports.md`	Remote-host port assignment
`plans/20260417-automations.md`	Automation dispatch flow

10. Prompt Index (Verbatim)

The actual strings Superset emits to agents.

Where	Prompt
`packages/shared/src/agent-prompt-template.ts:62`	`DEFAULT_TERMINAL_TASK_PROMPT_TEMPLATE` — task header + "Work in the current workspace …"
`packages/shared/src/agent-prompt-template.ts:64+`	`DEFAULT_CHAT_TASK_PROMPT_TEMPLATE` — task header + "take the next concrete step"
`packages/shared/src/agent-prompt-template.ts:154`	`DEFAULT_CONTEXT_PROMPT_TEMPLATE_SYSTEM` (empty by default — agent's own system prompt preserved)
`packages/shared/src/agent-prompt-template.ts:160`	`DEFAULT_CONTEXT_PROMPT_TEMPLATE_USER` — `{{userPrompt}}\n\n{{tasks}}\n\n{{issues}}\n\n{{prs}}\n\n{{attachments}}`
`packages/chat/src/server/desktop/title-generation/title-generation.ts:61`	`"You generate concise titles."`
`apps/desktop/src/main/lib/agent-setup/agent-wrappers-claude-codex-opencode.ts:68-93`	`[ -n "$SUPERSET_HOME_DIR" ] && [ -x "$SUPERSET_HOME_DIR/hooks/notify" ] && "$SUPERSET_HOME_DIR/hooks/notify" \|\| true` (hook script body)

The biggest "prompt" surface, however, is what flows from the user: tasks, issues, PRs, attachments — composed via LaunchSource[] → LaunchSpec, rendered through per-agent Mustache templates.

11. The Top 15 (If You Only Read 15 Files)

For a deep but bounded read, in order:

README.md
AGENTS.md
apps/desktop/HOST_SERVICE_ARCHITECTURE.md
apps/desktop/HOST_SERVICE_BOUNDARIES.md
apps/desktop/V2_WORKSPACE_CREATION.md
apps/desktop/src/main/index.ts
packages/host-service/src/app.ts
packages/host-service/src/serve.ts
apps/desktop/src/main/lib/host-service-coordinator.ts
apps/desktop/src/lib/trpc/routers/workspaces/procedures/create.ts
packages/shared/src/agent-prompt-template.ts
packages/shared/src/agent-prompt-launch.ts
packages/host-service/src/trpc/router/settings/agent-presets.ts
apps/api/MCP_TOOLS.md
plans/v2-chat-greenfield-architecture.md