ctx-launcher (wl)

Overview

A .NET 10 CLI tool that launches GitHub Copilot CLI sessions from workspace definitions. The binary is wl. Workspaces live under ~/.wl-workspaces/<name>/ (override with WL_WORKSPACES_ROOT) containing workspace.json, AGENTS.md, and .copilot/skills/. wl launch with no name runs folder mode in the current directory. Published on GitHub at fotis89/ctx-launcher and on npm as @ctx-launcher/wl.

Docs: docs/reference.md (how wl works — keep it in sync with the code) and CHANGELOG.md. The finished v0.10 plan is in docs/design/v0.10-plan.md.

Architecture

• Program.cs — top-level statements, System.CommandLine wiring, tab completion, Run() maps expected exceptions to exit code 1. Services are created here (no DI container).
• Commands/ — thin handlers: Launch, Which, Create, Clone (primary constructors, no base class). Program.cs splits args at the first -- into Copilot pass-through; bare wl prints help.
• Services/
  • WorkspaceService — workspace discovery/load/save and validation (schemaVersion: 2, required fields).
  • CopilotService — Copilot-specific launch logic: BuildArgs(LaunchSpec), PrepareLaunch (plugin.json manifests), GetEnvironment (COPILOT_CUSTOM_INSTRUCTIONS_DIRS), DescribeLaunchPrep (non-mutating, used by wl which), InvokeCreateSkill. Accepts a workspace or folder mode.
  • LaunchService — resolves paths from the workspace folder, prompts for undefined variables, builds args via CopilotService, reads/writes .last-session and .folder-sessions.json, spawns via CopilotRunner.
  • CopilotRunner — resolves and spawns copilot (virtual Run for tests), TryGetVersion.
  • PathsService (.paths.json variables; refuses to save after a failed load, atomic writes), SetupService (installs embedded skills, merges .gitignore), VersionService.
• Models/ — Workspace (computed paths), LaunchSpec/LaunchArgs, WlJsonContext (source-gen JSON for AOT).
• Helpers/ — WlPaths (single source of truth for the folder layout), PathHelper (ResolvePath, QuotePath, FindCommandOnPath, Slugify), ConsoleLabel.

Key decisions

• Sessions resume by default. Fresh launches pass --name=<folder>-<8 hex> (-temp- for --temp) and --session-id=<uuid>; resume passes --resume=<saved id>. Argument order: wl args, then copilotArgs, then pass-through. The UUID is saved to .last-session (plain text) only after Copilot exits 0, so /rename can't break resume.
• Args are raw, unquoted strings passed through ProcessStartInfo.ArgumentList. QuotePath is display-only (wl which).
• Each .copilot/ dir with skills is passed as --plugin-dir; wl generates its plugin.json (workspace plugin name wl-<slug>-<hash>, shared plugin wl-shared). No implicit skill discovery.
• The workspace AGENTS.md (and optional .shared/AGENTS.md) are user-edited and loaded by Copilot because wl appends .shared (only when .shared/AGENTS.md exists) and then the workspace folder to COPILOT_CUSTOM_INSTRUCTIONS_DIRS (inherited entries preserved). wl never writes them.
• wl create [name] runs Copilot with the shared wl-workspace skill.
• Skills are embedded resources in src/wl/Resources/*.md (loaded via GetManifestResourceStream). EnsureInstalled writes wl-workspace to ~/.wl-workspaces/.shared/.copilot/skills/ on first launch/create/clone after a version change. Keep them in sync with /sync-skills.

Conventions

• File-scoped namespaces, primary constructors for commands
• Official dotnet new editorconfig template, format with dotnet format
• No DI container — services instantiated in Program.cs
• Unit tests (tests/wl.tests) cover helpers and services; commands are covered by E2E tests (tests/wl.e2e.tests) that run the native binary against a fake copilot shim.
• Native AOT publishing (PublishAot=true), ~4 MB binary

Build and test

• Build: dotnet build
• Unit tests: dotnet test tests\wl.tests\wl.tests.csproj (must pass with 0 warnings) — see /run-tests
• E2E: needs a published binary and an absolute WL_BINARY_PATH
• Local install: .\scripts\install-local.ps1 (builds HEAD in a clean worktree, runs both suites, installs to %LOCALAPPDATA%\Programs\wl\<version> behind a current junction) — see /publish
• Publish AOT manually: requires MSVC build tools; add C:\Program Files (x86)\Microsoft Visual Studio\Installer to PATH so vswhere is found.

Release

• /release: tag vX.Y.Z on master and push; CI builds all platforms, publishes the npm packages, and creates the GitHub release. Don't run npm publish or gh release create by hand.
• The tag must point at the pushed master commit — if you amend after tagging, re-tag.