session

namespace	aiwg
name	session
platforms	["all"]
description	Start an agentic session with pre-flight health checks, auto-repair, optional MCP injection, and provider launch

AIWG Session

Start a fully-prepared agentic session. Pre-flight checks run automatically: version currency, health diagnostics, and deployment verification. Issues are auto-repaired before launch. Pass mcp to inject configured MCP servers into the provider config first.

Triggers

Alternate expressions and non-obvious activations (primary phrases are matched automatically from the skill description):

• "start a session" → aiwg session
• "launch claude" → aiwg session --provider claude
• "start with mcp" → aiwg session mcp
• "start fresh" → aiwg session (triggers full pre-flight)
• "launch codex" → aiwg session --provider codex

Trigger Patterns Reference

Pattern	Example	Action
Default launch	"start a session"	aiwg session
Explicit provider	"launch with codex"	aiwg session --provider codex
With MCP	"start with my MCP servers"	aiwg session mcp
MCP + provider	"launch cursor with MCPs"	aiwg session mcp --provider cursor
Skip repair	"just launch, skip checks"	aiwg session --no-repair

Behavior

When triggered:

1. Resolve provider: --provider flag → project config providers[0] → user config → claude

2. Pre-flight (auto-repair enabled by default):

   • Version check — updates aiwg if stale
   • Health check (aiwg doctor) — auto-repairs fixable issues
   • Deployment check — redeploys missing framework files
   • If repair fails: offers full reinstall + redeploy
   • If unresolvable: surfaces aiwg feedback --type bug

3. MCP inject (when mcp subcommand is used):

   aiwg mcp inject --provider <provider>
   

4. Launch:

   • Spawnable providers (claude, codex, opencode): launches the binary directly
   • IDE providers (cursor, windsurf, copilot, factory, warp): prints ready instructions

Examples

Example 1: Default session

User: "Start a session"

Action:

aiwg session

Flow: version check → doctor → deployment check → launch claude

Example 2: Session with MCP

User: "Start a session with my MCP servers"

Action:

aiwg session mcp

Flow: version check → doctor → deployment check → aiwg mcp inject --provider claude → launch claude

Example 3: Specific provider

User: "Launch with codex and inject MCPs"

Action:

aiwg session mcp --provider codex

Example 4: IDE provider (Cursor)

User: "Set up my cursor session"

Action:

aiwg session --provider cursor

Flow: full pre-flight for cursor → deployment check for .cursor/ → aiwg mcp inject --provider cursor (if mcp requested) → prints "Open Cursor in your project directory"

Example 5: Skip repair

User: "Just launch, skip the health checks"

Action:

aiwg session --no-repair

Clarification Prompts

If the user's intent is ambiguous:

• "Which provider should I launch? (claude, codex, opencode, cursor, ...)"
• "Should I inject your configured MCP servers before launching?"

References

• @$AIWG_ROOT/src/cli/handlers/session.ts — Session command handler
• @$AIWG_ROOT/src/cli/agent-spawn.ts — Provider launch map
• @$AIWG_ROOT/docs/cli-reference.md — CLI reference (session section)